bundler-audit's offline promise rests on a git clone of the advisory database
Patch-level verification for Bundler
At a glance
- What is it?
- A patch-level checker for Gemfile.lock that also flags insecure gem sources. The vulnerability data is a local checkout of YAML advisories, so checking can run offline when that database is already available. An update refreshes it over the network, including when `check --update` is used. Read the per-project config example carefully: it uses CVE-shaped identifiers while every command example uses OSVDB ones.
- Who is it for?
- Adopt bundler-audit if you ship a Ruby application, want a dependency check that runs offline against a database you can refresh on a schedule, and will wire `--format json` into a pipeline. Do not adopt it expecting it to find problems beyond published advisories: it matches Gemfile.lock against advisory records, and a gem with no record on file passes.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- rubysec/bundler-audit2,763 ★ · +2
| Repository | 2026-09-30 | 2026-11-15 |
|---|---|---|
| rubysec/bundler-audit | 2.8k | 2.8k |
2 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The advisory database is a git repository, which is how the offline claim works
One of the five listed features is that bundler-audit does not require a network connection. That is true, and the reason is visible in what `bundle-audit update` prints: a git fetch from https://github.com/rubysec/ruby-advisory-db, a fast-forward from 5f8225e to 328ca86 on branch master, and then a file list of advisory records being added.
The records are one YAML file per gem per advisory. The sample shows `gems/actionmailer/OSVDB-98629.yml`, `gems/cocaine/OSVDB-98835.yml`, `gems/fog-dragonfly/OSVDB-96798.yml` and the beginning of a fourth under `gems/sounder/`, and the output stops partway through that filename.
So the database is a checked out git working tree, and the audit is a comparison between two local files: your `Gemfile.lock` and those YAML records. No network is needed for that comparison, and the offline claim holds.
The consequence is that the database is only as current as the last update, and the page draws that line explicitly with three separate flags: update and refresh for yourself, `check --update` for a CI run that wants fresh data, and `check --no-update` when you must not touch the network.
Three invocations, and only one of them never reaches the network
The documented commands cover more ground than the feature list suggests:
$ bundle-audit check --update
$ bundle-audit check --no-update
$ bundle-audit check --ignore OSVDB-108664
$ bundle-audit check --gemfile-lock Gemfile.custom.lock
$ bundle-audit check --format json
$ bundle-audit check --format json --output bundle-audit.json
$ bundle-audit check --config bundler-audit.custom.yamlFour of those are about selecting what to check. `--gemfile-lock` points at a lock file other than the default, which is how you audit a Gemfile for something other than the current project. `--ignore` suppresses one advisory by ID, and the configuration file does the same thing in bulk. `--format json` and `--output` are the machine-readable pair.
The naming is slightly awkward and worth knowing before you type it. There is a bare `bundle-audit` invocation that audits the project, and a separate two-word `bundle-audit update` that only refreshes the database. Once you add the `check` subcommand the flags attach to it, so the update is expressed as a flag rather than as the subcommand it otherwise appears to be.
Either way, one git operation is available to every invocation, and `--no-update` is the only way to be certain it does not happen.
There is a second kind of finding on the same page that has no advisory behind it. One of the listed features is a check for insecure gem sources, meaning `http://` and `git://` in a lock file rather than a known vulnerability. That check cannot use the seven-field shape from the Synopsis, because there is no advisory ID, no criticality and no fixed version for a source that should have been https in the first place. The sample output shows only the advisory form, so what a source finding looks like is not documented.
One gem version can produce several advisories with one fix
The Synopsis section shows what a finding looks like, and the shape is worth internalising before you wire this into anything:
$ bundle-audit
Name: actionpack
Version: 3.2.10
Advisory: OSVDB-91452
Criticality: Medium
URL: http://www.osvdb.org/show/osvdb/91452
Title: XSS vulnerability in sanitize_css in Action Pack
Solution: update to ~> 2.3.18, ~> 3.1.12, >= 3.2.13Seven fields per advisory: the gem name, the resolved version, the advisory ID, a criticality, a URL, a title and the version ranges that fix it. Nothing is inferred, and the solution line is a set of Bundler requirements you can paste into a Gemfile.
The sample then prints a second advisory for the same gem and the same version, OSVDB-91454, also Medium, also fixed by the same three ranges, with a different title about the `sanitize` helper. Then a third, OSVDB-89026, rated High, whose output stops after `Title: R`.
So one vulnerable version yields several findings, and the number of lines is not the number of problems. Anything counting advisories rather than gems will misreport.
The config file example uses CVE identifiers, every command example uses OSVDB
There is a per-project configuration file, `.bundler-audit.yml`, holding one key:
---
ignore:
- CVE-YYYY-XXXXThe key is documented as an array of strings, a list of advisory IDs to ignore, and `--config` lets you point at a file elsewhere.
Here is the inconsistency. Every other identifier on the page is OSVDB shaped: `OSVDB-91452` in the output, `OSVDB-108664` as the argument to `--ignore`, and the file names in the advisory database itself. The configuration example is the only place a CVE identifier appears, and it is the only place where the format is unspecified enough to be wrong.
Two smaller naming details in the same section. The `--config` example points at `bundler-audit.custom.yaml`, while the default file is `.bundler-audit.yml`, so the two are named differently in the same three lines. And the ignore list is the one place in the tool where you record a decision: every entry is an assertion that a finding does not apply to you, and nothing in the output distinguishes an ignored advisory from an absent one.
Rake tasks and JSON are the two integration surfaces
For a Rails project the intended integration is two lines in the Rakefile:
require 'bundler/audit/task'
Bundler::Audit::Task.newThat registers two tasks, and the page shows what `rake -T` then lists:
$ rake -T
rake bundle:audit
rake bundle:audit:updateSo the check and the database refresh are separate tasks, which is the right shape for a pipeline where the refresh should be cached rather than repeated on every run.
For anything not built on rake, the JSON pair is the route: `--format json` writes to standard output and adding `--output` writes to a named file, with `bundle-audit.json` given as the example. There is no documented schema for that output, no documented exit code behaviour, and no documented way to make a specific advisory fail the build other than not ignoring it.
Combined with `--gemfile-lock`, that gives you three separate controls: which lock file, which database state, and which format the result arrives in.
A human must review every submission, and machine output is closed
The repository has a section on generative AI contributions, and it is stricter than most. A human in the loop is required for all submissions. AI tools are permitted as assistants. Contributors must personally review, understand and take full responsibility for what they submit.
The enforcement is stated too: contributions that appear to be unreviewed machine output are closed immediately, and repeat offenders are banned from the project and reported.
That is a defensible position for this particular project, and the reason is structural rather than ideological. The tool's output is only as good as the advisory records it reads, and those records decide whether a specific version of a gem is reported to a build. A project whose stated purpose is patch-level verification has an obvious incentive to require a person to stand behind every record it adds.
It also has a cost for contributors, and it is worth being clear-eyed about it. The contributing instructions that follow are ten steps ending in `bundle exec rake spec`, with no separate review gate in them. The human-in-the-loop requirement is enforced at review time by a maintainer rather than by any tooling in the repository.
thor is capped at 1.x and ruby is floored at 2.0.0
The requirements list is short: git, ruby 2.0.0 or newer, rubygems 1.8 or newer, thor `~> 1.0`, and bundler 1.2.0 or newer. The thor constraint is the tight one, admitting only the 1.x series, while the ruby floor is Ruby 2.0 from 2013 and the newest release, 0.9.3, dates from 2025-11-28.
Installation is a single line, with sudo shown as optional:
$ [sudo] gem install bundler-auditBecause git is a requirement rather than a convenience, the page gives four platform commands for it: `sudo apt install git` on Debian and Ubuntu, `sudo dnf install git` on RedHat and Fedora, `apk add git` on Alpine, and `brew install git` on macOS. Note that sudo appears on the first two and not the last two.
The rest of the repository explains the shape. `ba-usage.md` holds the command line reference, `gemspec.yml` sits beside a checked-in `bundler-audit.gemspec`, COPYING.txt and ChangeLog.md carry the licence and history, and `.yardopts`, `.document`, `.rspec` and `.rubocop.yml` cover documentation and test tooling.
On licensing, the metadata records GPL-3.0 while the licence text grants version 3 or, at your option, any later version, and the copyright line runs 2013 to 2026 for Hal Brodigan.
Editorial conclusion
Adopt bundler-audit if you ship a Ruby application, want a dependency check that runs offline against a database you can refresh on a schedule, and will wire `--format json` into a pipeline. Do not adopt it expecting it to find problems beyond published advisories: it matches Gemfile.lock against advisory records, and a gem with no record on file passes. Verify first which advisory identifier format your configuration file uses, because the per-project example shows CVE-shaped IDs while every command example uses OSVDB ones, and pin the ruby-advisory-db commit your CI clones if the results need to be reproducible.
Frequently asked questions
Does bundler-audit need an internet connection?
The audit itself does not. The vulnerability data is a local git checkout of the ruby-advisory-db repository, so comparing Gemfile.lock against it is a local operation. `bundle-audit update` and `bundle-audit check --update` do fetch from GitHub, and `check --no-update` is the form that will not.
How do you install bundler-audit?
With `gem install bundler-audit`, optionally under sudo. It requires git, ruby 2.0.0 or newer, rubygems 1.8 or newer, thor `~> 1.0` and bundler 1.2.0 or newer, so git has to be installed separately with the platform command for your distribution.
How do you suppress an advisory in bundler-audit?
For one advisory, pass `--ignore` with its identifier. For several, add them to the `ignore` array in a `.bundler-audit.yml` file at the project root, or point `--config` at a file elsewhere. Nothing in the output distinguishes an ignored advisory from one that does not apply.
Can bundler-audit run as a rake task?
Yes. Add `require 'bundler/audit/task'` and `Bundler::Audit::Task.new` to your Rakefile, which makes `rake bundle:audit` and `rake bundle:audit:update` available. For machine-readable output there is also `--format json`, optionally with `--output`.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/rubysec-bundler-audit)Star history chart for your README
[](https://hysenlabs.com/projects/rubysec-bundler-audit)Was this useful?