CLI Reference

CLI Reference

coretrace-python-analyzer [--check | --emit-ir [--ssa]] [options] [path]

Option	Effect
--check	Run the loaded plugins on path and report their findings.
path	A Python file, or a directory analysed as a project.
--format {text,json,sarif}	Report format, text by default.
--fail-on SEVERITY	Exit 1 only from this severity up: info, low, medium, high, critical. Default: any finding.
--baseline PATH	The accepted findings: written on the first run, then only findings not recorded there fail the check.
--plugins DIR	Load the plugins found under DIR on top of the bundled ones. Repeatable.
--no-bundled-plugins	Do not load the plugins shipped with the package.
--cache DIR	Keep per-module results under DIR and reuse them for unchanged modules.
--jobs N	Analyse independent modules in N processes.
--sbom PATH	Write a CycloneDX bill of materials of the dependencies.
--vex PATH	Write an OpenVEX document: whether each advisory affecting a requirement affects the project.
--advisories FILE	Read a local advisory file in addition to advisories.json at the root. Repeatable.
--policy FILE	Apply this dependency policy instead of coretrace-policy.toml at the root.
--import-advisories SRC OUT	Convert an OSV dump into the local advisory file OUT, then exit.
--emit-ir	Print the intermediate representation of path instead of checking it.
--ssa	With --emit-ir, print the static single assignment form.
--help	Show the options and exit.

Directory-only options

--cache, --jobs, --sbom, --vex, --advisories and --policy apply to a directory check.

This is not an arbitrary restriction: dependency files, project templates and the module graph only exist for a project. A single-file check reads no template, so it never establishes escaping, and it has no dependency graph to correlate advisories against.

Examples

# Project check, human output
coretrace-python-analyzer --check src/

# CI: report everything, fail from high up, feed code scanning
coretrace-python-analyzer --check src/ --fail-on high --format sarif > coretrace.sarif

# Large project: cache between runs, four processes
coretrace-python-analyzer --check src/ --cache .coretrace --jobs 4

# Supply chain artifacts alongside the check
coretrace-python-analyzer --check src/ --sbom sbom.json --vex vex.json

# Adopt on an existing code base
coretrace-python-analyzer --check src/ --baseline coretrace-baseline.json

# Look at the IR of one file
coretrace-python-analyzer --emit-ir --ssa src/app.py

From Python

from pathlib import Path
from coretrace_python import engine

analysis = engine.analyze_project(Path("src"), [engine.BUNDLED_PLUGINS])
for finding in analysis.findings:
    print(finding.rule_id, finding.span.source_id, finding.span.start_line, finding.message)
print(analysis.coverage.summary())

analyze_project accepts the same options as the command line (cache, jobs, advisory_files, policy_file). analyze_file checks one SourceFile loaded through SourceManager.