Command line

Usage

quantum-scan <target-directory> [options]

The target directory is required and is scanned recursively. Everything else has a default.

Options

Flag	Default	Effect
--format <fmt>	markdown	One of markdown, json, sarif, cbom. See output formats.
--out <path>	depends on format	Where to write the report.
--source-only	off	Skip tests, vendored code, fixtures and documentation.
--fail-on <level>	off	Exit 2 if any reportable weakness is at or above this severity: none, info, low, medium, high, critical. Inventory findings never fail a build.
--baseline <report.json>	none	Treat findings already present in that earlier JSON report as accepted. Only new findings gate.
--ignore <glob>	none	Skip matching paths. Repeatable.
-h, --help	—	Print usage and exit 0.

Exit codes

Code	Meaning
0	Scan completed. Either no threshold was set, or it was not exceeded.
1	Usage error or scan failure: missing target, unreadable directory, bad flag.
2	Scan completed and the --fail-on threshold was exceeded.

Exit 1 and exit 2 are distinct on purpose. A broken pipeline and a failed gate need different responses, and collapsing them means a misconfigured scanner looks like a clean repository.

Suppression

Three mechanisms, in increasing order of scope. All three are counted in the report, so nothing disappears quietly.

Inline, on the finding

Keeps the justification next to the code, where a reviewer sees it.

def cache_key(blob):
    return hashlib.md5(blob).hexdigest()  # quantum:ignore[CRYPTO-HASH-BROKEN-001] cache key, not security

Accepted on the finding's line or the line directly above it. Prefer the bracketed form with a rule id: a bare quantum:ignore will also hide a different rule that lands on that line later.

Path exclusion

A .quantumignore file in the scan root, loaded automatically:

vendor/
third_party/
*_test.go
docs/examples/

The same thing can be passed per run with --ignore, which is repeatable:

quantum-scan . --ignore vendor/ --ignore "*_test.go"

Baseline

For an existing codebase, accept what is there today and gate only on what is added. This is the mechanism that makes adoption possible on a mature repository.

quantum-scan . --format json --out .quantum-baseline.json --source-only
quantum-scan . --format json --out new.json --baseline .quantum-baseline.json --fail-on high

Run against the scanner's own sample project, the first command records 50 matches and the second exits 0 with "baselined": 50 and no reportable findings. Without the baseline, the same scan exits 2.

Examples

# human-readable report for review
quantum-scan . --out report.md --source-only

# gate a build on anything high or above
quantum-scan . --format json --out quantum.json --fail-on high

# upload to the GitHub Security tab
quantum-scan . --format sarif --out quantum.sarif --source-only

# cryptographic inventory for auditors
quantum-scan . --format cbom --out quantum-cbom.json --source-only

# only gate on new findings
quantum-scan . --format json --out new.json --baseline accepted.json --fail-on high

Performance

Scanning is line-based and single-pass, so it is fast enough to sit in a pre-commit hook. The Functor repository, 137 source files with --source-only, scans in 0.12 seconds on an Apple laptop. Memory use is proportional to the largest file, not to the repository.