Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    VEX

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    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.

    Terminal window
    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).

    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.

    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.

    • 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.

    Terminal window
    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 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 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.