sbomnix

sbomnix is a utility that generates SBOMs given Nix derivations or out paths.

In addition to sbomnix this repository is home to nixgraph - a Python library and command line utility for querying and visualizing dependency graphs for Nix Packages.

For a demonstration of how to use sbomnix generated SBOM in automating vulnerability scans, see: vulnxscan.

For an example of how to use the tooling provided in this repository to automate vulnerability scanning for a nix flake project, see: ghafscan.

The CycloneDX and SPDX SBOMs for each release of sbomnix itself are available in the release assets.

sbomnix and other tools in this repository originate from Ghaf Framework.

Table of Contents

• Getting Started
  • Running as Nix Flake
  • Running from Nix Development Shell
• Usage Examples
  • Generate SBOM Based on Derivation File or Out-path
  • Generate SBOM Including Meta Information
  • Generate SBOM Including Buildtime Dependencies
  • Generate SBOM Based on Result Symlink
  • Visualize Package Dependencies
• Contribute
• License
• Acknowledgements

Getting Started

sbomnix requires common Nix tools like nix and nix-store. These tools are expected to be in $PATH.

Running as Nix Flake

sbomnix can be run as a Nix flake from the tiiuae/sbomnix repository:

# '--' signifies the end of argument list for `nix`.
# '--help' is the first argument to `sbomnix`
$ nix run github:tiiuae/sbomnix#sbomnix -- --help

or from a local repository:

$ git clone https://github.com/tiiuae/sbomnix
$ cd sbomnix
$ nix run .#sbomnix -- --help

Similarly, you can run nixgraph with nix run github:tiiuae/sbomnix#nixgraph -- --help

See the full list of supported flake targets by running nix flake show.

Running from Nix Development Shell

If you have nix flakes enabled, start a development shell:

$ git clone https://github.com/tiiuae/sbomnix
$ cd sbomnix
$ nix develop

You can also use nix-shell to enter the development shell:

$ git clone https://github.com/tiiuae/sbomnix
$ cd sbomnix
$ nix-shell

From the development shell, run sbomnix as follows:

$ sbomnix --help

Usage Examples

In the below examples, we use Nix package wget as an example target. To print wget out-path on your local system, try:

$ nix eval -f '<nixpkgs>' 'wget.outPath'
"/nix/store/8nbv1drmvh588pwiwsxa47iprzlgwx6j-wget-1.21.3"

Generate SBOM Based on Derivation File or Out-path

By default sbomnix scans the given target and generates an SBOM including the runtime dependencies. Notice that determining the target runtime dependencies requires realising (building) the target. This stems from the way Nix determines potential runtime dependencies:

$ sbomnix /nix/store/8nbv1drmvh588pwiwsxa47iprzlgwx6j-wget-1.21.3
...
INFO     Wrote: sbom.cdx.json
INFO     Wrote: sbom.spdx.json
INFO     Wrote: sbom.csv

Main outputs are the SBOM json files sbom.cdx.json and sbom.spdx.json in CycloneDX and SPDX formats.

Generate SBOM Including Meta Information

To include license information to the SBOM, first generate package meta information with nix-env:

$ nix-env -qa --meta --json '.*' >meta.json

Then, run sbomnix with --meta argument to tell sbomnix to read meta information from the given json file:

$ sbomnix /nix/store/8nbv1drmvh588pwiwsxa47iprzlgwx6j-wget-1.21.3 --meta meta.json

Generate SBOM Including Buildtime Dependencies

By default sbomnix scans the given target for runtime dependencies. You can tell sbomnix to determine the buildtime dependencies using the --type argument. Acceptable values for --type are runtime, buildtime, both. Below example generates SBOM including buildtime dependencies. Notice that determining buildtime dependencies does not require realising (building) the target.

$ sbomnix /nix/store/8nbv1drmvh588pwiwsxa47iprzlgwx6j-wget-1.21.3 --meta meta.json --type=buildtime

Generate SBOM Based on Result Symlink

sbomnix can be used with output paths too (e.g. anything which produces a result symlink):

$ sbomnix /path/to/result 

Visualize Package Dependencies

sbomnix finds the package dependencies using nixgraph. Moreover, nixgraph can also be used as a stand-alone tool for visualizing package dependencies. Below, we show an example of visualizing package wget runtime dependencies:

$ nixgraph /nix/store/8nbv1drmvh588pwiwsxa47iprzlgwx6j-wget-1.21.3 --depth=2

Which outputs the dependency graph as an image (with maxdepth 2):

For more examples on querying and visualizing the package dependencies, see: nixgraph.

Contribute

Any pull requests, suggestions, and error reports are welcome. To start development, we recommend using Nix flakes development shell:

$ git clone https://github.com/tiiuae/sbomnix
$ cd sbomnix/
# Optionally, install git hooks to check the git commit message
$ ./githooks/install-git-hooks.sh
$ nix develop

Run make help to see the list of supported make targets. Prior to sending any pull requests, make sure at least the make pre-push runs without failures.

To deactivate the Nix devshell, run exit in your shell. To see other Nix flake targets, run nix flake show.

License

This project is licensed under the Apache-2.0 license - see the Apache-2.0.txt file for details.

Acknowledgements

sbomnix uses Nix store derivation scanner (nix.py and derivation.py) originally from vulnix.