vexctl: Create, Add, Merge and Attest OpenVEX Documents

A source-checked guide to vexctl v0.4.4: the create, add, merge and attest commands, the validation rules they enforce, why merge keeps every statement instead of resolving them, and the defaults that quietly produce weak VEX documents.

Tall stacks of paper documents and green and brown file folders with yellow-edged pages on an office desk under ceiling lights
Photo by Wesley Tingey on Unsplash

vexctl is the OpenVEX project’s own tool for writing VEX (Vulnerability Exploitability eXchange) documents: create starts a document, add appends a statement and bumps the version, merge combines documents into one timeline, and attest wraps a document in an in-toto attestation you can sign and attach to an image. The commands are short. The defaults behind them are where weak VEX comes from: an anonymous author, a placeholder action statement, and a merge that resolves nothing.

This guide reads the vexctl v0.4.4 source (the newest tag on November 12, 2026, committed June 16, 2026) and the go-vex v0.2.8 library it builds on. It fills the gap left by our Trivy --vex oci guide: Trivy consumes VEX but does not write it. If you need the basics of what a statement asserts, start with what a not_affected statement means.

Install and version check

The README gives two install routes:

go install github.com/openvex/vexctl@latest   # or pin: @v0.4.4
brew install vexctl

v0.4.4’s go.mod requires Go 1.26.4, github.com/openvex/go-vex v0.2.8 and github.com/sigstore/cosign/v2 v2.6.3. Pin the version in CI: the behaviour below is read from that tag, and a few help texts in it are out of step with the code (covered under merge).

vexctl create: one statement, new document

create takes positional arguments or flags (create [flags] [product_id [vuln_id [status]]]):

vexctl create \
  --author="Example Corp PSIRT <[email protected]>" \
  --product="pkg:oci/api-gateway@sha256:<digest>?repository_url=registry.example.com/team" \
  --vuln="CVE-2026-12345" \
  --status="not_affected" \
  --justification="vulnerable_code_not_in_execute_path" \
  --impact-statement="The parser that contains the flaw is never loaded by this image." \
  --file=api-gateway.vex.json

Illustrative: the command and flag names are taken from the v0.4.4 source; we did not run the binary for this article.

The flags that shape the statement, from internal/cmd/options.go:

FlagShortDefaultNotes
--product-pnoneRepeatable. At least one is required. A purl or other IRI.
--vuln-vnoneRequired.
--status-snonenot_affected, affected, fixed or under_investigation.
--justification-jnoneOnly allowed with not_affected. vexctl list prints the valid labels.
--impact-statementnoneOnly allowed with not_affected.
--action-statement-aNo action statement providedOnly kept when status is affected.
--status-notenoneHow the status was determined.
--aliasesnoneOther IDs (GHSA, GO-…). Duplicates, or an alias equal to --vuln, are rejected.
--subcomponentsnoneRejected when more than one --product is given.
--authorUnknown AuthorDocument author.
--author-roleemptyOptional.
--idgeneratedGenerated from the document’s canonical hash when omitted.
--filestdoutOutput path.

Two validation layers apply. vexctl’s own checks (above) run first; then go-vex’s statement validator enforces the OpenVEX spec rules: a not_affected statement needs a justification or an impact_statement, and an affected statement needs an action_statement. The spec words them as MUSTs: “For statements conveying a not_affected status, a VEX statement MUST include either a status justification or an impact_statement”, and “For a statement with ‘affected’ status, a VEX statement MUST include a statement that SHOULD describe actions to remediate or mitigate the vulnerability.”

Two defaults to override every time

The author. go-vex sets DefaultAuthor = "Unknown Author", and vexctl’s validator only rejects a blank author, so the placeholder passes. The spec says author “MUST be an individual or organization”. A consumer that weighs VEX by issuer cannot trust an anonymous statement, so pass --author on create, add and merge.

The action statement. The -a flag defaults to No action statement provided. For an affected statement that default fills the required field, so the validator is satisfied and the document carries no remediation advice. Write the real action (upgrade target, configuration change, compensating control) every time.

Reproducible timestamps

create and add honour SOURCE_DATE_EPOCH; the help text says it may be “formatted in UNIX time or RFC3339”. Set it in release pipelines so a rebuilt document gets the same timestamp and, with the default ID, the same @id. go-vex serializes statement timestamps in UTC.

vexctl add: append and bump the version

The spec says a document’s version “must be incremented when any content within the VEX document changes”. add does that for you:

vexctl add --in-place api-gateway.vex.json \
  "pkg:oci/api-gateway@sha256:<digest>?repository_url=registry.example.com/team" \
  CVE-2026-23456 under_investigation

Illustrative. Per internal/cmd/add.go, add:

  • reads the document from the first positional argument or -d/--document, and writes to stdout unless you pass -i/--in-place or --file;
  • copies the document’s last_updated (or timestamp) into any statement that has no timestamp of its own, so those statements keep their inherited date once the document changes;
  • refuses the new statement if any existing statement’s timestamp or last_updated is later than the new time (“date cannot be older than other statements”);
  • appends the statement, sets the document’s last_updated and increments version.

The time check matters with SOURCE_DATE_EPOCH: an epoch older than the newest statement makes add fail rather than write an out-of-order history.

vexctl merge: a timeline, not a verdict

merge exists for the case the README describes, “when more than one stakeholder is issuing VEX metadata about a piece of software”:

vexctl merge --author="Example Corp PSIRT" \
  --product="pkg:apk/wolfi/[email protected]" \
  examples/openvex/document1.vex.json examples/openvex/document2.vex.json > merged.vex.json

What it does, from Merge() in pkg/ctl/implementation.go:

  1. Filters, optionally. With --product and/or --vuln, only matching statements are kept. Product matching is go-vex’s, which compares purls rather than plain strings.
  2. Fills timestamps. A statement without a timestamp takes its source document’s timestamp. If both are missing, merge fails: “unable to cascade timestamp from doc to timeless statement”.
  3. Keeps everything. Every matching statement is copied. There is no deduplication and no conflict resolution.
  4. Sorts. Statements are sorted by vulnerability name (string order), then by timestamp, oldest first.
  5. Names the result deterministically. Without --id, the new @id is merged-vex- plus the SHA-256 of the input documents’ @id values, sorted and joined with :. A document with no @id contributes VEX-DOC-<position>.
  6. Starts a fresh document. Version 1, a new timestamp, and Unknown Author unless you pass --author.

Who wins? Not merge. go-vex’s EffectiveStatement() returns the last matching statement after the same sort, so the newest statement for a product and vulnerability is the current status. That is how the README explains a merged history of under_investigation followed by fixed: tools “replay” the statements in order.

We ported steps 1 to 5 to Python (product matching simplified to exact strings) and ran the port on the two example documents in the vexctl repository:

$ python3 -I merge_port.py document2.vex.json document1.vex.json
merged-vex-6b33f63783819578804350ba1cde277ddd8f90aa2bbcb706d19a61d211a8443f
2023-12-05T05:04:34.77929922Z CVE-1234-5678 under_investigation
2023-12-05T05:06:38.099731287Z CVE-1234-5678 fixed
effective: fixed

Passing the files in the other order produced the same @id, because the IDs are sorted before hashing. That is a property of the port matching the source; treat it as a reading aid, not a test of the vexctl binary.

Merge pitfalls

  • Clock skew decides conflicts. Two issuers stating different statuses for the same product rely on their timestamps alone. A supplier’s not_affected with a later clock beats your own affected. Merge per issuer, or review conflicts before publishing.
  • Output is stdout only. merge registers no --file flag in v0.4.4; redirect the output.
  • The flag is --vuln. The command’s own help example shows --vulnerability=CVE-2022-3294, but the flag registered in v0.4.4 is --vuln (constant vulnLongFlag = "vuln"). Use --vuln.
  • Merged documents grow. History is kept, so a long-lived merged file accumulates every status change. That is by design; prune by publishing a new document rather than editing statements in place.

vexctl attest: wrap, sign, attach

vexctl attest api-gateway.vex.json                      # unsigned in-toto statement to stdout
vexctl attest --sign api-gateway.vex.json               # sign with the sigstore flow
vexctl attest --attach api-gateway.vex.json             # sign and attach to each image subject
vexctl attest --attach api-gateway.vex.json registry.example.com/team/api-gateway@sha256:<digest>

Illustrative. From internal/cmd/attest.go and pkg/ctl/ctl.go:

  • The predicate is the OpenVEX document; go-vex sets the predicate type to https://openvex.dev/ns/v0.2.0.
  • Without positional image arguments, subjects come from the document’s products. pkg:oci purls become image references (the help text’s example: pkg:oci/kube-apiserver?repository_url=registry.k8s.io&tag=v1.26.0 becomes registry.k8s.io/kube-apiserver:v1.26.0), and references without a digest “will trigger a network lookup to read the image digest from the registry”.
  • Products that are neither oci purls nor image references are kept only if they carry sha256 or sha512 hashes. Otherwise they are skipped with a warning, or rejected with an error if you named them explicitly.
  • --attach (-a) “always implies –sign as sigstore does not support attaching unsigned attestations”. --refs (-r) names the images to attach to when automatic attachment fails.

If your scanner reads the attestation from the registry, check the predicate type it accepts. Our Trivy --vex oci guide covers how Trivy matches OpenVEX predicate types and why you should verify the signature yourself before trusting what it finds.

Where vexctl fits in a patch-decision flow

VEX is the last filter before a finding becomes work: a not_affected statement with a sound justification closes a scanner finding that KEV, EPSS or CVSS would otherwise push up the queue. Our vulnerability prioritization workflow shows where that step sits between the CVE record and the ticket. Product IDs are where most VEX fails in practice, so check the matching rules in our OpenVEX products and subcomponents guide before you publish, and see the CycloneDX VEX mapping if your consumers expect CycloneDX.

Two more commands exist and are out of scope here: vexctl filter applies VEX to SARIF results (the README says “We support results files in SARIF for now”), and vexctl generate builds documents from “golden” template files (default directory .openvex/templates).

Limits of this article

  • We read the v0.4.4 source and README; we did not run the vexctl binary. Commands are marked illustrative. The merge output comes from a Python port of the merge and sort logic, not from vexctl.
  • Behaviour may change after v0.4.4. Re-check flags with vexctl <command> --help against the version you install.
  • vexctl writes OpenVEX only. CSAF and CycloneDX VEX producers follow their own formats.

Sources and verification

Important claimSourceStatus
v0.4.4 is the newest tag; dependency versionsvexctl v0.4.4 go.mod, git tagsVerified
Flags, defaults and validation rulesinternal/cmd/options.go, go-vex vex.goVerified
add version bump and time checksinternal/cmd/add.goVerified
Merge filters, keeps, sorts and hashes IDspkg/ctl/implementation.go, go-vex statement.goVerified (source); example run via Python port
Latest statement is the effective onego-vex vex.go EffectiveStatementVerified
Attest predicate type and subject rulesinternal/cmd/attest.go, pkg/ctl/ctl.go, go-vex attestationVerified
Spec MUSTs for author, version, justification, action statementOpenVEX specificationVerified

Frequently asked questions

What is vexctl used for?

vexctl is the OpenVEX project's command-line tool for creating VEX documents, appending statements to them, merging several documents, wrapping a document in a signed in-toto attestation and filtering SARIF scanner results with VEX data.

Does vexctl merge pick the newest status?

No. In v0.4.4 the merge command keeps every statement that matches the optional --product and --vuln filters and sorts them by vulnerability name, then timestamp. The newest statement wins only when a consumer applies the OpenVEX rule of reading the latest statement for a product and vulnerability.

How do I add a statement to an existing OpenVEX document?

Use vexctl add with the document path, product, vulnerability and status, for example vexctl add --in-place doc.vex.json pkg:... CVE-... fixed. It appends the statement, increments the document version, sets last_updated and refuses to add a statement dated earlier than existing ones.

Why does vexctl attest skip some products?

Attestation subjects need an image reference or a digest. vexctl converts oci purls to image references and keeps products with sha256 or sha512 hashes; other purls without hashes are skipped with a warning, or cause an error if you passed them explicitly as subjects.

VexOpenvexVexctlSigstoreIn-TotoSbomSupply Chain SecurityVulnerability Management