A VEX statement is a producer’s claim about whether a vulnerability affects a product. Keryn treats it as an attributed assertion, not independent proof. It never raises a finding’s proof level, and it is never presented as Keryn’s own conclusion.
Reading VEX
Section titled “Reading VEX”keryn scan . --vex vendor/acme.openvex.json --vex security/our.cdx.json --vex-product pkg:oci/acme-api@1.4.0 --json keryn-out/result.jsonProducer VEX claims about dependency advisories do not clear source-code findings. With blocking source findings, this scan still exits 1. The scan writes keryn-out/result.json for the export example below.
| Flag | Meaning |
|---|---|
--vex <local-file> |
a VEX document; repeatable, up to 16 files of at most 8 MiB each (16 MiB in total) |
--vex-product <purl|url> |
the product the scan is about; needed to apply statements that name subcomponents of a product |
The flags work on every fresh scan: keryn scan, bom, diff, bundle, decide, and every keryn sca action. With --from, keryn decide, decide migrate and bundle refuse --vex (exit 2), because a saved result already records the VEX it was scanned with. keryn ci does not take the flags, and there is no .keryn.yml key. Files are local only: nothing is downloaded. A file that cannot be read or parsed is a usage error (exit 2). In a pull request checked under an enforced policy base, the VEX files are read from the trusted base, not from the pull request.
The format is recognised from the document:
| Format | Recognised by | Statuses read |
|---|---|---|
| OpenVEX | @context https://openvex.dev/ns/v0.2.0 |
not_affected, fixed, affected, under_investigation |
| CSAF 2.0 VEX | document.csaf_version 2.0 and category csaf_vex |
known_not_affected, fixed, known_affected, under_investigation (other product_status keys are not read); products need a product_identification_helper.purl |
| CycloneDX VEX | specVersion 1.4–1.7 with vulnerabilities[].analysis.state |
not_affected and false_positive → not affected; resolved, resolved_with_pedigree → fixed; exploitable → affected; in_triage → under investigation; version ranges are not read |
Every statement must name a vulnerability, a product, an author and a time (the statement’s, else the document’s). A not_affected statement also needs one of the five OpenVEX justifications or an impact statement. A statement that fails a check is not applied. It is listed as an issue, and the scan’s coverage becomes incomplete (exit 3, unless --allow-incomplete).
Matching
Section titled “Matching”A statement applies to a dependency finding when both of these hold:
- Vulnerability. One of the finding’s advisory ids or aliases equals one of the statement’s vulnerability ids (case does not matter).
- Product. The finding’s purl, with its version, equals the statement’s product. Comparison is on the canonical purl, so qualifiers and subpath count.
A statement whose product has subcomponents applies only when --vex-product equals that product exactly and a subcomponent equals the finding’s purl. Claims about another container never apply globally. A versionless purl never matches.
Only findings with advisories and a package identity take part (dependency findings, and imported scanner findings whose purl comes from structured report data). Rule findings in source code are never touched.
What each status does
Section titled “What each status does”| Status | Effect on the finding |
|---|---|
not_affected, fixed |
covers that advisory. When every advisory of the finding is covered, the finding leaves the gated findings and is listed under Covered by VEX. Otherwise it stays gated with the remaining advisories and says how many were covered |
affected, under_investigation |
nothing: the finding stays as it was |
a not_affected/fixed and an affected/under_investigation for the same subject |
a conflict: the finding stays gated, and the conflict is listed |
A statement that matches nothing is listed as unmatched and does not affect the gate. In keryn sca inventory, collect, assess and sbom, covered component/advisory pairs are subtracted from the advisory count. VEX never clears an inventory change, an SBOM identity check, an unknown assessment or incomplete source coverage.
Where it is reported
Section titled “Where it is reported”- Console and Markdown summary: a Covered by VEX (producer assertions; not independent proof) section. Each covered finding shows its advisory ids, the statement’s status, author, time and justification, and the source file. The source file is labelled repository-sourced (inside the scanned tree) or external, with its SHA-256. The section also gives the counts of unmatched and conflicting statements, and any statements that were not applied, with the reason.
- Result JSON: a top-level
vexobject withcovered(each original finding, the vulnerabilities and the statement ids),statements(normalised, with format, author, timestamp, justification, explanation and source{name, sha256, origin}),unmatched,conflicts,issuesandsources. - SARIF carries no VEX field. A fully covered finding is simply not among the results.
keryn scaactions writevex-assessment.json(keryn.dev/vex-assessment/v1) into their output directory.- Keryn Web shows Covered by VEX on the results and in recorded evidence.
The repository and external labels say where the file was, not who wrote it: there is no signature check.
Writing VEX
Section titled “Writing VEX”keryn export --vex vex.json .keryn export --vex vex.cdx.json --format cyclonedx --from keryn-out/result.json .| Flag | Default | Meaning |
|---|---|---|
--vex <file|-> |
required | where to write; - is stdout |
--format openvex|cyclonedx |
openvex |
OpenVEX 0.2.0, or CycloneDX 1.6 VEX |
--product <purl|url> |
the git remote as a purl (GitHub, GitLab, Bitbucket), else pkg:generic/<folder> |
the product the statements are about |
--author <name> |
git user.email, else unknown |
document author |
--timestamp <iso> |
now | document time; a value that is not an ISO 8601 date-time is a usage error (exit 2) |
--from <result.json> |
none | the scan result: names each finding’s purl and advisory ids, and adds Keryn’s reachability statements |
From .keryn/decisions.yml. Each decision gives one statement, or one per advisory of a dependency finding with --from.
- The statement’s author is the decision’s
decided_by, and its time isdecided_at. not_affectedkeeps its justification, and the reason becomes the impact statement.- An accepted risk is written as
affected, with Accepted until … by …. fixedandunder_investigationkeep the reason as status notes.
From reachability (with --from). Keryn’s own reachability verdicts become statements by Keryn static reachability analysis:
- not reachable in the analysed code →
not_affectedwithvulnerable_code_not_in_execute_path, citing what was analysed; - reachable →
affected, citing the call site; - otherwise →
under_investigation.
CycloneDX output. Statuses map to analysis.state:
- not_affected →
not_affected - fixed →
resolved - affected →
exploitable - under_investigation →
in_triage
Justifications map to:
code_not_present(from component or vulnerable code not present)code_not_reachablerequires_environmentprotected_by_mitigating_control
Properties keryn:vex:* keep the author, time, aliases and products, so Keryn reads its own export back without loss. The export is checked before writing: an invalid statement stops it.
keryn handoff evidence … -o report.html also writes report.openvex.json from the decisions.