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

BYOS SBOM ingestion

Overview

• Accepts external SBOMs and runs them through validation, normalization, and analysis triggers.
• Stores the SBOM artifact in the scanner object store and records provenance metadata.
• Emits a deterministic analysis job id tied to the upload metadata.

API

• POST /api/v1/sbom/upload
• GET /api/v1/sbom/uploads/{sbomId}

Example request:

{
  "artifactRef": "example.com/app:1.0",
  "sbomBase64": "<base64>",
  "format": "cyclonedx",
  "source": { "tool": "syft", "version": "1.0.0" }
}

Supported formats

• CycloneDX JSON 1.4-1.6 (bomFormat, specVersion)
• SPDX JSON 2.3 (spdxVersion)
• SPDX JSON 3.0 (structural checks only; schema validation pending)

CLI

stella sbom upload --file sbom.json --artifact example.com/app:1.0

Troubleshooting

• Missing format: ensure bomFormat (CycloneDX) or spdxVersion (SPDX).
• Unsupported versions: CycloneDX must be 1.4-1.6; SPDX must be 2.3 or 3.0.
• Empty component lists are accepted but reduce quality scores.