vex-authoring

name	vex-authoring
description	Author CycloneDX-VEX or OpenVEX documents that import cleanly into ReARM. Use when generating, fixing, or validating a VEX file for upload to a ReARM release, or when a VEX upload reported zero imported statements, unmatched statements, or skipped entries.

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:

status	Required	Forbidden
not_affected	justification OR impact_statement	action_statement
affected	action_statement	justification, impact_statement
fixed	--	justification, impact_statement, action_statement
under_investigation	--	justification, impact_statement, action_statement

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.

Conditional justifications defer to attestation

Not every accepted statement applies immediately. ReARM distinguishes code properties (true regardless of deployment) from conditional claims (true only while some consumer-side control is in place):

• not_affected with one of requires_configuration, requires_environment, protected_by_compiler, protected_at_runtime, protected_at_perimeter, protected_by_mitigating_control
• exploitable with a workaround (text or a workaround_available response)

These are accepted but their Finding Analysis write is deferred behind a PENDING Mitigation Attestation: someone must attest that the environmental control / workaround is actually in place (Mitigation Attestations inbox) before the analysis applies and finding counts change. This is by design, not a dropped statement -- do not "fix" it by swapping the justification to code_not_reachable or code_not_present; use those only when they are the true assessment. not_affected with code_not_present / code_not_reachable applies immediately.

Interpreting the import outcome

The upload response (and the VEX artifact record) carries the outcome summary. Symptom-to-fix table:

Outcome	Cause	Fix
"No VEX statements imported" / total = 0	No vulnerabilities[] entries carry an analysis block, or the document is not parseable as CDX/OpenVEX	Add analysis to each entry (see above); check the envelope
"N vulnerability entries skipped: no analysis block"	Those entries are scanner findings, not VEX statements	Add analysis.state (+ justification for not_affected) reflecting the real assessment
N unmatched, no proposals	Product PURLs / versions do not correspond to any component in the release's SBOM	Copy PURLs verbatim (including version) from the SBOM; check bom-refs resolve inside the VEX document itself
"doc parse failed: ..."	Malformed JSON or wrong schema	Validate the JSON; check bomFormat / OpenVEX @context
"Cannot import VEX: release has no SBOM components yet"	Upload order	Upload and reconcile the SBOM first, then the VEX
Statement staged despite Auto-accept	Trust gate (issuer class) or missing severity demoted it	Expected; supply ratings[] and review the proposal, or adjust issuer class if you authored the VEX yourself
Statement accepted but finding state / counts unchanged	Conditional claim (environmental justification or workaround) -- analysis write deferred behind a PENDING Mitigation Attestation	By design; attest the control in the Mitigation Attestations inbox and the analysis applies. See "Conditional justifications defer to attestation"

Do not invent an analysis state to force an import: state is an assertion about exploitability. If no assessment exists yet, use in_triage (CycloneDX) or under_investigation (OpenVEX) -- that is exactly what those states are for.

Self-check before uploading

Run this against the VEX file (and the target SBOM) to catch the common failures locally:

python3 - vex.cdx.json sbom.cdx.json <<'EOF'
import json, sys
vex = json.load(open(sys.argv[1]))
sbom_purls = set()
if len(sys.argv) > 2:
    sbom = json.load(open(sys.argv[2]))
    sbom_purls = {c.get("purl") for c in sbom.get("components", []) if c.get("purl")}
own_refs = {c.get("bom-ref"): c.get("purl") for c in vex.get("components", [])}
problems = []
vulns = vex.get("vulnerabilities", [])
if not vulns:
    problems.append("no vulnerabilities[] entries at all")
for v in vulns:
    vid = v.get("id", "?")
    if not v.get("analysis", {}).get("state"):
        problems.append(f"{vid}: missing analysis.state (entry will be skipped)")
    if v.get("analysis", {}).get("state") == "not_affected" and not v["analysis"].get("justification"):
        problems.append(f"{vid}: not_affected without justification")
    if not v.get("ratings"):
        problems.append(f"{vid}: no ratings[] (severity may need manual review)")
    for a in v.get("affects", []):
        ref = a.get("ref", "")
        purl = ref if ref.startswith(("pkg:", "cpe:")) else own_refs.get(ref)
        if not purl:
            problems.append(f"{vid}: affects ref '{ref}' resolves to no PURL")
        elif sbom_purls and purl not in sbom_purls:
            problems.append(f"{vid}: '{purl}' not in SBOM inventory (will be unmatched)")
print("\n".join(problems) if problems else "OK: all statements look importable")
EOF

Uploading

• UI: release page -> Add Artifact -> type VEX -> attach the file. Extra controls appear: Scope (default Component), Import mode (default Auto-accept; pick "Stage all for review" to keep a human in the loop), Issuer class (default Vendor).
• CLI / CI: rearm-cli addartifact with "type": "VEX" in the artifacts JSON; optional vexScope, vexImportMode, userIssuerClassOverride fields (rearm-cli 26.05+). Full example in documentation_site/docs/workflows/importing-vex.md.