README
¶
extract-sbom
extract-sbom performs standardized incoming inspection for software deliveries. Given one input file, it produces:
- one consolidated SBOM (CycloneDX JSON, CycloneDX XML, or SPDX JSON)
- one audit report (Markdown, HTML, JSON, SARIF, or any combination)
It recursively processes nested containers and archive formats, applies safety
limits, records extraction/scanning decisions, and keeps traceability via
extract-sbom:delivery-path metadata.
The concrete scan strategy, including determinism and trust boundaries, is explained in SCAN_APPROACH.md.
Why This Project Exists
Software procurement teams regularly receive deliveries from external vendors — ZIP archives, MSI installers, setup executables — and must verify that these deliveries are free of known vulnerabilities (CVEs) before they are accepted and deployed. This is the software equivalent of an incoming goods inspection: in supply-chain-critical environments, nothing is deployed without being checked first. The relevant risk is not just in the top-level package, but throughout the entire software supply chain — transitive dependencies, bundled libraries, and components buried inside nested installer formats.
Existing SBOM tools cover the development and build side of the supply chain well, but none address the inspection of an already-packaged, opaque vendor delivery:
-
Syft generates SBOMs from container images, source directories, and simple archive formats. It does not recursively unpack deeply nested archives or installer formats (MSI, CAB, InstallShield), produces no auditable report, and provides no sandboxing for untrusted inputs. extract-sbom uses Syft internally as a component cataloging engine, but Syft alone cannot handle the delivery inspection workflow.
-
cyclonedx-cli is a BOM manipulation tool for converting, merging, diffing, validating, and signing existing SBOM documents. It has no ability to generate an SBOM from a software artifact and no extraction capability.
-
microsoft/sbom-tool generates SPDX SBOMs from a build drop path or source tree. It is designed for software producers to describe their own products during CI/CD — not for consumers performing incoming inspection of an opaque binary or installer received from an external vendor.
-
jimmykarily/sbom-extractor pulls an SBOM that was previously attached to a container image as an OCI attestation. It operates exclusively on container registry images and cannot inspect a locally received file. It also relies entirely on the vendor having already attached an SBOM to the image — no independent verification is possible.
extract-sbom fills the gap by treating the vendor delivery file as the unit of inspection: one file in, one consolidated CycloneDX SBOM and one auditable report out.
Feature Comparison
| Feature | extract-sbom | Syft | cyclonedx-cli | microsoft/sbom-tool | jimmykarily/sbom-extractor |
|---|---|---|---|---|---|
| Designed for incoming delivery inspection | ✓ | ✗ | ✗ | ✗ | ✗ |
| Recursive nested archive extraction | ✓ | ✗ | ✗ | ✗ | ✗ |
| MSI / CAB / InstallShield / ISO / CPIO / Squashfs support | ✓ | ✗ | ✗ | ✗ | ✗ |
| Single delivery file in → consolidated SBOM out | ✓ | ✗ | ✗ | ✗ | ✗ |
| Auditable extraction report (Markdown / HTML / JSON / SARIF) | ✓ | ✗ | ✗ | ✗ | ✗ |
| Delivery-path traceability in SBOM metadata | ✓ | ✗ | ✗ | ✗ | ✗ |
| Sandboxed execution for untrusted vendor input | ✓ | ✗ | ✗ | ✗ | ✗ |
| Policy-controlled extraction (depth / size limits) | ✓ | ✗ | ✗ | ✗ | ✗ |
| Deterministic / reproducible output | ✓ | ✗ | ✗ | ✗ | ✗ |
| Component cataloging across packaging ecosystems | ✓ (via Syft) | ✓ | ✗ | ✓ | ✗ |
| CycloneDX output (JSON + XML) | ✓ | ✓ | ✓ | ✗ | ~ |
| SPDX 2.3 JSON output | ✓ | ✓ | ✓ | ✓ | ✗ |
| SARIF output for CI security gates | ✓ | ✗ | ✗ | ✗ | ✗ |
| Independent of container registry / OCI | ✓ | ✓ | ✓ | ✓ | ✗ |
| SBOM manipulation (merge, diff, validate, sign) | ✗ | ✗ | ✓ | ✗ | ✗ |
Note: cyclonedx-cli and Syft are complementary tools that integrate naturally with extract-sbom: Syft is used by extract-sbom as a cataloging engine, and cyclonedx-cli can be used to further process or validate the SBOM output. The table reflects suitability for the incoming delivery inspection workflow, not general-purpose capability.
What It Does
- Identifies archive/container formats (ZIP, TAR variants, CAB, MSI, 7z, RAR, InstallShield CAB, ISO, CPIO, Squashfs/Snap, AppImage)
- Extracts recursively with policy and resource limits
- Detects encrypted ZIP entries and automatically re-routes those archives to 7-Zip
- Tries configured passwords in order for password-protected formats handled by external extractors
- Uses Syft in library mode for component cataloging
- Assembles one deterministic SBOM in CycloneDX 1.6 JSON (
--format cyclonedx-json), CycloneDX XML (--format cyclonedx-xml), or SPDX 2.3 JSON (--format spdx-json) - Generates an auditable report in Markdown (
--report markdown), standalone HTML (--report html), structured JSON (--report json), SARIF 2.1.0 (--report sarif), or Markdown + JSON + HTML together (--report all) — in English or German
Encrypted Archives and Password Sources
For encrypted archives, extract-sbom supports ordered password attempts from:
--password(repeatable)EXTRACT_SBOM_PASSWORDS(comma-separated)--password-file(one password per line,#comments allowed)
Password attempts are ordered by source precedence:
- command-line flags (
--password) - environment variable (
EXTRACT_SBOM_PASSWORDS) - password file (
--password-file)
Within extraction, extract-sbom first tries without a password, then each configured password in order. Secrets are never printed in logs or reports.
Optional Vulnerability Enrichment (--grype)
If --grype is enabled, extract-sbom runs Grype against the generated SBOM and
enriches the audit report without changing SBOM structure or extraction/scan decisions.
- Summary view: grype-inspired vulnerability table with
Name, installed/fixed versions, vulnerability ID, severity (including CVSS score when available), EPSS, risk, and KEV. - Detail view: package-grouped occurrence index with per-occurrence vulnerability status
(
found,none,not-assessable), including type, fix data, CVSS version/score/vector, description, EPSS, and source references when available. - Runtime diagnostics: Grype version/database metadata and explicit enrichment state
(
completed,completed-with-errors,unavailable,not-requested). - Failure behavior: if Grype is missing or returns invalid/unusable output, SBOM and report are still generated; the report records enrichment as unavailable/incomplete.
Quick Start
Install a prebuilt release binary (see INSTALL.md) or build from source (see BUILD.md).
Run (sandboxed mode on Linux with bwrap):
mkdir -p out
extract-sbom \
--output-dir out \
sample-delivery.zip
Run (unsandboxed, e.g., macOS or trusted CI):
mkdir -p out
extract-sbom \
--unsafe \
--output-dir out \
sample-delivery.zip
Typical outputs in out/ (base name derived from input file):
sample-delivery.cdx.json(default; use--format cyclonedx-xmlfor.cdx.xml,--format spdx-jsonfor.spdx.json)sample-delivery.report.md(default; use--report jsonfor.report.json,--report htmlfor.report.html,--report sariffor.sarif.json,--report allfor Markdown + JSON + HTML)
Documentation
- INSTALL.md: installation and dependency troubleshooting
- BUILD.md: building from source and release tooling
- USAGE.md: scenario-based usage, parameters, and outputs
- SCAN_APPROACH.md: operator-focused explanation of how scanning works and why the result is trustworthy
- DESIGN.md: functional and security design
- MODULE_GUIDE.md: module architecture and decisions
- RELEASE_NOTES.md: notable changes in this release
Project Status in CI
Core CI currently checks build, test, race, coverage, lint, plus dedicated workflows for fuzz testing and release candidate verification.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
extract-sbom
command
Package main provides the CLI entry point for extract-sbom.
|
Package main provides the CLI entry point for extract-sbom. |
|
internal
|
|
|
assembly
Package assembly merges per-node CycloneDX BOMs into one consolidated SBOM.
|
Package assembly merges per-node CycloneDX BOMs into one consolidated SBOM. |
|
buildinfo
Package buildinfo provides build and VCS metadata for extract-sbom.
|
Package buildinfo provides build and VCS metadata for extract-sbom. |
|
config
Package config provides the central configuration types and defaults for extract-sbom.
|
Package config provides the central configuration types and defaults for extract-sbom. |
|
extract
Package extract implements recursive, auditable extraction of archive formats.
|
Package extract implements recursive, auditable extraction of archive formats. |
|
identify
Package identify detects the format of a file and determines whether Syft can handle it natively or whether extract-sbom needs to extract it.
|
Package identify detects the format of a file and determines whether Syft can handle it natively or whether extract-sbom needs to extract it. |
|
orchestrator
Package orchestrator coordinates the end-to-end processing pipeline of extract-sbom.
|
Package orchestrator coordinates the end-to-end processing pipeline of extract-sbom. |
|
policy
Package policy evaluates limit violations and determines processing behavior based on the configured policy mode.
|
Package policy evaluates limit violations and determines processing behavior based on the configured policy mode. |
|
report
Package report generates audit reports from the processing state.
|
Package report generates audit reports from the processing state. |
|
report/internal/domain
Package domain holds report-domain aggregation logic shared by renderers.
|
Package domain holds report-domain aggregation logic shared by renderers. |
|
report/internal/html
Package html implements the self-contained HTML report renderer.
|
Package html implements the self-contained HTML report renderer. |
|
report/internal/i18n
Package i18n holds the localized label and prose catalog shared by the report renderers, together with a small inline-Markdown-to-HTML converter so the HTML renderer can reuse the Markdown-flavored catalog strings.
|
Package i18n holds the localized label and prose catalog shared by the report renderers, together with a small inline-Markdown-to-HTML converter so the HTML renderer can reuse the Markdown-flavored catalog strings. |
|
report/internal/json
Package json implements the structured JSON audit report renderer.
|
Package json implements the structured JSON audit report renderer. |
|
report/internal/markdown
Package markdown implements the active Markdown-based markdown report renderer.
|
Package markdown implements the active Markdown-based markdown report renderer. |
|
report/internal/model
Package model defines the shared report contracts used across report outputs and the root report facade.
|
Package model defines the shared report contracts used across report outputs and the root report facade. |
|
report/internal/sarif
Package sarif implements the SARIF 2.1.0 audit report renderer.
|
Package sarif implements the SARIF 2.1.0 audit report renderer. |
|
safeguard
Package safeguard provides extraction safety checks for extract-sbom.
|
Package safeguard provides extraction safety checks for extract-sbom. |
|
sandbox
Package sandbox provides isolation wrappers for executing external binaries (7-Zip, unshield) during archive extraction.
|
Package sandbox provides isolation wrappers for executing external binaries (7-Zip, unshield) during archive extraction. |
|
scan
Package scan invokes Syft in library mode to catalog software components.
|
Package scan invokes Syft in library mode to catalog software components. |
|
vulnscan
Package vulnscan performs optional vulnerability enrichment by invoking Grype on the generated SBOM and correlating matches to component BOM refs.
|
Package vulnscan performs optional vulnerability enrichment by invoking Grype on the generated SBOM and correlating matches to component BOM refs. |