CI gates and SARIF export

Run secfoo in a pipeline, fail the build on what it finds or on what it spends, and send the findings to GitHub code scanning.

Gate a build

secfoo run --skill sast --skill secret-scanning --agent api --target . \
  --fail-on high --max-cost 2.00 --json > secfoo-result.json
--fail-oncritical | high | medium | low. Fails if any run reports a finding at that severity or worse. Counts come from the report's severity headings, not from prose.
--max-costA USD cap on the summed AI spend for this invocation, checked after the runs finish (agents report cost on completion).
--jsonOne JSON document on stdout: per-skill status, severity counts, tokens, USD, gate verdicts and the exit code. Progress goes to stderr. Also skips the interactive project-name prompt.

Set them once for every run instead:

# ~/.secfoo/config.toml
[defaults]
fail_on = "high"
max_cost_usd = 2.00

Exit codes

CodeMeaning
0Every run succeeded and no gate tripped.
1A run failed or timed out. A partial scan never passes, even if the gates would have.
2All runs succeeded, but the --fail-on findings gate tripped.
3All runs succeeded, but the --max-cost gate tripped. Wins over 2 if both trip.

So CI can tell "the scan broke" (1) from "the scan worked and found something" (2) from "the scan cost too much" (3) without parsing output.

Where the cost numbers come from

secfoo records what each agent reports. It doesn't estimate.

apiLiteLLM's cost for the model used.
claude, opencodeThe cost the CLI reports in its JSON output.
codex, geminiToken counts only.
agent, agyNothing reported.

A run with no reported cost is counted as unpriced, in the JSON and in secfoo cost. It's never treated as $0, so it can't quietly pass a --max-cost cap. To see spend across past runs:

secfoo cost                         # by agent
secfoo cost --by skill --since 2026-09-01
secfoo cost --by project --project payments

Upload to GitHub code scanning

After a SAST, SCA or secret-scanning run, its findings are in secfoo's local store. Export them as SARIF 2.1.0 and upload them in the same job, since the scan, the export and the upload must share one runner and one store:

name: secfoo
on: [pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install "secfoo[api]"
      - name: Scan
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          secfoo run --skill sast --skill secret-scanning --agent api --target . \
            --project-name my-app --fail-on high --max-cost 2.00 --json > secfoo-result.json
      - name: Export findings
        if: always()
        run: secfoo findings export --format sarif --project 1 -o findings.sarif
      - uses: github/codeql-action/upload-sarif@v4
        if: always()
        with:
          sarif_file: findings.sarif
          category: secfoo

On a fresh runner the scanned project is local ID 1. Export one project at a time, so paths belong to the checked-out repository. Code scanning must be enabled for the repository. if: always() uploads the findings even when the gate fails the scan step.

What's in the SARIF

  • Rules are grouped by skill, CWE and severity. Findings without a CWE still get a rule, and CWE tags use external/cwe/cwe-N.
  • Critical and high map to error, medium to warning, low and informational to note. Their security-severity values (9.0, 7.0, 4.0, 1.0, 0.0) are categorical, not calculated CVSS scores.
  • A missing file or invalid line number drops that location rather than inventing one.
  • Only open findings are exported by default. --status all includes closed ones as results too, so leave it off for uploads.

JSON Lines, and keeping paths private

Without --format, the export is JSON Lines: one record per finding, with its skill, severity, language, framework and a code-free description of the vulnerable construct. It's the same shape for every skill, ready for another tool.

secfoo findings export                                   # open findings, every skill, to stdout
secfoo findings export -s sast --status all              # one skill, open and closed
secfoo findings export --no-locations -o findings.jsonl  # drop paths, lines, region hashes
--no-locations removes locations, not text
It drops file paths, line numbers, code-region hashes and reachability evidence. Finding titles and descriptions are not redacted.

See secfoo run and secfoo findings export in the CLI reference for every flag.