Skip to content

The subject component

Set metadata.component, the thing the document describes, instead of the name and version the CLI reads from git, and add its supplier, licences and hashes.

Updated 04 Nov 2026Markdown

metadata.component is, in CycloneDX’s words, “the component that the BOM describes”. Every package in components hangs off it in the dependency graph. By default the CLI describes the repository it scanned. When the document is really about a release, a container image or a product, say so.

What the CLI derives

Member Derived from
type application
bom-ref urn:project. Never changed, because every root edge in dependencies refers to it.
name The repository name in the git remote, else the repository directory
version The tag on HEAD, else the first 8 characters of the commit
description Source code repository
externalReferences One vcs reference per git remote, SSH remotes rewritten to HTTPS
authors The repository’s recent committers (CycloneDX 1.6 and later)
properties vulnetix:git/*: branch, commit, commit time, message and author, tags, dirty state, worktree, repository root

Flags

Flag Type Default Description
--component-name string the repository name metadata.component.name
--component-version string the HEAD tag or commit metadata.component.version
--component-type string application metadata.component.type: application, framework, library, container, platform, operating-system, device, device-driver, firmware, file, machine-learning-model, data, cryptographic-asset
--component-group string metadata.component.group, such as com.acme
--component-purl string metadata.component.purl

An unknown --component-type is rejected before the scan starts. Each flag has a VULNESIS_COMPONENT_* environment variable.

Only the members you set change. The git properties, the vcs references and the committers stay, because they are still true of the source the document was built from.

# The SBOM of a release, not of a branch
vulnetix cdx \
  --component-name payment-service --component-version "$VERSION" \
  --component-group com.acme --component-purl "pkg:generic/acme/payment-service@$VERSION"

# The SBOM of a built image
vulnetix cdx --container-archive image.tar \
  --component-type container --component-name payment-service --component-version "$VERSION"

More than the flags

The flags cover the identity of the subject. Anything else CycloneDX allows on a component goes in an overlay under metadata.component: its supplier, manufacturer, publisher, licenses, hashes, cpe, copyright or pedigree.

{
  "metadata": {
    "component": {
      "type": "application",
      "name": "payment-service",
      "supplier": { "name": "Acme Ltd", "url": ["https://acme.example"] },
      "licenses": [ { "license": { "id": "Apache-2.0" } } ],
      "copyright": "Copyright 2026 Acme Ltd"
    }
  }
}

A flag wins over the overlay for the member it sets, so --component-version "$VERSION" with this overlay still writes the pipeline’s version.

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