Skip to content

vens generate

Who this is for: anyone looking up a flag or an exit code. By the end of this page: you know every flag of the generate command.

For a walkthrough, see Quickstart.


Synopsis

vens generate --config-file CONFIG --sbom-serial-number urn:uuid:<uuid> INPUT OUTPUT [flags]

Generate a CycloneDX VEX document from a Trivy or Grype vulnerability report, with contextual OWASP risk scores computed by an LLM.


Arguments

Argument Description
INPUT Path to a Trivy or Grype JSON report. Format is auto-detected.
OUTPUT Path where the generated CycloneDX VEX document will be written. Parent directory must exist.

Required flags

--config-file <path>

Path to your config.yaml file.

--sbom-serial-number <urn:uuid:...>

The serialNumber of the CycloneDX SBOM paired with this scan. Vens uses it to build the BOM-Link urn:cdx:<uuid>/<version>#<bom-ref> references in the generated VEX so each affects entry resolves back to that SBOM. Required and must start with urn:uuid:.

vens generate \
  --config-file ./vens.yaml \
  --sbom-serial-number urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79 \
  report.json vex.json

Generating an ad-hoc UUID on Linux/macOS:

SBOM_UUID="urn:uuid:$(uuidgen | tr '[:upper:]' '[:lower:]')"

Optional flags

--llm <provider>

Pick the LLM provider. Default: auto, which resolves to openai. There is no detection: auto never looks at your environment to choose the provider, so an Anthropic or Gemini key on its own still sends the run to OpenAI, which then stops with openai: OPENAI_API_KEY is not set. Only the choice of provider ignores the environment; once it lands on OpenAI the run reads OPENAI_MODEL, OPENAI_API_KEY and, if you set it, OPENAI_BASE_URL.

Value Provider Env vars
auto OpenAI, same as openai OPENAI_API_KEY, OPENAI_MODEL
openai OpenAI OPENAI_API_KEY, OPENAI_MODEL
anthropic Anthropic Claude ANTHROPIC_API_KEY, ANTHROPIC_MODEL
googleai Google AI (Gemini) GOOGLE_API_KEY (or GEMINI_API_KEY), GOOGLE_MODEL
ollama Ollama (local) OLLAMA_MODEL (required), OLLAMA_HOST

Any provider other than OpenAI needs an explicit --llm.

The *_MODEL variables are optional for the three cloud providers and fall back to gpt-5.4-mini, claude-sonnet-4-6 and gemini-2.5-flash, logged as a warning at startup. Ollama has no default: without OLLAMA_MODEL the run stops with ollama: set the OLLAMA_MODEL environment variable.

vens generate --llm openai --config-file c.yaml --sbom-serial-number "$SBOM_UUID" in.json out.json

--llm-batch-size <int>

Number of CVEs sent to the LLM per request. Default: 10.

  • Lower values (e.g. 5) — fewer CVEs per call, more calls, safer for small context windows.
  • Higher values (e.g. 20) — fewer calls, faster, uses more tokens per call.
vens generate --llm-batch-size 15 ...

--llm-temperature <float>

LLM sampling temperature. Only sent to the provider when the flag is explicitly passed — by default no temperature is sent at all (the 0.0 default is never forwarded on its own), so each provider applies its own default instead: 0.8 for Ollama, 1.0 for OpenAI, Gemini and Anthropic. Values above 0 — including those provider defaults — introduce randomness and are not recommended for production scoring. Passing --llm-temperature 0 together with --llm-seed reduces drift between runs, but it doesn't make runs deterministic. Note: some models don't take an explicit temperature. Current Anthropic generations reject it, so passing the flag with one of them fails fast with a clear error; OpenAI reasoning models (o-series and gpt-5*, which includes the default gpt-5.4-mini) ignore it.

--llm-seed <int>

Seed forwarded to the LLM when the provider supports it. Default: 0 (no explicit seed sent). OpenAI, Google AI and Ollama accept a seed parameter; Anthropic has none, so on Anthropic this flag is silently ignored.

Reproducibility is best-effort, not a guarantee

Even at --llm-temperature 0.0 with a fixed --llm-seed, byte-identical scores across runs are not guaranteed. Cloud LLM providers periodically update server-side models without changing the API model name, and most of them do not expose true deterministic decoding. What Vens does do is:

  • Compute the final OWASP score in Go from the LLM's four 0-9 component scores (pkg/generator/generator.go). Small drifts in the component scores are absorbed by the arithmetic.
  • Keep the same prompt, schema and ordering across runs.

In practice, expect score drift of ±1–3 points on a minority of CVEs between runs with the same config and model. If you need strict reproducibility (for audit evidence at a fixed point in time), pin a local Ollama model version, pass --llm-temperature 0 --llm-seed <n>, and archive the --debug-dir output — together they give you a byte-exact record of what was sent and returned.

--input-format <auto|trivy|grype>

Force the input parser. Default: auto.

vens generate --input-format grype --config-file c.yaml --sbom-serial-number "$SBOM_UUID" report.json out.json

--output-format <auto|cyclonedxvex>

Output format. Default: auto. Currently only cyclonedxvex is supported.

--cyclonedx-spec-version <1.6|1.7>

CycloneDX spec version for the VEX output. Default: 1.6.

The default is 1.6 because no released Dependency-Track version can ingest a 1.7 BOM yet (it is rejected as an unrecognized specVersion) — 1.6 lands out of the box. Opt up to 1.7 if your consumer understands it. The --attest sidecar is emitted at the same spec version as the VEX. Any value other than 1.6 or 1.7 is rejected with an error.

vens generate --cyclonedx-spec-version 1.7 \
  --config-file c.yaml \
  --sbom-serial-number "$SBOM_UUID" \
  report.json out.json

--debug-dir <path>

Directory where Vens writes, for every LLM call, the prompts it sends and the raw reply it gets back. Useful for auditing scores, debugging unexpected results, and producing evidence for compliance reviews.

Each run writes into a run-* subdirectory of its own, logged when the run starts, so runs that share a --debug-dir, even in parallel, never overwrite each other:

vens generate \
  --debug-dir ./vens-debug \
  --config-file c.yaml \
  --sbom-serial-number "$SBOM_UUID" \
  report.json out.json
# ... level=INFO msg="Writing debug files" dir=./vens-debug/run-3787846641
ls vens-debug/run-3787846641/
# batch-00001.human.prompt  batch-00001.response  batch-00001.system.prompt
# batch-00002.human.prompt  batch-00002.response  batch-00002.system.prompt
# ...

Each run adds a new run-* directory, and nothing deletes the old ones. Remove them when you are done, for example with rm -rf vens-debug/run-*.

What you get, for each LLM call, numbered from 00001 in call order:

  • batch-NNNNN.system.prompt — the full system prompt sent to the LLM, including your config.yaml context formatted as text, the OWASP scoring instructions, and the JSON schema the LLM must return. Shape (truncated):

    You are a talented security expert scoring vulnerabilities using OWASP Risk Rating Methodology.
    
    SYSTEM CONTEXT:
    Project: my-python-api
    Description: Customer-facing Python API handling user data
    Exposure: internet
    Data Sensitivity: high
    Business Criticality: high
    Compliance Requirements: GDPR
    Security Controls: WAF
    ...
    
    TASK: For EACH vulnerability, analyze its specific characteristics and score 4 factors (0-9):
    1. THREAT_AGENT ...
    ...
    #### Output format: JSON Schema
    {...}
    
  • batch-NNNNN.human.prompt — the JSON array of CVEs sent in that call (vuln id, pkg, title, description, severity).

  • batch-NNNNN.response — the model's raw reply to that call, with its scores and reasoning for each CVE. It is written before Vens parses it, so a reply that fails to parse is on disk too. A call that failed, such as a batch the provider truncated, has no .response.

Numbers count LLM calls, not --llm-batch-size batches: a batch the provider truncates is retried in two halves, and a CVE the model leaves out is asked about again on its own, each in a call with its own number.

Matching the files to the --attest evidence

Match a call's files to its evidence-batch-N entry by prompt_hash, not by number: the attestation records only the calls that succeeded, so after a truncated batch, batch-00002 can be evidence-batch-1. prompt_hash is the SHA-256 of the system prompt, two newlines, then the human prompt:

cd vens-debug/run-3787846641
{ cat batch-00002.system.prompt; printf '\n\n'; cat batch-00002.human.prompt; } | sha256sum
jq -r '.declarations.evidence[] | .["bom-ref"] + " " + (.data[] | select(.name == "prompt_hash") | .contents.attachment.content)' ../../out.attestation.cdx.json

An ask-again for a lone CVE repeats its prompt word for word, so two entries can share a hash. They come in the same order as the files, and each entry's raw_response is its call's .response, base64-encoded.

Per-CVE component scores and the LLM's reasoning are also logged to stderr at INFO/DEBUG level (run with DEBUG=1 to see them).

Treat --debug-dir output as sensitive

These files contain the full text of what was sent to the LLM provider and of what it sent back:

  • Your config.yaml context, including the notes field verbatim.
  • Every CVE identifier from the scanned image, plus titles and descriptions.
  • The model's reasoning about each CVE in your context.

On Linux and macOS, Vens creates each run directory and its files readable by your user only (0700 and 0600). Do not commit them to a public repository. In CI, either delete the directory after inspection or upload it to an access-controlled artifact store.

Retention for compliance workloads

If you need the debug output as audit evidence (HIPAA-style 6-year retention, SOC 2 change log, PCI-DSS risk decisions), store it in the same encrypted, access-controlled system you use for other security audit logs. Treat each run-* directory as one entry in your vulnerability-triage evidence chain, indexed by scan date and by the Git SHA of the config.yaml that produced it. Reasoning can only be reconstructed later if both the config.yaml version and the debug files are preserved — a copy of the VEX alone is not enough.

--attest

Opt-in. Emits a CycloneDX Attestations (CDXA) sibling file next to the VEX, capturing what the LLM saw and produced so the run can be audited and reproduced later. Off by default.

vens generate --attest \
  --config-file c.yaml \
  --sbom-serial-number "$SBOM_UUID" \
  report.json out.cdx.json
# writes out.cdx.json AND out.attestation.cdx.json

What it contains (CDX BOM at the same spec version as the VEX — 1.6 by default, or whatever --cyclonedx-spec-version selects — everything under declarations):

  • claims[] — one per scored CVE/affected component: the assessment (predicate + reasoning), linked to its target component and to the evidence that backs it. When a claim's package and version were not in the prompt of the batch it cites (a later batch reusing the CVE's first score, or a held-back row filled in by a later batch), its predicate ends with "; this package was not in the cited batch's prompt".
  • targets.components[] — the affected components the claims point at
  • evidence[] — one per LLM batch, recording how the scoring was produced:
    • generation_method — llm
    • provider / model — backend and model used (e.g. openai / gpt-5.4-mini); when the provider's *_MODEL env var is unset, vens falls back to that provider's default and logs it
    • seed — the LLM seed (0 if unset)
    • temperature — the sampling temperature (only present when --llm-temperature was explicitly passed)
    • prompt_hash — SHA-256 of system_prompt + "\n\n" + human_prompt
    • input_hash — SHA-256 of the scanner report bytes
    • config_hash — SHA-256 of the config.yaml used
    • raw_response — base64-encoded raw LLM JSON reply (flagged sensitiveData)
  • assessors[] + attestations[] — tie the claims to vens as the producer; a human reviewer can add their own assessor/attestation over the same claims without touching the LLM evidence, but not by editing a signed sidecar (see the note there)

The producing vens version is recorded in metadata.tools. The attestation is a file component that links to the VEX it describes through a bom external reference (urn:cdx:<vex-serial>/<version>).

Reproducibility scope

The attestation records the inputs and outputs of each LLM call. Recreating a score also requires the config.yaml used at the time — keep it under version control alongside the attestation.

The attestation is sensitive — store it like audit evidence

The claims spell out, in clear text, which CVEs you scored, their scores and the model's reasoning, and raw_response holds the full model reply base64-encoded, not encrypted (anyone with the file can decode it). The prompt, scanner report and config are kept only as SHA-256 hashes, so the raw vulnerability list is not embedded, but the assessment itself is fully readable. In CI, write the attestation to the same access-controlled store as your other security evidence, not to a public build artifact.

--attest-signing-key <path>

Opt-in. Requires --attest. Signs the CDXA sidecar with a BOM-level JSF signature (signature.signers[], algorithm ES256). The value is a path to a file, not the key itself: an unencrypted PKCS#8 PEM ECDSA P-256 (prime256v1) private key. Passphrase-protected keys are rejected; openssl pkey -in enc.key -out attest.key decrypts one.

One-time setup: generate the key once, keep attest.key in your CI secret store, and publish attest.pub.pem somewhere your verifiers already trust (for example, in the repo).

(umask 077; openssl ecparam -name prime256v1 -genkey -noout \
  | openssl pkcs8 -topk8 -nocrypt -out attest.key)
openssl ec -in attest.key -pubout -out attest.pub.pem

Per run, write the key from your secret store to a 0600 file (umask 077 / chmod 600) before running vens:

vens generate --attest --attest-signing-key attest.key \
  --config-file c.yaml \
  --sbom-serial-number "$SBOM_UUID" \
  report.json out.cdx.json
# out.attestation.cdx.json carries signature.signers[0] {algorithm,keyId,publicKey,value}

Optional --attest-signing-key-id <id> (requires --attest-signing-key) sets the JSF keyId label (default: hex SHA-256 fingerprint of the public key's SPKI). It is only a label: it does not identify who signed.

Fail-closed: --attest-signing-key without --attest, an empty --attest-signing-key=, --attest-signing-key-id without a key path, or an unreadable, encrypted or non-P-256 key is a hard error before any output is written. A SEC1 EC PRIVATE KEY is rejected too; openssl pkcs8 -topk8 -nocrypt converts it.

What the signature proves

It proves the sidecar has not changed since someone holding the private key signed it, if you check it against your own public key. It does not sign the VEX (the sidecar names the VEX by serial number and version only, with no hash), it does not prove when it was signed, and keyId is only a label. The publicKey embedded in the file is self-asserted: checking against it only catches accidental damage, because anyone who edits a claim can re-sign the file with their own key.

Editing a signed sidecar, for example to add a reviewer's assessor or attestation, breaks the signature. Keep the vens-signed file as is and record the review in a separate CDXA file, or add a second signer to signature.signers[].

Verify (CycloneDX JSON JSF; cyclonedx-cli cannot verify JSON signatures today). Check against the public key from the setup step, and check that the sidecar belongs to the VEX next to it:

npm install @cyclonedx/sign@0.5.2
node --input-type=module -e '
  import { verify } from "@cyclonedx/sign/jsf";
  import { readFileSync } from "node:fs";
  const doc = JSON.parse(readFileSync("out.attestation.cdx.json", "utf8"));
  const r = await verify(doc, { allowedAlgorithms: ["ES256"], publicKey: readFileSync("attest.pub.pem", "utf8") });
  const vex = JSON.parse(readFileSync("out.cdx.json", "utf8"));
  const link = doc.metadata?.component?.externalReferences?.find(e => e.type === "bom")?.url;
  const want = `urn:cdx:${vex.serialNumber.replace(/^urn:uuid:/, "")}/${vex.version}`;
  console.log("valid:", r.valid, "bom link matches VEX:", link === want);
  process.exit(r.valid && link === want ? 0 : 1);'

Without the bom link check, a signed sidecar left over from an earlier run still verifies next to a new VEX.

Digest rule (for a custom verifier): keep only the signer you are checking in signature.signers, drop its value, then take the SHA-256 of the JCS form of the whole document (JSF section 8). For the single signer vens writes, the signature member becomes {"signers":[<signer without value>]}, every other member stays as is, and it stays correct after a countersignature. Do not strip the whole signature member.

--sbom-version <int>

BOM-Link version number used alongside --sbom-serial-number. Default: 1.


Environment variables

Variable Purpose
OPENAI_API_KEY OpenAI credentials
OPENAI_MODEL OpenAI model name (e.g. gpt-5.4-mini)
ANTHROPIC_API_KEY Anthropic credentials
ANTHROPIC_MODEL Anthropic model name (e.g. claude-sonnet-4-6)
GOOGLE_API_KEY Google AI credentials
GEMINI_API_KEY Google AI credentials (fallback used when GOOGLE_API_KEY is unset)
GOOGLE_MODEL Google AI model name (e.g. gemini-2.5-flash)
OLLAMA_MODEL Ollama model name (e.g. llama3.1)

Exit codes

Code Meaning
0 Success — VEX written to OUTPUT
1 Generic failure (I/O, config validation, LLM call)
2 Invalid CLI usage (bad flags or arguments)

Note

vens generate does not fail based on CVE severity. To fail a CI pipeline on high contextual risk, filter the output VEX yourself — see Prioritize a CVE backlog.


Examples

All examples assume $SBOM_UUID is set, e.g.:

SBOM_UUID="urn:uuid:$(uuidgen | tr '[:upper:]' '[:lower:]')"

Basic

export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-5.4-mini

trivy image python:3.11-slim --format json --output report.json
vens generate --config-file vens.yaml --sbom-serial-number "$SBOM_UUID" report.json vex.json

With Grype

grype python:3.11-slim -o json > report.json
vens generate --config-file vens.yaml --sbom-serial-number "$SBOM_UUID" report.json vex.json

With debug output

vens generate \
  --config-file vens.yaml \
  --sbom-serial-number "$SBOM_UUID" \
  --debug-dir ./debug \
  --llm-batch-size 5 \
  report.json vex.json

Forcing Anthropic

export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_MODEL=claude-sonnet-4-6
vens generate --llm anthropic --config-file vens.yaml --sbom-serial-number "$SBOM_UUID" report.json vex.json

Air-gapped with Ollama

# Ollama running on localhost:11434
export OLLAMA_MODEL=llama3.1
vens generate --llm ollama --config-file vens.yaml --sbom-serial-number "$SBOM_UUID" report.json vex.json

As a Trivy plugin

Every example above also works as trivy vens — same flags, same behaviour:

trivy vens generate --config-file vens.yaml --sbom-serial-number "$SBOM_UUID" report.json vex.json

See also