Exit Codes

AIROM’s exit status answers one question: did the scan run? It does not tell you whether the scan found anything. Failing the build on a finding is an explicit, opt-in decision you make with --fail-on and --exit-code.

The contract

Code	Meaning
`0`	The scan completed. Findings are not failures. A scan that discovers 40 AI components still exits `0`.
`<n>`	The opt-in CI gate matched. `<n>` is the `--exit-code` value — `1` by default when a policy is active.
`2`	Fatal error: invalid flags or configuration, or source acquisition failed (unreadable path, clone failure, image acquisition failure).

Everything downstream of source acquisition degrades instead of failing. Detector errors, unreadable files, and corrupt headers become Unknown records in the output — they never change the exit code. A partial inventory is still a successful scan.

Exit 0 on findings is deliberate, not an oversight. If you want “fail the build when a hosted LLM shows up,” you must say so with --fail-on. Nothing else will fail your build for you.

Turning on the gate

Scan and report (no gate)

Report only — always exits 0

airom fs . -o table

Add a policy

--fail-on compiles an expression and evaluates it against the assembled inventory after all output has been written. A match exits 1.

Fail when a high-confidence hosted LLM is present

airom fs . --fail-on "hosted-llm&confidence>=0.9"

Choose the exit status

Match exits 3 instead of 1

airom fs . --fail-on "pickle-risk" --exit-code 3

`--exit-code` and `--fail-on` interact

Flags	Behavior
neither	No gate. A successful scan always exits `0`.
`--fail-on <expr>`	Policy active; a match exits `1`.
`--fail-on <expr> --exit-code N` (N > 0)	Policy active; a match exits `N`.
`--fail-on <expr> --exit-code 0`	Policy is evaluated, all output is still written, and the run exits `0` on a match.
`--exit-code N` alone (N > 0)	Fail on any component. Equivalent to a policy that matches every discovered component.
`--exit-code 0` alone	No gate — identical to leaving it unset.

--exit-code must be in [0,255]; anything else is a configuration error (exit 2).

--min-confidence is a presentation filter. It trims what the writers emit; it does not change what --fail-on evaluates. Put your confidence threshold in the policy expression (confidence>=0.8) if you want it to affect the gate.

The `--fail-on` grammar

Grammar

expr       = clause *( "|" clause )     ; OR
clause     = term   *( "&" term )       ; AND
term       = ident | risk | compliance | comparison
ident      = a ComponentKind ("hosted-llm")
risk       = "risk" | "risk:" severity | "risk:" slug   ; severity: high | medium | low
compliance = "compliance" | "compliance:gap"
           | "compliance:" framework [ ":" control ]     ; inventory-level; not &-combinable
comparison = "confidence" OP number     ; OP: >= <= > < =

& binds tighter than |, so a|b&c reads as a | (b & c). Whitespace around tokens is ignored. A dangling & or | is a configuration error (exit 2). A --fail-on that is empty or all whitespace sets no policy at all — it is not an error, and it does not gate.

Each clause must be satisfied by a single component

This is the rule that surprises people. hosted-llm&confidence>=0.9 means “some one component is a hosted LLM and that same component has confidence ≥ 0.9.” It does not mean “a hosted LLM exists somewhere and, separately, something else is high-confidence.”

The application root component — the scan target itself — is never eligible to match a policy. It is the thing you scanned, not a finding.

Terms

ComponentKind

A component kind — hosted-llm, local-model-file, embedding-model, framework, library, vector-db, prompt, dataset, ai-config, infra, service, rag-pipeline, application.

risk | risk:severity | risk:slug

Matches a component carrying an artifact risk. risk matches any risk; risk:high / risk:medium / risk:low match by severity; risk:<slug> matches one catalog entry (pickle-import, keras-lambda, gguf-template, savedmodel-pyfunc, unsafe-load). pickle-risk remains as a deprecated alias for risk:pickle-import.

compliance | compliance:framework[:control]

Fires on a compliance gap (a manual control is not a failure; a met is a pass). compliance:gap — any gap; compliance:<framework> — a gap in that framework; compliance:<framework>:<control> — that control is a gap. It is inventory-level, so it cannot be &-combined with a component term (use |), and it requires --compliance to have been given — gating on a framework you never evaluated is a configuration error, not a silent pass. Like every selector it evaluates the full assembly, so --min-confidence never relaxes it.

comparison

Compares the component’s confidence against a bound in [0,1]. Operators: >=, <=, >, <, =. A bound outside [0,1] is a configuration error. Bare confidence with no operator is rejected — it is almost always a typo.

Worked examples

Command	Gate semantics	Exit code
`airom fs .`	No gate.	`0` always (unless fatal)
`airom fs . --fail-on "hosted-llm"`	Any hosted-LLM reference.	`1` on match, else `0`
`airom fs . --fail-on "pickle-risk"`	Any model file with a dangerous pickle global.	`1` on match, else `0`
`airom fs . --fail-on "risk:high"`	Any component carrying a high-severity artifact risk.	`1` on match, else `0`
`airom fs . --fail-on "risk:unsafe-load"`	Any component with the `unsafe-load` risk.	`1` on match, else `0`
`airom fs . --compliance nist-ai-rmf --fail-on "compliance:gap"`	Any compliance gap in an evaluated framework.	`1` on match, else `0`
`airom fs . --fail-on "hosted-llm&confidence>=0.9"`	One component that is a hosted LLM and has confidence ≥ 0.9.	`1` on match, else `0`
`airom fs . --fail-on "local-model-file\|hosted-llm&confidence>=0.8"`	Any local model file, or a hosted LLM with confidence ≥ 0.8.	`1` on match, else `0`
`airom fs . --fail-on "dataset" --exit-code 7`	Any dataset component.	`7` on match, else `0`
`airom fs . --fail-on "hosted-llm" --exit-code 0`	Evaluated; output still written; never fails.	`0` always
`airom fs . --exit-code 1`	Any discovered component (root excluded).	`1` if anything was found
`airom fs . --fail-on "not a term"`	Rejected at parse time.	`2`
`airom repo https://example.invalid/x.git`	Source acquisition fails.	`2`

--exit-code 1 with no --fail-on fails on any component, including low-confidence noise. Extension-only dataset detection and keyword-only ai-config detection emit components at confidence 0.5–0.6 on general-purpose directories. Prefer an explicit --fail-on expression with a confidence bound. See confidence.

Shell notes

Quote the expression. Both & and | are shell metacharacters:

Always quote --fail-on

airom fs . --fail-on "local-model-file|hosted-llm&confidence>=0.8"

You can also set the policy through the config layers — flags beat env vars beat .airom.yaml:

export AIROM_FAIL_ON="hosted-llm&confidence>=0.9"
export AIROM_EXIT_CODE=1
airom fs .

fail-on: "hosted-llm&confidence>=0.9"
exit-code: 1

Unknown keys and unknown AIROM_* variables fail loudly with exit 2. A typo never silently disables your gate.

GitHub Actions

A copy-pasteable workflow: scan, upload SARIF, gate.

CLI reference

Every command and global flag.

Get started

Concepts

Scanning

Output

CI/CD

Rules

Reference

The contract

Turning on the gate

`--exit-code` and `--fail-on` interact

The `--fail-on` grammar

Each clause must be satisfied by a single component

Terms

Worked examples

Shell notes

Next

GitHub Actions

CLI reference

​The contract

​Turning on the gate

​--exit-code and --fail-on interact

​The --fail-on grammar

​Each clause must be satisfied by a single component

​Terms

​Worked examples

​Shell notes

​Next

GitHub Actions

CLI reference

The contract

Turning on the gate

`--exit-code` and `--fail-on` interact

The `--fail-on` grammar

Each clause must be satisfied by a single component

Terms

Worked examples

Shell notes

Next