git.stella-ops.org/docs/modules/sbomservice/byos-ingestion.md

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.

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.6 or SPDX 2.3/3.0.
• Low quality scores: include PURLs, versions, and license declarations where possible.