# VEX

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> The VEX documents Keryn reads (OpenVEX 0.2.0, CSAF 2.0 VEX, CycloneDX VEX) and writes (OpenVEX, CycloneDX 1.6 VEX), how statements match findings, what each status does to the gate, and where it is reported.

Source: https://keryn.dev/docs/reference/sca/vex/

> **Caution: Ships in the next release**
> On main; not in Keryn 0.5.2, the latest release. Keryn 0.5.2 writes OpenVEX from `keryn export --vex` and reads no VEX.

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

```sh
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.json
```

Producer 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

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

| 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

- **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 `vex` object with `covered` (each original finding, the vulnerabilities and the statement ids), `statements` (normalised, with format, author, timestamp, justification, explanation and source `{name, sha256, origin}`), `unmatched`, `conflicts`, `issues` and `sources`.
- **SARIF** carries no VEX field. A fully covered finding is simply not among the results.
- **`keryn sca` actions** write `vex-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

```sh
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](https://keryn.dev/docs/guides/release-decisions/) 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 is `decided_at`.
- `not_affected` keeps its justification, and the reason becomes the impact statement.
- An accepted risk is written as `affected`, with *Accepted until … by …*.
- `fixed` and `under_investigation` keep the reason as status notes.

**From reachability** (with `--from`). Keryn's own [reachability verdicts](https://keryn.dev/docs/guides/sca/#reachability) become statements by *Keryn static reachability analysis*:
- *not reachable in the analysed code* → `not_affected` with `vulnerable_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_reachable`
- `requires_environment`
- `protected_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.
