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.

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 Without Installation
    • Running as Nix Flake
    • Running as Python Script
  • Installation
• 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. nixgraph requires graphviz.

Running Without Installation

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 as Python Script

Running sbomnix as Python script requires Python packages specified in requirements.txt. You can install the required packages with:

$ git clone https://github.com/tiiuae/sbomnix
$ cd sbomnix
$ pip install --user -r requirements.txt

After requirements have been installed, you can run sbomnix without installation as follows:

$ source scripts/env.sh
$ python3 sbomnix/main.py
usage: main.py [-h] [--version] [--verbose VERBOSE] [--meta [META]] [--type {runtime,buildtime,both}] [--csv [CSV]] [--cdx [CDX]] NIX_PATH

Installation

Examples in this README.md assume you have installed sbomnix on your system and that command sbomnix is in $PATH. To install sbomnix from source, run:

$ git clone https://github.com/tiiuae/sbomnix
$ cd sbomnix
$ nix-env -f default.nix --install
# To uninstall:  nix-env --uninstall '.*sbomnix.*'

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 something like:

$ 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:

$ 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 include buildtime dependencies using the --type argument. Acceptable values for --type are runtime, buildtime, both. Below example generates SBOM including buildtime-only dependencies:

$ 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.