Skip to content

Supported SBOM formats

Affectra reads SBOMs in CycloneDX and SPDX. You do not say which format a file is. Affectra detects it from the content, not from the file name or the Content-Type header.

Format Versions Encodings
CycloneDX 1.2 to 1.7 JSON, XML
SPDX 2 2.1, 2.2 and 2.3 JSON, tag-value
SPDX 3 3.0 JSON-LD

A file in another format or version is refused with a 400 that says it is not a supported SBOM document. Examples are SPDX 2.4, an SPDX 2 file in YAML, RDF or XML, and a CycloneDX protobuf file. A file that starts with a UTF-8 byte order mark is accepted.

How Affectra tells them apart:

  • JSON with "bomFormat": "CycloneDX" is CycloneDX.
  • JSON with an spdxVersion that starts with SPDX-2. is SPDX 2.
  • JSON with an @context that points to spdx.org/rdf/3. is SPDX 3. Affectra reads the flat list of elements in @graph, as OpenEmbedded and other tools write it.
  • XML whose root declares a cyclonedx.org/schema/bom namespace is CycloneDX XML.
  • A text file that starts with SPDXVersion: is SPDX 2 tag-value.

Affectra limits what one upload may hold, so that one large file cannot slow the service for everyone:

Limit Value When it is exceeded
File size 16 MiB 413, code upload.tooLarge
Components, nested ones included 30,000 413, code sbom.limitExceeded
Dependencies (the edges between components) 150,000 413, code sbom.limitExceeded

The counts are checked before the file is read in full, so a file over a limit is refused quickly. A typical SBOM of a container image or a firmware build has a few hundred to a few thousand components. If yours is larger, upload one SBOM per product or image instead of one for everything.

Text in the file must be valid UTF-8 without control characters. A reference, name or version can have at most 255 characters, a package URL or CPE at most 1,024. If one value is not valid, Affectra refuses the whole file with a 400 and code sbom.invalid, and the reason names the value, for example components[12].name.

When the service is busy with other uploads, it answers 429 with a Retry-After header. Wait that long and send the file again; the upload-sbom action waits and retries once.

Uploading the same file to a release twice keeps one copy.

An upload that carries a signature has more limits. See Sign SBOMs.

Affectra keeps what it needs to find vulnerabilities and exposure (see How matching works):

What CycloneDX SPDX 2 SPDX 3
Components components, including nested ones, and metadata.component packages the elements of type software_Package
Name name, with group in front as group/name name name
Version version versionInfo software_packageVersion
Package URL (purl) purl an external reference of type purl software_packageUrl, or an external identifier of type packageUrl
CPE cpe an external reference of type cpe23Type or cpe22Type an external identifier of type cpe23 or cpe22
Supplier supplier, else publisher supplier suppliedBy
Type type, such as library or firmware primaryPackagePurpose software_primaryPurpose
The thing the SBOM describes metadata.component the package the document DESCRIBES the root element of the document
Dependencies dependencies DEPENDS_ON, CONTAINS, DEPENDENCY_OF, RUNTIME_DEPENDENCY_OF and CONTAINED_BY dependsOn and contains relationships between packages
Tools that wrote the file metadata.tools, in both the old and the new form creators of type Tool createdUsing
Spec version specVersion spdxVersion specVersion in the creation info

The release’s SBOMs tab lists each SBOM with its Components and when it was Uploaded. Fields it does not read, such as licences and hashes, stay in the file. Download the document as uploaded returns it unchanged.

Give each component a package URL where you can. It is the most precise way to name a package.

Some problems do not stop an upload. Affectra stores the SBOM and returns a warning for each, up to 100:

  • A package URL or CPE that is not valid is ignored for that component.
  • Two components with the same bom-ref or SPDX identifier. Affectra keeps the first.
  • A component with no name. Affectra uses its package URL, or else its reference, as the name.
  • Dependencies that name a component that is not in the document are ignored.
  • The signer of the SBOM is not one of your trusted publishers.

The action prints the warnings, and the upload response lists them.

A file that cannot be read at all, such as broken JSON or a missing @graph, is refused with 400 and creates nothing, not even the product or release you named.