How do you generate an SBOM for a Ruby project?

To generate an SBOM for a Ruby project, install the cyclonedx-ruby gem, run it against the project directory, and keep the resulting bom file with each build. It reads your resolved dependencies and writes a CycloneDX document in XML or JSON. Then verify the output against Gemfile.lock and scan it.

What goes into a Ruby SBOM?

An SBOM is a machine-readable inventory of the components in a piece of software. For Ruby the main source of truth is Gemfile.lock, which records exact gem versions that Bundler resolved, including transitive ones. Gemfile alone is not enough, because it holds constraints rather than resolved versions.

CycloneDX is an OWASP-run specification. It records component names, versions, package URLs and relationships, and can carry licenses and hashes.

How do you run the tool?

The cyclonedx-ruby gem README describes installation with gem install cyclonedx-ruby and a command-line tool with these options: -p for the project path, -o for the output path, -f for format (xml by default, json supported), and -s for the CycloneDX spec version. The README lists support for versions 1.1 through 1.7 and a default of 1.7 at the time of writing.

cyclonedx-ruby -p . -f json -o bom.json

The result is a bom.xml or bom.json file. Pick JSON if your downstream tooling prefers it, and set the spec version to whatever your consumers accept. Check the README for current options, since flags and defaults change between releases.

How do you check that the SBOM is right?

Do not trust a generated file blindly. A constructed check for a Rails app:

1. Run bundle list and count the gems.
2. Count the components in bom.json.
3. Spot check five gems, including one transitive and one from a Git source, for matching versions.
4. Confirm gems from a private source are present with the source recorded where the tool allows.

If counts differ, find out why. Common causes: running the tool from the wrong directory, gems in a group excluded from the lockfile view, a missing lockfile because it was not committed, or platform specific gems listed once per platform.

What does the SBOM leave out?

A Ruby SBOM from the lockfile covers gems. It does not describe the Ruby interpreter version, system libraries linked by native extensions, the base container image, JavaScript packages managed by npm or yarn in a Rails app, or vendored code. For a complete picture, generate a second SBOM from the container image, or use a tool that merges ecosystems, and record the Ruby version in the build metadata.

Where should the SBOM live?

Generate it in CI on every release build, from the same lockfile that produced the artifact. Store it next to the artifact, with the commit hash and build ID in its name. An SBOM generated a week later from a changed lockfile describes a different build.

What do you do with it?

Feed it to a vulnerability scanner, compare the gems to advisory data, and keep it so that when a new advisory lands you can search your archive and answer "which releases contain this gem version?" in minutes instead of days.

NIST's secure software development framework covers maintaining provenance data for your components, which makes inventory a routine output of the build.

What to do

1. Commit Gemfile.lock for applications.
2. Install cyclonedx-ruby in CI and run it after bundle install.
3. Write JSON at a spec version your consumers support.
4. Compare component counts with the lockfile and fix gaps.
5. Add a second SBOM for the container image and other ecosystems.
6. Archive the SBOM with the artifact and commit hash.
7. Scan each SBOM for advisories and gate on agreed severity.

Safeguard's CLI generates SBOMs across many package managers and scans them, and reachability analysis helps show which flagged gems your code can reach.

Quick check

Sources

• CycloneDX Ruby Gem README
• CycloneDX specification overview
• NIST SP 800-218: Secure Software Development Framework

Last reviewed: 18 October 2026.