bundler-resolutions

bundler-resolutions

bundler-resolutions is a bundler plugin that allows you to specify gem version requirements in your Gemfile without explicitly declaring a concrete dependency on those gems. It acts much like the resolutions feature in Yarn.

[!WARNING]
This is an experimental project and neither its API stability nor correctness should be assumed

Usage

Add bundler-resolutions to your Gemfile, and add a resolutions group to specify the gems you want to specify versions requirements for.

The resulting Gemfile.lock in this example will have nokogiri locked to 1.16.5 or above.

plugin 'bundler-resolutions'

gem "rails"

group :resolutions do
  gem "nokogiri", ">= 1.16.5" # CVE-2024-34459
end

However the Gemfile.lock from this example will not have nokogiri at all, as it is neither explicitly declared, nor brought in as a transitive dependency.

plugin 'bundler-resolutions'

group :resolutions do
  gem "nokogiri", ">= 1.16.5" # CVE-2024-34459
end

Detail

bundler-resolutions allows you to specify version requirements using standard gem syntax in your Gemfile to indicate that you have version requirements for those gems if they were to be brought in as transitive dependencies, but that you don't depend on them yourself directly.

An example use case is in the Gemfile given below. Here we are saying that although we do not use nokogiri specifically ourselves, we want to ensure that if it is pulled in by other gems then it will always be above the know version with a CVE.

source "https://rubygems.org"

plugin 'bundler-resolutions'

gem "rails"

group :resolutions do
  gem "nokogiri", ">= 1.16.5" # CVE-2024-34459
end

The big difference between doing this and just declaring it in your Gemfile is that it will only be used in resolutions (and be written to your lock file) if the gems you do directly depend on continue to use it. If they stop using it, then your resolutions will take no part in the bundler lock resolution.

The other difference is that even if it does take part in the resolutions, it will not be present in the DEPENDENCIES section of the lock file, as it is not a direct dependency.

Use cases

There are a number of reasons you may want to prevent the usage of some gem versions, without direct use, such as:

1. You have learnt of a CVE of a gem.
2. You have internal processes that mandate the usage of certain gem versions for legal or sign off reasons.
3. You know of gem incompatibilities in later versions.
4. You know that different OS architectures do not work with some versions.

How it works

bundler-resolutions works by patching the Gemfile DSL to allow for special processing of the resolutions group. It also patches the bundler filtered_versions_for method to allow for the resolution restrictions from the versions specified in the resolutions group.

This is a very early version, and it should be considered experimental.

Future work may include relating this to bundler-audit, and other security tools, so you will automatically gain version restrictions against known CVEs.