Vex Authoring

Authoring VEX documents for ReARM

ReARM imports VEX (Vulnerability Exploitability eXchange) documents in two formats, auto-detected from content:

• CycloneDX-VEX 1.4 - 1.7 JSON. The bundled parser formally targets 1.6, but the VEX subset ReARM reads (vulnerabilities[], analysis, affects, ratings) is unchanged in 1.7, so 1.7 documents import (verified). Constructs introduced in 1.7 outside that subset are ignored -- do not encode load-bearing VEX data in 1.7-only fields.
• OpenVEX 0.2.0

Import happens synchronously during artifact upload (artifact type VEX on a release). Each statement is matched against the release's SBOM inventory and becomes either a Finding Analysis (auto-accept) or a PENDING proposal in the VEX Proposals inbox (stage). The import outcome (total / staged / auto-accepted / unmatched / errored counts plus error messages) is reported back on upload and persisted on the VEX artifact.

This skill covers the producer side: what the document must contain so statements actually import. For the reviewer side (scopes, import modes, trust gate, proposals inbox), see documentation_site/docs/workflows/importing-vex.md.

Before you write anything: two hard prerequisites

1. The target release must already have an SBOM artifact with reconciled components. The VEX matcher matches against that inventory; importing VEX into an SBOM-less release fails loud.
2. Product identifiers must match the SBOM's PURLs exactly, version included. ReARM canonicalizes PURLs (drops subpath and most qualifiers) but preserves the version. If the SBOM says pkg:npm/minimist@1.2.6, a statement about pkg:npm/minimist (no version) or pkg:npm/minimist@1.2.5 will NOT match and is counted as unmatched. Copy purl values verbatim from the SBOM you are writing VEX against.

CycloneDX-VEX requirements

Document envelope

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:<uuid4>",
  "version": 1,
  "vulnerabilities": [ ... ]
}

Every vulnerabilities[] entry MUST have an analysis block

This is the single most common authoring mistake. In CycloneDX, a vulnerabilities[] entry without analysis is a plain vulnerability report (what a scanner emits), not a VEX statement -- it carries no exploitability assertion, so ReARM skips it and reports it as "skipped: no analysis block". A document whose entries all lack analysis imports zero statements.

"analysis": {
  "state": "not_affected",
  "justification": "code_not_reachable",
  "detail": "optional free-text explanation of the assessment"
}

• state -- required. One of: not_affected, exploitable, in_triage, resolved, resolved_with_pedigree (imported as resolved), false_positive.
• justification -- provide it whenever state is not_affected. One of: code_not_present, code_not_reachable, requires_configuration, requires_dependency, requires_environment, protected_by_compiler, protected_at_runtime, protected_at_perimeter, protected_by_mitigating_control.
• response -- optional array, e.g. ["will_not_fix"], ["update"].

affects[].ref must be resolvable

Each entry's affects[] names the product(s) the statement is about. Two accepted forms:

1. Direct identifier -- a pkg: PURL or cpe: string: "affects": [{"ref": "pkg:npm/minimist@1.2.6"}]

2. bom-ref into this same document -- the ref must match the bom-ref of an entry in the VEX document's own top-level components[] array, and that component must carry a purl:

   "components": [
     {"type": "library", "name": "minimist", "version": "1.2.6",
      "purl": "pkg:npm/minimist@1.2.6", "bom-ref": "comp-minimist"}
   ],
   "vulnerabilities": [
     {"id": "CVE-...", "affects": [{"ref": "comp-minimist"}],
      "analysis": {...}}
   ]

   Refs pointing into another document -- e.g. the SBOM's BOM-Link form urn:cdx:<serial>/1#<ref> -- do NOT resolve and the statement matches nothing.

Include ratings[] so severity resolves

Every accepted analysis needs a severity. Put the severity in the statement:

"ratings": [{"severity": "high"}]

With multiple ratings, ReARM takes the highest. If the statement has no rating, ReARM falls back to existing Finding Analysis rows for the same CVE, then to the org's canonical vulnerability record; if all three are empty an auto-accept import demotes the statement to STAGE with a SEVERITY_MISSING banner. Supplying ratings[] avoids the demotion.

Minimal complete CycloneDX-VEX example

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6",
  "serialNumber": "urn:uuid:2c1f4a60-0000-4000-8000-000000000001",
  "version": 1,
  "vulnerabilities": [
    {
      "id": "CVE-2021-44906",
      "ratings": [{"severity": "critical"}],
      "affects": [{"ref": "pkg:npm/minimist@1.2.5"}],
      "analysis": {
        "state": "not_affected",
        "justification": "code_not_reachable",
        "detail": "The vulnerable prototype-pollution path is never invoked with attacker-controlled input."
      }
    }
  ]
}

OpenVEX requirements

OpenVEX statements are validated per the 0.2.0 spec. Each statement needs a vulnerability name (CVE id), product @ids (PURLs -- same exact-match rule as above), and a valid status:

Valid justification values (OpenVEX vocabulary): component_not_present, vulnerable_code_not_present, vulnerable_code_not_in_execute_path, vulnerable_code_cannot_be_controlled_by_adversary, inline_mitigations_already_exist.

Statements that violate these rules are counted as errored with a per- statement message; the rest of the document still imports. Note OpenVEX has no severity field, so the fallback chain above always applies -- expect SEVERITY_MISSING demotions for CVEs the org has never seen.