bundle-audit-ruby

Overview

bundler-audit (github.com/rubysec/bundler-audit (opens in new window)) is a standalone Ruby gem that scans Gemfile.lock against the ruby-advisory-db (opens in new window): a community-maintained YAML corpus of CVE, GHSA, and OSVDB advisories for RubyGems and Ruby runtimes.

Differentiation vs. npm-pip-maven-audit: that skill treats bundle audit (the Bundler subcommand) as one line in a multi-ecosystem dispatcher; this skill covers the full bundler-audit workflow: advisory-db lifecycle, per-project suppression with justification, Rake task integration, and JSON output for downstream tooling.

When to use

• Ruby project has a Gemfile.lock and needs CVE/GHSA scanning.
• CI pipeline needs a fast, offline-capable SCA gate with no commercial license overhead.
• Team needs per-project advisory suppression with auditable justification in source control.
• Layering SCA: run bundler-audit for the Ruby-specific feed, pair with osv-scanner for OSV.dev cross-DB consensus.

Install

Per github.com/rubysec/bundler-audit (opens in new window):

gem install bundler-audit

No system-level dependencies beyond a Ruby environment. After install, run a one-time database fetch:

bundle-audit update

Per ruby-advisory-db (opens in new window), the corpus is a git repository of YAML files under gems/ (per-RubyGem advisories) and rubies/ (Ruby runtime advisories). bundle-audit update syncs the local clone of this repo. Subsequent bundle-audit check --no-update runs are fully offline.

Scan

Per github.com/rubysec/bundler-audit (opens in new window):

bundle-audit check --update

The --update flag refreshes the local ruby-advisory-db before scanning, ensuring the check sees the latest advisories. Where outbound git is restricted, pre-update in a build step and scan offline with bundle-audit check --no-update.

bundler-audit scans Gemfile.lock in the current directory and checks two classes of issues (github.com/rubysec/bundler-audit (opens in new window)):

1. Vulnerable gem versions - gem + version matched against ruby-advisory-db advisories with patched-version ranges.
2. Insecure sources - http:// and git:// source URIs that transmit without TLS.

Output flags (github.com/rubysec/bundler-audit (opens in new window)):

JSON + file example, useful as a CI artifact:

bundle-audit check --update --format json --output bundle-audit.json

Suppress false positives

Per github.com/rubysec/bundler-audit (opens in new window), create .bundler-audit.yml at the project root and list advisory IDs to ignore:

---
ignore:
  - CVE-2024-1234
  - GHSA-xxxx-yyyy-zzzz

The ignore array takes CVE, GHSA, or OSVDB identifiers, committed to source control so suppressions are auditable in git history. Every ignore needs an inline justification comment (reachability finding, approver, re-review date); undocumented ignores are a code-smell reviewers should treat as unapproved. The mandatory justification template, per-run --ignore flags, and the quarterly re-review cadence are in references/bundle-audit-ci.md.

Worked example

A Rails service locks nokogiri 1.13.0 and rack 2.2.3. The scan (bundle-audit check --update, per Scan above) flags two advisories and exits non-zero:

Name: nokogiri
Version: 1.13.0
CVE: CVE-2022-24836
Criticality: High
Title: Nokogiri ReDoS on crafted input
Solution: upgrade to >= 1.13.4

Name: rack
Version: 2.2.3
CVE: CVE-2022-30122
Criticality: Medium
Title: Denial of Service in Rack multipart parsing
Solution: upgrade to >= 2.2.3.1

Vulnerabilities found!

Because the exit code is non-zero, a CI job running this step fails. Triage the two findings:

1. nokogiri is reachable (it parses user-supplied XML). Patch it - bundle update nokogiri to 1.13.4 - and the advisory clears.
2. rack multipart parsing is confirmed unreachable (the app rejects multipart requests at the edge). Suppress CVE-2022-30122 in .bundler-audit.yml using the justification template from Suppress false positives above.

Re-run offline (bundle-audit check --no-update): both findings resolved, exit 0, CI passes. Wire the gate into the pipeline per references/bundle-audit-ci.md.

Anti-patterns

Limitations

• Scans Gemfile.lock only; gems loaded outside Bundler (standalone require) are not visible to bundler-audit.
• No reachability analysis: every advisory on a locked gem counts even if the vulnerable code path is not exercised.
• ruby-advisory-db coverage is community-maintained (ruby-advisory-db (opens in new window)); advisories without a community submission are absent until filed.
• --ignore has no built-in expiry mechanism; teams must enforce review cadence in process, not in tooling.

References

• github.com/rubysec/bundler-audit (opens in new window) - installation, CLI flags, config, Rake integration, exit codes
• github.com/rubysec/ruby-advisory-db (opens in new window) - advisory corpus structure (gems/ + rubies/ YAML files), CVE/GHSA/OSVDB coverage
• CI wiring (Rake + GitHub Actions), exit-code gating, and the full .bundler-audit.yml waiver template: references/bundle-audit-ci.md
• npm-pip-maven-audit - multi-ecosystem native audit dispatcher; covers bundle audit as one ecosystem among many
• osv-scanner - OSV.dev cross-DB scanner; pairs for cross-ecosystem consensus
• snyk-test - commercial SCA with Snyk DB