Software Bill of Materials (SBOM)
=================================

This project produces machine-readable Software Bills of Materials following
industry standards and the
`2025 CISA minimum elements guidance <https://www.cisa.gov/sbom>`_.

Generating SBOMs
----------------

.. code-block:: sh

   make sbom

This runs four steps:

1. **Source SBOM (CycloneDX 1.6)** — scans the source tree for dependencies,
   vendored code, and build metadata.

2. **Source SBOM (SPDX)** — same scan, alternate format for license compliance
   workflows.

3. **Binary SBOM (CycloneDX)** — scans the compiled release build for linked
   libraries and embedded dependencies.

4. **Vulnerability scan** — checks all discovered components against known
   vulnerability databases (NVD, GitHub Advisories, etc.).

Output files land in ``sbom/``:

- ``sbom.cdx.json`` — CycloneDX 1.6 (primary format)
- ``sbom.spdx.json`` — SPDX
- ``sbom-binary.cdx.json`` — binary analysis
- ``vulnerabilities.json`` — Grype scan results

Tools
-----

`Syft <https://github.com/anchore/syft>`_
   Open-source SBOM generator from Anchore.  Scans source directories,
   container images, and archives.  Detects pkg-config files, lock files,
   and binary metadata.  Outputs CycloneDX and SPDX formats.

`Grype <https://github.com/anchore/grype>`_
   Vulnerability scanner that reads SBOMs and matches components against
   CVE databases.  Exits non-zero when vulnerabilities above a configured
   severity are found.

Both are included in the project's Nix dev shell (``nix develop``).

Nix-Native SBOM Generation
---------------------------

For projects distributed as Nix packages, Syft alone may not capture the
full Nix closure (all transitive build-time and runtime dependencies from
nixpkgs).  Two Nix-specific tools address this:

`sbomnix <https://github.com/tiiuae/sbomnix>`_
   Scans a Nix store path and generates CycloneDX + SPDX SBOMs covering
   the entire runtime closure.  Also supports ``--buildtime`` for build
   dependency enumeration without requiring a build::

      nix run github:tiiuae/sbomnix#sbomnix -- /nix/store/<hash>-gettext-header

`bombon <https://github.com/nikstur/bombon>`_
   Nix library and CLI that generates CycloneDX v1.5 SBOMs directly from
   Nix derivations.  Integrates as a flake input::

      bombon.lib.${system}.buildBom pkgs.gettext-header { }

   Designed for compliance with German BSI TR-03183 v2.0.0 and
   US Executive Order 14028.

SBOM Contents
-------------

Per CISA 2025 guidance, generated SBOMs include at minimum:

- **Component name** and **version**
- **Supplier/author** information
- **Unique identifier** (package URL / purl)
- **Dependency relationships** (direct and transitive)
- **Cryptographic hash** of each component
- **License** information
- **Generation tool** name and version
- **Timestamp** of generation

Best Practices
--------------

- Regenerate SBOMs before every release.
- Include SBOM files in release artifacts (alongside tarballs/packages).
- Run ``grype`` in CI to fail builds on known vulnerabilities.
- Review ``vulnerabilities.json`` and document accepted risks as VEX
  (Vulnerability Exploitability eXchange) statements if needed.
- For Nix-packaged distributions, generate a closure-level SBOM with
  sbomnix or bombon in addition to the source-level Syft SBOM.