Skip to content

Author and customise a CycloneDX document

What you can state about the SBOMs, AI-BOMs and CBOMs the CLI writes, on which commands, and how flags, environment variables and overlay files combine.

Updated 04 Nov 2026Markdown

The CLI fills in a CycloneDX document from what it can observe: the packages, the git repository, the CI provider and the machine. It cannot observe who you are, who supplies what you ship, what licence the document is under, or the services and decisions that sit around the code. From CLI v4.15.0 you can state those yourself, and the document says them in the members CycloneDX defines for them.

Which commands

Command Writes Spec version
vulnetix cdx (alias sbom) .vulnetix/sbom.cdx.json, or --output-file --spec-version, 1.6 or 1.7 (default)
vulnetix aibom .vulnetix/ai-bom.cdx.json --spec-version, 1.6 or 1.7
vulnetix cbom .vulnetix/cbom.cdx.json --spec-version, 1.6 or 1.7
scan, sca, sast, secrets, iac, containers .vulnetix/sbom.cdx.json, and a copy for -o <file>.cdx.json always 1.7

The same flags work on all of them. Commands that change a document somebody else wrote, such as bom enrich and bom import, do not take them: they append themselves to metadata.tools and leave the author’s identity alone.

Three ways to say it

Way Best for
A flag, such as --bom-supplier "Acme Ltd" One value on one run
An environment variable, such as VULNESIS_BOM_SUPPLIER A value a CI job sets once for every step
An overlay file, --bom-overlay acme.cdx.json Anything with structure: a supplier with a URL, services, compositions, annotations, an analysis on a vulnerability

Each member is decided on its own, first answer wins:

  1. The flag.
  2. Its environment variable.
  3. The last overlay file that states it.
  4. What the run derives (the CI or git owner, the repository name, the phases the run read).

So a supplier in an overlay survives a --bom-author flag, because the two set different members.

CycloneDX member Flag Page
serialNumber, version --bom-serial, --bom-version Who made it
metadata.manufacturer --bom-manufacturer, --bom-manufacturer-url Who made it
metadata.authors --bom-author Who made it
metadata.supplier --bom-supplier, --bom-supplier-url Who made it
metadata.lifecycles --lifecycle Document identity
metadata.component --component-name, -version, -type, -group, -purl The subject component
metadata.licenses --bom-license Licences and properties
metadata.properties --bom-property Licences and properties
Anything else in the document --bom-overlay Overlay files

What you cannot set

Member Why
metadata.tools It names the program that wrote the document. CycloneDX defines it as “the tool(s) used in the creation, enrichment, and validation of the BOM”, which is a fact about this run.
metadata.timestamp “The date and time when the BOM was created”: the time of this run.
Any property named vulnetix:* The CLI’s own vocabulary. A value you set there would be indistinguishable from one the scan measured. Use your own prefix.
signature A signature covers the finished document. Sign the output with --sign instead. See Signing documents.

Validation

After every flag and overlay is applied, the document is validated against the CycloneDX schema for its spec version. If anything fails, nothing is written and every violation is listed with its JSON pointer and the input that put it there:

Error: CycloneDX 1.6 validation failed (2 violation(s)):
  /metadata/component/type: value must be one of 'application', 'framework', 'library', 'container', 'platform', 'operating-system', 'device', 'device-driver', 'firmware', 'file', 'machine-learning-model', 'data', 'cryptographic-asset' (set by --component-* or an overlay)
  /services/0/endpoints: got string, want array (from an overlay)

A member that only exists in a later spec version fails at an earlier one: an overlay carrying 1.7’s metadata.distributionConstraints cannot be written with --spec-version 1.6.

The scan family is the exception. A scan’s findings are worth more than the labels on them, so a bad overlay there prints a warning and the scan goes on.

A complete example

vulnetix cdx \
  --bom-manufacturer "Acme Ltd" --bom-manufacturer-url https://acme.example \
  --bom-author "Jane Doe <jane@acme.example>" \
  --bom-supplier "Acme Ltd" \
  --bom-serial "payment-service-2.0.0" --bom-version 1 \
  --component-name payment-service --component-version 2.0.0 \
  --bom-license CC0-1.0 \
  --bom-property acme:team=payments \
  --bom-overlay .vulnetix/overlay.cdx.json \
  --lifecycle build \
  --sign

In GitHub Actions the same values go in inputs or env:. See GitHub Actions.

Environment variables

Variable Flag
VULNESIS_BOM_MANUFACTURER --bom-manufacturer
VULNESIS_BOM_MANUFACTURER_URL --bom-manufacturer-url
VULNESIS_BOM_AUTHORS --bom-author, comma- or semicolon-separated
VULNESIS_BOM_SUPPLIER, VULNESIS_BOM_SUPPLIER_URL --bom-supplier, --bom-supplier-url
VULNESIS_BOM_SERIAL, VULNESIS_BOM_VERSION --bom-serial, --bom-version
VULNESIS_BOM_LICENSES --bom-license, comma- or semicolon-separated
VULNESIS_BOM_PROPERTIES --bom-property, comma- or semicolon-separated name=value
VULNESIS_BOM_OVERLAY --bom-overlay, comma- or semicolon-separated paths
VULNESIS_COMPONENT_NAME, _VERSION, _TYPE, _GROUP, _PURL --component-name, -version, -type, -group, -purl

A list variable splits on commas and semicolons, so a value that contains either belongs in a flag or an overlay instead.

esc
↑ ↓ move↵ openSearches in your browser. A key like autonomy.max or a code like threshold_required jumps straight to it.