Reports and CI

Reports and CI

Formats

--format {text,json,sarif}, text by default.

• text — one finding per line, then a count and a coverage line.
• json — findings with full metadata, per-file detail, and the suppressed and baselined lists.
• sarif — for GitHub code scanning; suppressed results are marked suppressed in source, and baselined ones carry baselineState: unchanged while new ones are marked new.

Supply-chain artifacts are produced alongside a directory check:

• --sbom PATH — a CycloneDX bill of materials of the dependencies.
• --vex PATH — an OpenVEX document stating, for each advisory affecting a requirement, whether it affects the project.

Reports name what produced them

A directory check records what its result was produced with, besides the engine and the sources: every plugin it loaded (manifest name and version) and every advisory file it read (by path), each with the SHA-256 digest of its content.

Format	Where
JSON	tool.components
SARIF	tool.extensions
CycloneDX SBOM	metadata.tools.components, with their hashes
OpenVEX	the document's tooling, so its @id changes with the advisory data

Every finding about an advisory names the plugin (name@version) or advisory file it comes from, in its advisory_source metadata. The cache key and the reports identify a plugin by the same digest, so a report can be traced back to the exact inputs that produced it.

Exit status and gating

Status	Meaning
0	Nothing reported
1	Findings reported
2	Usage or analysis error

--fail-on SEVERITY keeps reporting everything but fails only from that severity up: info, low, medium, high, critical.

Adopting on an existing code base

coretrace-python-analyzer --check src/ --baseline coretrace-baseline.json

The first run writes the file with every current finding and passes. Later runs set the recorded findings apart and fail only on new ones.

A finding is recognised by its file, its rule, its function and the text of its line — not by its line number. Code inserted above it does not make it new; a change to the line itself does.

Commit the file and shrink it as findings are fixed: an entry without a matching finding is simply unused.

GitHub Actions

- run: pip install coretrace-python-analyzer
- run: coretrace-python-analyzer --check src/ --fail-on high --format sarif > coretrace.sarif
  continue-on-error: true
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: coretrace.sarif

continue-on-error: true on the analysis step is what lets the SARIF be uploaded even when the gate fails the job — otherwise the run that stops the build is the run whose findings get lost.

Add --cache on a directory restored between runs to analyse only what changed; see Performance and Caching.