SBOMFlow Exit Codes

SBOMFlow uses stable exit codes for CI and operator scripts.

Codes 130/141 are emitted only by the installed sbomflow console entry point (and python -m sbomflow), which wraps the command runner to turn normal operator interruptions into conventional shell codes without a traceback. The programmatic sbomflow.cli.main(...) still raises KeyboardInterrupt / BrokenPipeError for callers and tests.

141 holds regardless of how stdout is buffered. Redirected output (> file, | head, a CI log) is block-buffered, so nothing is written until a flush; the console entry point performs that flush itself rather than leaving it to interpreter shutdown, where the failure would land outside every handler and the process would exit 120 with Exception ignored while flushing sys.stdout. 120 is not an SBOMFlow exit code and appears nowhere in this table.

No subcommand is treated as usage error: sbomflow prints help to stderr and exits 2. Gate failures are distinct from structural validation failures so CI can separate manufacturer policy decisions from broken artifact integrity.

Release gate reason codes#

Exit code 1 says a release gate blocked; the reason codes below say why, in a stable machine-readable form. Every entry in release-gate.json under violations[] and drift_violations[] carries a reason_code alongside its human description, so CI can branch on a code (GATE_KEV_PRESENT) instead of parsing prose. Codes are registered in a versioned registry (sbomflow-gate-reason-codes-v1, sbomflow.gate_reasons) and are additive: they are never renamed once shipped.

Reason codes describe engine policy outcomes only. A code means a manufacturer-selected policy blocked a release — never a claim about CRA conformity, and never a substitute for the human review that owns every evidence, VEX, and approval decision.

GATE_DATA_UNAVAILABLE: an enforced policy that could not be evaluated#

Exit code 1 means "do not release". It does not mean "a vulnerability was found" — it means at least one enforced policy said no. GATE_DATA_UNAVAILABLE is the case where the policy could not even be evaluated, because an input it depends on was never loaded.

--fail-on-kev counts findings flagged by the CISA KEV catalogue. If the catalogue was never fetched, nothing is flagged — so the old gate reported a clean pass for a question it never asked. Zero known-exploited findings in a run that never loaded KEV is not a clean bill of health; it is an unasked question. Any enforced policy whose data is absent is now indeterminate: it renders no verdict (policy_outcomes[].outcome is not_evaluated, never pass), emits a policy_data_unavailable violation naming the policy and the missing input, and exits 1. The detail is in release-gate.json under indeterminate_policies[], and sbomflow explain <dir> --gate prints it in full.

There is deliberately no new exit code: 1 already means "an enforced gate said no", CI already treats it as a build break, and inventing a third state would let a pipeline that only checks == 1 silently ship an unevaluated release. Automation that needs the distinction branches on the reason_code. This matches GATE_DRIFT_UNAVAILABLE, which has always refused to let a drift policy pass with no previous release to compare against.

An inventory nobody read is the same unasked question. Every vulnerability policy (fail_on_vulnerabilities, fail_on_kev, epss_threshold, the reachable and new_* variants) also requires inventory: it is unmet (state absent) when the run inventoried no component at all, and (state not_read, the documents named) when a requested SBOM document — --import-sbom, sbom.import, a declared supplier SBOM — was not read because it was missing, unreadable, empty, not parseable, over a resource limit or in a version this build does not interpret. One unread document of two is enough: the inventory is incomplete. Before this, a truncated SBOM from a killed or disk-full generator gave gate PASS (enforced) over 0 components. The policy renders not_evaluated with policy_data_unavailable; policies that do not read components are unchanged, and --strict keeps its own exit status. A gate that applied this rule records data_requirement_rules: ["inventory"] in release-gate.json. A historic release replayed by store verify-gates whose recorded PASS came from an empty or unread inventory, whose record carries no such marker, and whose recorded outcome reproduces exactly under the earlier rule, reads recorded_before_inventory_rule and exits 0: the rule changed, not the record. Re-running the release records an outcome under the current rule. A record that carries the marker, or that the earlier rule does not reproduce either, stays outcome_mismatch (exit 4).

A run that assessed no requirement regime is the same rule, one layer up. requirement_regime: none (config, or --requirement-regime none) means nothing was assessed, so evidence_gaps and requirement_assessments are empty because no question was asked. fail_on_gaps therefore declares a data requirement of its own (requirement_graph, state not_applicable_by_operator_choice), and so do the new_gap: and status_regression: parts of fail_on_evidence_regression. Enforced over such a pack, each renders not_evaluated and emits policy_data_unavailable — never exit 0 with an empty violation list. review_recheck: is a review fact, not a requirement fact, and stays evaluable; so do fail_on_kev and fail_on_support_period_missing, which --strict also forces and which are not CRA concepts.

analyze/audit refuse an explicit --fail-on-gaps (or a policy file enforcing it) up front rather than letting it reach the gate. What --strict and the shipped --policy-profile presets force is dropped instead of refused — an operator who picked a preset for other reasons should not have to re-pick it — and every drop is recorded in release-gate.json under regime_excluded_policies[] with the policy, the parts, the origin (audit --strict, policy-profile:<name>) and the reason requirement_regime_none. A dropped knob you cannot read about is the same defect as a vacuous pass. The key is written only on a none run, so a cra release-gate.json is byte-identical.

fail_on_evidence_regression is dropped and recorded rather than refused, even when the operator gives it explicitly (--fail-on-evidence-regression, or a policy file that enforces it — the origin names which). Only its new_gap: and status_regression: parts are regime-derived: refusing the whole knob would disarm review_recheck:, which is a review fact and stays enforced under none. fail_on_gaps has no such part, which is why it is refused outright.

Missing data is not a network requirement. A pinned offline snapshot satisfies every one of these policies — --kev-file, --epss-file, --nvd-file, --osv-snapshot, or a vulndb store. Only an absent or failed source triggers the block. A stale source does not, by default: the catalogue was genuinely consulted and every finding really was compared against it, so its age is a separate fact — the stale_vulnerability_data warning (which --strict can promote to a failure). Blocking on staleness by default would push operators onto the network, which offline-first forbids.

GATE_STALE_VULNERABILITY_DATA: an opt-in freshness SLA#

GATE_DATA_UNAVAILABLE is "the source never loaded". This is its counterpart for a source that did load and was genuinely consulted, but is older than a freshness service level the operator chose to enforce. It is off by default and set only in the gate policy — fail_on_stale_vulnerability_data: true, with an optional uniform max_snapshot_age_days. With no day count, each source is judged by its documented per-kind window (the same threshold the stale_vulnerability_data warning uses), so the bare knob simply promotes that warning to a gate.

When it is on, a consulted source older than the maximum blocks — and a source whose data date is unknown also blocks, because unknown age can never be shown to be within the SLA (unknown is never fresh, the same rule GATE_DATA_UNAVAILABLE applies to absent data). The reason names each source, its recorded as-of date, its computed age, and the maximum it was judged by, so the block is replayable. Clear it by refreshing the source (a newer pinned offline snapshot is enough — this never forces the network), raising max_snapshot_age_days, or not enforcing the policy. Like every gate reason it is an engineering policy outcome, not a compliance determination, and exit 1 is unchanged.

The knob is enforced on the primary gate path — sbomflow analyze --policy <file> and --policy-profile <preset> (and the read-only gate simulate) all honour it, so a real release run over a stale consulted source blocks with this reason.

Per-policy data requirements — what each --fail-on-* flag needs, and what happens when it is absent — are tabulated in the CI runbook.

GATE_SEVERITY_UNDETERMINED / GATE_EPSS_UNINTERPRETABLE: values the gate could not interpret#

GATE_DATA_UNAVAILABLE is the same honesty rule at source granularity — "we never loaded the catalogue". These two are that rule at finding granularity: the source loaded, and it told us nothing usable about this item.

An unknown severity is not a low severity. It is the absence of one. The severity scale runs none < low < medium < high < critical, and unknown is not on it: none is a determined zero-impact answer, while unknown means no source gave us a rankable band at all (no CVSS vector, no advisory severity). Ranking the two the same — which the gate did until this was fixed — let a finding the engine never scored slide under every threshold, so --fail-on-vulnerabilities --severity-threshold low reported a clean pass over it. It now blocks with GATE_SEVERITY_UNDETERMINED: the gate will not report a finding it never ranked as sitting below your threshold.

The same rule covers the release-drift high band: fail_on_new_critical_or_high is a threshold policy over the drift rows, and a NEW (or severity-changed) finding whose severity cannot be determined used to silently not count toward it. It now blocks with GATE_SEVERITY_UNDETERMINED — never counted as critical/high (that is not known), and never silently below the band. GATE_NEW_CRITICAL_OR_HIGH itself still fires only for findings whose stated band determinably meets critical/high. A recorded human VEX review (not_affected/fixed) clears the drift block on the same terms as every other drift blocker.

An undated EPSS score is not a low EPSS score. FIRST re-fits the EPSS model periodically and the score distribution moves with it, so a bare probability is not interpretable without the score_date it was produced under. A finding carrying a score with no model date blocks an enforced epss_threshold with GATE_EPSS_UNINTERPRETABLE rather than quietly counting as "below the threshold". (The daily FIRST CSV records its own score_date; SBOMFlow stamps it onto every finding it scores, so real enrichment never trips this.)

Neither code is a claim that the item is severe — only that it could not be cleared. Both are visible on every run, enforced or not: release-gate.json always carries undetermined_severity_vulnerability_ids, undetermined_severity_gap_ids, and uninterpretable_epss_vulnerability_ids, so "how many findings have no determinable severity?" is answerable from any output. With no --fail-on-* flag they block nothing — the gate stays informational and exits 0.

They clear the way every other blocking item clears — through a recorded human decision, never through silence:

• supply the missing data (an NVD/OSV snapshot carrying a CVSS vector; an EPSS snapshot that records its score_date);
• record a human VEX review of the finding (fixed, or not_affected with a valid CISA justification); or
• waive the item with a reviewer, a reason, and an expiry — it stays visible in waiver_status and in the report.

The two AI honesty controls#

fail_on_ai_model_changed and its siblings can only ever report what an AI comparison found. If the previous release carried no AI evidence record, or one that could not be read, or this run performed no scan, then every one of them is vacuously empty — and an operator enforcing an AI policy over an inventory that was never gathered would get the most reassuring possible green.

fail_on_ai_drift_uncomparable and fail_on_ai_inventory_partial are the answer: they make "nothing was compared" and "the walk was cut short" into blockable facts. They are the AI face of the rule GATE_DATA_UNAVAILABLE states for advisory sources — not looked at is not clean — and, like every AI control, they are off until an operator turns them on.

Every AI control is evaluated independently. One control that cannot be evaluated, or that raises, is recorded as GATE_AI_CONTROL_UNEVALUATED for itself and never stops the others from being evaluated and enforced: a gate that keeps closing while most of its controls have quietly stopped running is the failure this design exists to prevent.

No AI reason code asserts that a change is harmful, that a model is unfit, or that a release is unsafe. Each says a manufacturer-selected policy blocked on something the AI evidence recorded. AI controls are configured in the gate policy file only (fail_on_ai_*: true), like the other recent knobs — there is no CLI flag.

Stable error codes on failure output#

Every user-reachable CLI failure prints a stable `[E0xx] code with a one-line fix and a docs link (see ERRORS.md, or offline: sbomflow help error <code>`). Exit code 2 covers usage/input/operation failures (families E01x usage & input, E02x review workflow, E03x outputs & artifacts, E04x integrations & integrity, E05x store & vulndb); integrity verification failures that must not read as ordinary usage errors — a broken audit-log hash chain (E043), store tamper, gate outcome mismatch — exit 4. A structural test in the offline suite fails if a new failure path ships without a code.

Exit 4 is reserved for a record that does not reproduce, never for a record that has merely been overtaken: store verify-gates reports a release whose recorded outcome replays exactly but which humans have decided more about since as outcome_superseded, and exits 0. A verification signal that fired on the ordinary review workflow would train operators to ignore it. The same holds for a record made before a gate rule existed: recorded_before_inventory_rule exits 0.

Nor is it reserved for data that is merely gone. store verify-gates also reports, beside each verdict, whether the release's vulnerability result can still be recomputed from the advisory bytes it was computed from — a separate vulnerability_replay state of replayable, unreplayable or unknown. An unreplayable release exits 0: its recorded gate outcome reproduced, and a pruned advisory snapshot is a fact about data availability, not a tamper signal. The verdict word verified is unchanged by it; see the store verify-gates section of docs/RELEASE_HISTORY.md.

Troubleshooting first-run failures#

Common mistakes are designed to self-explain with an actionable message:

• Missing/file target (exit 2) — "target directory not found … Fix: pass an existing product directory."
• Malformed or unknown-key config (exit 2) — the parser error plus "Fix: check syntax/keys with sbomflow validate-config <file> or run sbomflow doctor .."
• Unknown --policy-profile (exit 2) — lists the available shipped presets.
• Malformed --kev-file/--epss-file/--nvd-file snapshot — never silently ignored: it surfaces a vulnerability_enrichment_error scan warning (and fails under --strict). An --nvd-file that is not JSON, gzip or zip data as its name says (.json, .json.gz, .zip) takes the same path with a plain-language message naming the file, never a decoder error or an E019 exit.

sbomflow doctor . is the first stop: it reports Python compatibility, optional extras, the external CycloneDX CLI, and any discoverable config (including parse errors and unknown-key warnings) — all offline.

--strict is opt-in and runs after all artifacts are written, so the evidence pack is always produced; the distinct exit code 5 lets CI fail on warnings without conflating them with a --fail-on-* gate decision (1). Each scan-warning code is registered in a stable, versioned warning catalog (sbomflow-warning-catalog-v1); --strict=<codes> is validated against it.