Architecture¶

How bomify works internally, for anyone changing it. For using the CLI, see the README and docs/reference.

Mental model¶

bomify mirrors Docker: a package is built from a CycloneDX SBOM the way an image is built from a Dockerfile, a tag names one, and packages/tag/package rm/save/load map onto images/tag/rmi/save/load. Docker's layers are bomify's components, each pulled, cached, and reused independently by content hash.

bomify only orchestrates. Fetching, publishing, scanning, and signing are done by external bomify-plugin-<kind> binaries.

Contents¶

• Data directory: the on-disk layout and how everything in it is keyed.
• Plugins: the four plugin contracts, component dispatch, SBOM generation, and concurrent pulls.
• Security scanning: scans, gating, VEX, scanning on pull, and reports and VEX in a registry.
• Signing and verification.
• Trust model: what verification, scan gates, and published VEX guarantee, and what they don't.
• Build provenance: SLSA provenance, recorded by build and attached as an in-toto attestation.
• Plugin installation, and how releases publish and sign the first-party plugins.
• Builds and tagging, and pruning.
• Push and pull: how packages are pushed and pulled, save/load, and credentials.
• Registry format: every media type and annotation bomify writes to a registry, and how they're versioned.

Diagrams are rendered from the Mermaid sources in docs/diagrams; after editing a .mmd, run make diagrams.

Design principles¶

• Content-addressing everywhere. Paths are keyed by SBOM hash, purl hash, or digest, so the path is the cache key. That makes builds, pulls, and pushes idempotent and safe to run concurrently without a lock file or database.
• Atomic writes. A final path appears only once its content is complete and verified, so a missing path always means "not done yet".
• bomify orchestrates, plugins do the work. The core has no ecosystem-specific code. Each plugin contract is kept minimal. bomify owns everything around it: dispatch, concurrency, caching, reports, referrers, and trust policy.