SBOM Generation

Cyberus requires the Software Bill of Materials (SBOM) of your CtrlOS configuration to know which packages you depend on, i.e., which packages we have to maintain. This document explains how to generate an SBOM in the correct format.

Your CtrlOS System Configuration

We assume that you have a flake.nix file that defines the CtrlOS configuration for your embedded device. A minimal example looks as follows.

{
  description = "Minimal CtrlOS system configuration";
  inputs = {
    nixpkgs.url = "https://channels.ctrl-os.com/channel/ctrlos-24.05.tar.xz";
  };
  outputs = {
    self,
    nixpkgs,
    ...
  }: let
    system = "x86_64-linux";
    pkgs = (import nixpkgs) { inherit system; };
  in {
    nixosConfigurations = {
      "ctrlos-device" = nixpkgs.lib.nixosSystem {
        modules = [
          ./configuration.nix
        ];
      };
    };
  };
}

Adding a Command for SBOM-Generation

Add the sbomnix flake input and the buildSbomnix app to your configuration:

{
  description = "Minimal CtrlOS system configuration with SBOM-generation command";
  inputs = {
    nixpkgs.url = "https://channels.ctrl-os.com/channel/ctrlos-24.05.tar.xz";
    sbomnix.url = "github:tiiuae/sbomnix"; # flake input for sbomnix
  };
  outputs = {
    self,
    nixpkgs,
    sbomnix, # make sbomnix available to the outputs
    ...
  }: let
    system = "x86_64-linux";
    pkgs = (import nixpkgs) { inherit system; };
  in {
    nixosConfigurations = {
      "ctrlos-device" = nixpkgs.lib.nixosSystem {
        modules = [
          ./configuration.nix
        ];
      };
    };
    # add app that generates the SBOM
    apps.${system}.buildSbomnix = {
      type = "app";
      program = "${pkgs.writeShellScript "buildSbomnix"
        ''
          ${sbomnix.packages.${system}.sbomnix}/bin/sbomnix ${self.nixosConfigurations.ctrlos-device.config.system.build.toplevel.outPath}
        ''
      }";
    };
  };
}

Generating the SBOM Manually

You can now run the newly defined app to generate SBOM files.

$ nix run .#buildSbomnix

sbomnix creates the files sbom.cdx.json, sbom.spdx.json, and sbom.csv in the current directory. CDX and SPDX are two different SBOM formats. Please provide us with your sbom.cdx.json file.

Automatically Generating SBOMs with GitLab CI

If you use GitLab to manage your CtrlOS configuration, you can utilize GitLab CI to automatically generate the SBOM. Use the following stage definition as a template.

build:sbom:
  stage: build
  interruptible: true
  tags:
    - nix
  script:
    - |
      unset NIX_PATH
      nix run .#buildSbomnix
  artifacts:
    expire_in: 1 week
    paths:
      - sbom.cdx.json