Software Bill of Materials

Copy Markdown View Source

A Software Bill of Materials (SBoM) is a structured inventory of the components that make up a software system. This guide explains what SBoMs are, why they matter, and how to generate them for Elixir projects.

What is an SBoM?

An SBoM is a formal, machine-readable record of all components in a piece of software. Think of it as a detailed ingredient list for your application. A typical SBoM includes:

  • Dependencies: all libraries and packages your project uses
  • Versions: the exact version of each component
  • Source locations: where each component was obtained (Hex, GitHub, etc.)
  • Checksums: cryptographic hashes to verify integrity
  • Licensing information: the license under which each component is distributed

Two widely adopted standards exist for SBoM formats:

  • CycloneDX: a lightweight standard designed for security contexts
  • SPDX: a more comprehensive standard originally focused on licensing

Both formats are machine-readable (JSON, XML) and designed to be consumed by automated tooling.

SBoM is an inventory, not a certification

An SBoM does not claim that software is secure, compliant, or free of vulnerabilities. It simply provides a detailed inventory that enables further analysis. Security and compliance assessments are performed by separate tools that consume the SBoM.

Why generate SBoMs?

There are three main reasons to generate SBoMs for your projects.

Vulnerability analysis

When a security vulnerability (CVE) is discovered in a library, you need to quickly determine if your projects are affected. SBoMs make this possible by providing a complete inventory of your dependencies.

Tools like OWASP Dependency-Track continuously monitor your SBoMs against vulnerability databases. When a new CVE is published, you get notified if any of your projects use the affected component.

Without an SBoM, answering "are we affected by CVE-2024-XXXXX?" means manually checking each project, which is time-consuming and error-prone.

Regulatory requirements

SBoMs are required by some regulations and procurement policies:

  • US Executive Order 14028 (2021) requires SBoMs for certain software supplied to the U.S. federal government, particularly for designated critical software
  • EU Cyber Resilience Act introduces requirements for component inventories (commonly fulfilled using SBoMs) for products with digital elements placed on the EU market
  • Safety-critical industries (medical devices, automotive, aerospace) often require detailed component inventories as part of certification

Customers and partners may also request SBoMs as part of their own compliance efforts.

License compliance

Every dependency in your project comes with a license. An SBoM provides a starting point for license review by listing the declared license for each package. This helps you:

  • Get an overview of licenses in your dependency tree
  • Flag packages that may need closer review
  • Support due diligence for acquisitions, audits, or legal review

Note that package-level license information (as provided by mix_sbom) reflects what the package declares, not necessarily all licenses present in its source files. For thorough license compliance, file-level scanning tools like ORT provide deeper analysis.

Generating SBoMs with mix_sbom

mix_sbom is an EEF project that generates CycloneDX SBoMs for Elixir projects.

Installation

There are several ways to install mix_sbom:

  • As a project dependency: add sbom to your mix.exs
  • As a global escript: run mix escript.install hex sbom (requires Elixir 1.19.4+)
  • As a standalone binary: download from the releases page

The standalone binary is useful for CI environments or when you don't want to modify your project's dependencies. It requires no local Elixir or Erlang installation.

Basic usage

To generate an SBoM for your project using the standalone binary:

$ mix_sbom cyclonedx /path/to/your/project

This creates a bom.cdx.json file in CycloneDX format containing your project's complete dependency tree.

Common options

The most useful options are:

  • -o, --output PATH: specify the output file (default: bom.cdx.json)
  • -t, --format FORMAT: output format (json, xml, or protobuf)
  • -s, --schema VERSION: CycloneDX schema version

For example, to generate an XML format SBoM:

$ mix_sbom cyclonedx --format xml --output sbom.xml /path/to/project

CI integration

For automated SBoM generation, mix_sbom provides a GitHub Action:

name: Generate SBoM
on:
  release:
    types: [published]

jobs:
  sbom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: erlef/mix_sbom@v0
        with:
          path: "."
          format: "json"
      - uses: actions/upload-artifact@v4
        with:
          name: sbom
          path: bom.cdx.json

This workflow generates an SBoM whenever you publish a release and uploads it as a build artifact. See the action's documentation for additional options.

Deeper analysis with ORT

mix_sbom provides package-level license information based on what each dependency declares. However, some compliance workflows require file-level scanning. A package might declare an MIT license but contain individual files under different licenses, or include vendored code with its own licensing terms.

The OSS Review Toolkit (ORT) addresses this by scanning actual source files for license headers and copyright notices. ORT supports Mix projects and provides:

  • File-level license detection: scans source code for license texts and SPDX identifiers
  • Copyright holder identification: extracts copyright notices from files
  • Policy enforcement: define rules for allowed and denied licenses
  • Multi-ecosystem support: analyze projects that span multiple package managers

For organizations with strict compliance requirements, ORT complements mix_sbom by providing the deeper analysis needed for thorough license audits.

See the ORT Mix plugin documentation for details.

Next steps