Stop name-substitution attacks in Bundler by assigning every internal gem to its own source block, giving every gem in the Gemfile an explicit source, committing a lockfile with checksums, and setting a cooldown so releases newer than a few days are not resolved. Then review any new dependency by hand.
What are the two attacks?
A typosquat is a gem published under a name one keystroke away from a popular one, hoping a developer mistypes bundle add. Dependency confusion is different: your company has an internal gem called, say, acme-billing on a private server, and an attacker publishes a public gem with the same name, counting on the resolver to pick the public copy.
The RubyGems security guide describes the second risk plainly. If you install from more than one source, such as an internal gem server alongside rubygems.org, a public gem published under the same name as an internal one could be substituted for it. It also reminds readers that installing a gem runs someone else's code on your machine with your privileges.
How do source blocks help?
The guide's fix is to assign each internal gem to its server with a source block, so Bundler installs it only from there. It adds an easily missed caveat: a source declared in a block still remains a candidate for gems that have no explicit source. So the rule is every gem gets an explicit source, including the public ones. A Gemfile where only the internal gems are in a block leaves the gap half open.
A constructed layout shows the idea. The default source "https://rubygems.org" line covers public gems placed in their own block, and a second block for the private server lists acme-billing and acme-auth and nothing else. With that layout, a public gem called acme-billing is never considered for the internal name.
What does a lockfile add?
Bundler records the exact version of every dependency in Gemfile.lock. Newly generated lockfiles also include a CHECKSUMS section, and Bundler verifies each gem against it at install time, so a gem tampered with after the lockfile was created fails to install. Existing lockfiles are not rewritten automatically. The guide documents a Bundler lock command with an add-checksums option for that.
Checksums protect the second install, not the first. If you add a malicious gem and then lock it, the checksum faithfully protects the malicious code. They stop later swaps, which matters for CI and production builds.
What is cooldown?
The guide notes that most malicious releases are detected and yanked within days of publication. Cooldown excludes versions newer than a set number of days from resolution. Enable it per project with bundle config set cooldown 7, or per source in the Gemfile. A trusted internal source can be exempted with cooldown: 0. The feature depends on the gem server publishing a creation time through the v2 compact index; versions from servers that do not provide it are treated as outside the cooldown window, so test that your private server behaves as you expect.
Cooldown has a cost. Urgent security patches also arrive later, so teams usually add a documented override for a known advisory.
Does the human step still matter?
Yes. Typosquats work on people. Before adding a gem, read the exact name, the owner, the release history and the download count on its page, and compare the name against the project you meant. If a gem is two weeks old with one release and a name close to a famous one, do not add it.
What to do
- Put every gem in the Gemfile under an explicit source, with internal gems only in the private source block.
- Add checksums to an existing lockfile with the Bundler lock command and commit the result.
- Set a cooldown of a few days and write down how to override it for urgent fixes.
- Reserve your internal gem names on the public registry if your policy allows it.
- Run
bundler-auditin CI against the Ruby advisory database. - Require review for any change to Gemfile or Gemfile.lock.
Safeguard can inventory dependencies and flag suspicious packages, see the dependency inventory demo.
Quick check
Is one source block for internal gems enough?
No. A block source can still be a candidate for gems without an explicit source, so give every gem an explicit source.
Do checksums prevent installing a malicious new gem?
No. They detect changes after the lockfile was created. Choosing which gems to add still needs review.
Sources
Last reviewed: 18 October 2026.
