Overview
vg evidence is Vibgrate Evidence: signed, reproducible regulatory evidence for products with digital elements. Register your products, freeze each shipped release into an immutable component manifest, and answer the question a regulator asks after a vulnerability lands — which shipped products contain it, at which versions, in which markets, still in support? — as evidence a third party can verify offline.
Evidence, not compliance. Vibgrate Evidence produces evidence to support your obligations under a reporting regime. It does not determine compliance, is not a certification, and is not legal advice. The scope determination, the "actively exploited" determination, and the filing decision are yours.
Jurisdiction-neutral: regimes
Reporting duties are modelled as regimes. The EU Cyber Resilience Act (CRA) (--regime cra) is the first; DORA incident reporting (--regime dora-incident) ships too. A new jurisdiction is a regime profile, not a new command — so the command set stays open as other jurisdictions introduce similar reporting duties. Run vg evidence regimes to list them.
Usage
# One-time setup: org, coordinator CSIRT, and the person with filing authority
vg evidence init --coordinator NCSC-NL --responsible "Jordan Alvarez" --filing-authority
# Register a product with digital elements (PDE)
vg evidence product add "Acme Edge Gateway" --markets DE,FR,NL --in-scope --until 2031-01-01
# Freeze a shipped release into an immutable manifest (from an SBOM or a scan)
vg evidence release acme-edge-gateway 4.2.0 --from .vibgrate/scan_result.json
# Or, for a container image, from what BuildKit built
vg evidence release acme-edge-gateway 4.2.0 --image ghcr.io/acme/edge-gateway:4.2.0
# The flagship: which shipped products contain this vulnerability?
vg evidence exposure CVE-2026-48282 --offline --advisory advisory.json
# A deterministic readiness gap report
vg evidence readiness
The flagship: exposure
vg evidence exposure <vuln> matches the advisory against the components in your frozen release manifests — what you actually shipped, not what is in main today. It is deterministic (identical inputs give a byte-identical answer) and never guesses: a bound product with no frozen manifest returns undetermined with a reason, never a false "not affected".
| Exit code | Meaning |
|---|---|
0 | No exposure in any shipped release |
2 | Exposure found — fail the build |
3 | Undetermined — manual review required |
1 | Operational error |
Advisories come from OSV (online) or a local --advisory file (OSV- or Vibgrate-shaped), so the whole path runs --offline. Add --bundle <dir> to emit a signed evidence bundle.
Freeze a container release from what the build wrote
A frozen manifest is only as good as the facts it records. For a container image, the build already produced them: BuildKit (the engine behind docker build and docker buildx build, and the default builder since Docker 23) writes the image digest to a metadata file, attaches a SLSA provenance attestation naming the source commit and base images, and can attach an SBOM. vg evidence release reads those instead of asking you to type them.
# At build time — BuildKit writes the facts
docker buildx build --push --provenance=true --sbom=true \
--metadata-file build-metadata.json -t ghcr.io/acme/edge-gateway:4.2.0 .
# At release time — freeze from the image and its attached attestations
vg evidence release acme-edge-gateway 4.2.0 --image ghcr.io/acme/edge-gateway:4.2.0 --ship-date 2026-02-01
# Or from the files, with no Docker daemon
vg evidence release acme-edge-gateway 4.2.0 --from sbom.spdx.json --buildkit-metadata build-metadata.json --provenance provenance.intoto.json
| Flag | Reads | Records |
|---|---|---|
--image <ref> | docker image inspect and docker buildx imagetools inspect | Image digest, org.opencontainers.image.* labels, attached provenance and SBOM. The attached SBOM becomes the manifest when --from is not given. Contacts the registry when the reference is not present locally. |
--buildkit-metadata <file> | The --metadata-file JSON | Image digest and build reference |
--provenance <file> | A SLSA provenance attestation — DSSE envelope, in-toto Statement, or bare predicate | Source repository, commit, builder, base images |
--from <file> | A Vibgrate scan artifact, a CycloneDX or SPDX SBOM, or an SBOM attestation | The component list |
The facts are stored under build in the frozen manifest. Two honesty rules apply: a typed --digest or --build-id that disagrees with what the build wrote is an error, never a silent preference; and attestation signatures are recorded as unverified — vg carries no registry trust root, so verify them with cosign.
Signed, offline-verifiable evidence
An evidence bundle wraps the deterministic answer in a DSSE / in-toto envelope signed with Ed25519 — the same signing spine as vg build --attest. vg evidence verify <bundle> checks it offline with honest trust states:
| State | Meaning |
|---|---|
verified | Signature checks, signer is trusted (--pub), and the result digest matches |
unverified | Cryptographically intact but the signer is not pinned |
failed | Bad signature, or the result no longer matches its signed digest |
No language model touches any figure in the evidence path, and there is no telemetry in it.
Command reference
| Command | Description |
|---|---|
vg evidence init | Set org, coordinator CSIRT, and the person with filing authority |
vg evidence regimes | List available reporting regimes and their clocks |
vg evidence product add | Register a product with digital elements (PDE) |
vg evidence release | Freeze a shipped release into an immutable component manifest — from an SBOM, a scan, or what BuildKit built |
vg evidence exposure | Which shipped products contain a vulnerability — with signed evidence |
vg evidence readiness | Deterministic gap report against the regime's obligations |
vg evidence drill | Timed dry-run of the determination against a simulated advisory |
vg evidence pack | Build the submission pack a human pastes into the reporting platform |
vg evidence verify | Verify an evidence bundle offline — no account, no network |
vg evidence push | Push products, frozen manifests and a signed exposure bundle to Vibgrate Cloud, which verifies the signature and shows releases, components and the ledger under Govern ▸ Evidence |
vg evidence export | Air-gap bundle of all evidence state |