Gates and exit codes
The --fail-on rules, the legacy gate flags they replace, which findings each gate counts, and the exit codes a pipeline can rely on.
A gate decides the exit code. Display flags such as --min-severity and --filter never do.
vulnetix sca --fail-on high,kev,malware
vulnetix sca --fail-on exploit=active --fail-on eol=high --fail-on cooldown=7d
--fail-on takes comma-separated rules and can be repeated. An unknown rule fails the run and lists the valid ones.
Rules
| Rule | Exit 1 when | Legacy flag |
|---|---|---|
low, medium, high, critical |
Any counted vulnerability’s highest severity is at or above the level. Severity is the highest of every scoring source the VDB holds (CVSS, EPSS, Coalition ESS, SSVC). | --severity <level> |
kev |
Same as exploit=active |
none |
exploit=poc |
Any public exploit exists, or the CVE is on any KEV list | --exploits poc |
exploit=active |
The CVE is on the CISA, VulnCheck or EU KEV list, or is weaponised | --exploits active |
exploit=weaponized |
Weaponised exploitation in the wild | --exploits weaponized |
malware |
A dependency is a known malicious package, from an advisory or from the package-level verdict | --block-malware |
eol |
A runtime (Go, Node.js, Python, Ruby) or a package with VDB end-of-life data is graded at or above the EOL block severity, critical by default |
--block-eol |
eol=<severity> |
As eol, blocking from that graded severity |
--block-eol --block-eol-severity <severity> |
unpinned |
A direct dependency uses a range (^, ~, >=, >, <=, <, !=, *, latest, x) instead of an exact version |
--block-unpinned |
unprotected |
A vulnerable package has no fix and no unexpired recorded control | none |
lag=<n> |
An installed version is one of the n most recently published versions of its package |
--version-lag <n> |
cooldown=<n>d |
An installed version was published within the last n days. The d is optional. |
--cooldown <n> |
When rules overlap, the strictest wins: --fail-on high --fail-on low fails on low, and exploit=poc beats exploit=active. Mixing --fail-on and a legacy flag never loosens a gate. For lag and cooldown the larger number wins.
EOL grading
An end-of-life date is graded by how close it is. The organisation can change the mapping on its quality gate.
| Horizon | Default severity | Quality gate key |
|---|---|---|
| Already past its end-of-life date | critical |
eolRetiredSeverity |
| Within 30 days | high |
eolWithin30DaysSeverity |
| This quarter | medium |
eolThisQuarterSeverity |
| Next quarter | low |
eolNextQuarterSeverity |
With the default block severity critical, only components already past end of life fail the build. Closer horizons are reported.
What the gates count
| Finding | Counted |
|---|---|
Affected, or unverified (range could not be compared) |
yes |
Ruled out by version (not affected, likely not affected) |
no, unless --strict |
| Covered by an unexpired recorded control | yes, unless --accept-defended |
Matched by an active ignore rule (local .vulnetix/memory.yaml or the org’s suppression rules) |
no: removed before reporting |
Marked not affected by a --vex-file, --vex or declared VexSource statement |
no |
Ruled-out and defended findings stay in the SBOM, the JSON report and the Resolve Platform. Only the gate input leaves them out. Suppressed findings are removed from every output.
Artefacts (.vulnetix/sbom.cdx.json, memory.yaml, --output files) are written before the gates run, so a failed build still leaves the full results.
Jail
--jail asks the organisation’s jail policy for a verdict after the scan uploads. A breached rule is reported as a gate named jail:<label> and exits 1. If a rule cannot be evaluated against current scan coverage, and nothing else breached, the exit is 3. An organisation with no jail policy passes. See Jail.
Exit codes
| Code | Meaning |
|---|---|
0 |
Scan finished; no gate breached |
1 |
A gate breached, or the command failed (bad flag, unreadable path, API failure) |
3 |
--jail only: the jail gate could not reach a verdict |
vulnetix sca, fix, containers and license do not use exit 2; flag errors exit 1. Exit 2 belongs to the standalone vulnetix jail command.
A breach prints quality gate(s) breached: followed by one message per gate, for example --severity high: 3 vulnerabilities at or above the threshold.
The organisation’s gate wins
When the scan runs under a signed-in organisation that has a quality gate, every value the organisation set replaces the matching flag, including a --fail-on rule. See Org quality gate.