Ingesting SBOMs into GUAC
Overview
Software Bill of Materials (SBOM) ingestion is essential in GUAC to help track and analyze dependencies, vulnerabilities, and software supply chain metadata.
Supported document types
GUAC’s ingestion pipeline handles SBOMs as well as other software supply chain documents. The table below lists document types with registered ingestion parsers. Some types are produced by GUAC collectors or certifiers and arrive with their type already set rather than being detected from a user-supplied file.
| Document type | Description |
|---|---|
SPDX | SPDX software bills of materials. |
CycloneDX | CycloneDX software bills of materials. |
DSSE | DSSE envelopes; embedded payloads are unpacked and processed recursively. |
SLSA | SLSA provenance statements carried in in-toto statements. |
ITE6VUL | GUAC vulnerability certification statements. |
ITE6EOL | GUAC end-of-life certification statements. |
ITE6REF | GUAC reference certification statements. |
ITE6MALWARE | GUAC malware certification statements. |
ITE6CD | ClearlyDefined legal and license certification statements. |
SCORECARD | OpenSSF Scorecard documents. |
DEPS_DEV | deps.dev documents used by GUAC. |
CSAF | Common Security Advisory Framework documents. |
OPEN_VEX | OpenVEX documents. |
OPAQUE | Internal container type used while unpacking JSON Lines input. |
INGEST_PREDICATES | Direct GUAC graph predicates for tightly controlled environments. |
INGEST_PREDICATES bypasses the backing-attestation validation used by normal ingestion. It is disabled by default and is registered by guacone collect only when the GUAC_DANGER environment variable is set.
JSON Lines
GUAC recognizes JSON Lines input. A JSON Lines document is treated as an OPAQUE container, unpacked line by line, and each line is processed again as an independent JSON document. Each line must therefore be valid JSON containing a document type that GUAC can process.
Compressed input
GUAC can decompress BZIP2 and Zstandard input before detecting the document format and type. Files ending in .bz2 and .zst are recognized by extension; GUAC can also detect these encodings from their file signatures. After decompression, the document continues through the normal format and type detection pipeline.
Ingestion Methods
Manual Ingestion
Use the following command to ingest an SBOM file into GUAC for analysis and tracking dependencies:
guacone collect files my-sbom.spdx.json
This method is ideal when working with specific files or testing new SBOMs locally. File ingestion also works for directories using standard shell globs.
Label collected SBOM data
Use guaccollect files with a repeatable --label key=value flag to identify which team, environment, or source a collected SBOM belongs to:
guaccollect files --label team=platform --label env=production my-sbom.spdx.json
During ingestion, GUAC records these labels as HasMetadata relationships on the packages or artifacts referenced by the collected SBOM. The key must not be empty; specify --label more than once to attach multiple key-value pairs. See guaccollect flags for more information.
Daemon-Mode Ingestion
When configured, GUAC operates in daemon mode, using collectors to poll for new SBOMs at regular intervals.
To use daemon-mode ingestion effectively, ensure the following:
- Configure polling intervals to balance between frequency and system load.
- Verify connectivity between GUAC and the data source to avoid ingestion delays.