# BYOS SBOM Ingestion

Overview

Bring-your-own SBOM (BYOS) uploads accept SPDX and CycloneDX JSON and register them in the SBOM ledger for analysis.

Supported formats

• CycloneDX JSON: 1.4, 1.5, 1.6
• SPDX JSON: 2.3, 3.0

Upload endpoint

• POST /sbom/upload or POST /api/v1/sbom/upload
• Required: artifactRef, plus sbom (JSON object) or sbomBase64.
• Optional: format hint (cyclonedx or spdx) and source metadata.

Example:

{
  "artifactRef": "acme/app:2.0",
  "sbom": { "spdxVersion": "SPDX-2.3", "packages": [] },
  "source": { "tool": "syft", "version": "1.9.0" }
}

Validation notes

• CycloneDX requires bomFormat and supported specVersion.
• SPDX requires spdxVersion and a supported version number.
• Quality scoring prefers components with PURL, version, and license metadata.
• Lifecycle enrichment runs after format validation and normalization. It preserves lifecycle hints from SBOM component metadata and uses offline local catalog rules to flag known unsupported runtime lines.
• Accepted uploads can return validationResult.tags and validationResult.lifecycleFindings. runtime:eol means ingestion identified an EOL runtime component and Policy can consume the tag with sbom.has_tag("runtime:eol").
• Lifecycle catalog updates are an operator-maintained offline input. The upload path must stay deterministic and must not fetch lifecycle data from the internet.

Troubleshooting

• “sbom or sbomBase64 is required”: include an SBOM payload in the request.
• “Unable to detect SBOM format”: set format explicitly or include required root fields.
• Unsupported SBOM format/version: ensure CycloneDX 1.4–1.7 or SPDX 2.3/3.0.
• Low quality scores: include PURLs, versions, and license declarations where possible.
• Unexpected runtime:eol warning: inspect validationResult.lifecycleFindings for the matched component, source, EOL date, and tags, then refresh or correct the local lifecycle catalog if the source rule is stale.