Exchange VEX documents

VEX (Vulnerability Exploitability eXchange) is how a triage decision leaves one tool and reaches another. TRUSTIVAN reads and writes OpenVEX 0.2.0, per asset. In the dashboard, the asset page’s VEX card has Download and Upload.

Export

curl -s localhost:8080/api/v1/assets/$ASSET_ID/vex \
  -H "Authorization: Bearer $TRUSTIVAN_KEY" -o asset.openvex.json

Needs findings:read. One statement per vulnerability finding on the asset, in every state. A container image is named by a pkg:oci Package URL, and each finding’s package is a subcomponent.

Finding state	OpenVEX status
open, reopened	`under_investigation` — no human decision yet
triaged	`affected`, action “remediation pending” (and the fixed version, when known)
suppressed with a VEX justification	`not_affected`, with that justification; the suppression reason is the impact statement
suppressed without one	`affected`, action “Risk accepted: …“
resolved	`fixed`

A suppression without a justification is exported as affected, never not_affected. Accepting a risk is a decision not to fix it, not a finding that the product is unaffected, and a VEX document is read by tools that act on the difference.

Import

curl -s -X POST localhost:8080/api/v1/assets/$ASSET_ID/vex \
  -H "Authorization: Bearer $TRUSTIVAN_KEY" \
  -H 'Content-Type: application/json' --data-binary @vendor.openvex.json

A statement applies to a finding on the asset when its vulnerability name or an alias equals the finding’s advisory ID or an alias, and — if the statement lists subcomponents — one of their Package URLs names the finding’s package.

Statement	What happens
`not_affected` with a `justification`	The finding is suppressed (permanently), and the justification is kept, so it exports back as the same statement
`not_affected` without a justification	Not applied. An imported suppression needs one of the five OpenVEX justifications
`affected`	An open finding is triaged. A suppressed or triaged one is left alone
`fixed`, `under_investigation`	Nothing. A finding is resolved when a scan no longer detects it

Every change goes through the same lifecycle a person uses, as the caller: findings:write, and findings:suppress for any suppression — checked before anything is applied, so a credential without it is refused the whole document. Each change is on the finding’s timeline, by the caller, with a reason naming the document’s @id, its author and its SHA-256. The response lists what was applied and, for every statement that changed nothing, why. Importing a document you exported changes nothing. A justification belongs to one suppression: unsuppressing, the expiry sweep, or re-suppressing by hand clears it.

Getting started

Concepts

Tutorials

How-to guides

Integrations

Help

Exchange VEX documents

Export

Import

​Export

​Import

Export

Import