Bundler 4.0.13 で導入された「Cooldown（クーリングオフ）」機能の概要と導入方法

RubyGems に対するサジェン攻撃の多くは、極めて限られた時間ウィンドウを狙う手法を採用しています。アカウントが侵害され、悪意のあるパッケージが公開された直後に実行される

bundle install

コマンドは、その脆弱なバージョンを直接使用してしまいます。

Bundler 4.0.13 では、このリスクを軽減するための**「cooldown（クーリングオフ）」という時間ベースのフィルタ機能が追加されました。これにより、パッケージが公開されてから少なくともN 日間**経過後にのみ解決されるようになります。

機能の仕組みと原理

• 公開された後に設計: 他のエコシステムにおける類似課題への対応を借鉴（けいはん）し実現されています。
• 補完的な防御策: オプトイン方式であり、強制二段階認証（2FA）や信頼できる公開（trusted publishing）などを代替するものではありません。それらの機能を補完・強化するものです。
• 判定基準: rubygems.org の v2 コンパクトインデックスが提供する各バージョンごとの

  created_at

  タイムスタンプを読み取ります。
  • ソースが

    created_at

    をエクスポートしていない場合（古いサーバー、v1 フォーマットなど）は**「クーリングオフ対象外」**となり、引き続き通常の解決処理が行われます。
• 非強制性: 常に解決をブロックすることはなく、証明可能に「新しい」と判断できるバージョンのみを保留に置きます。

始め方：導入と設定

Bundler の更新

「cooldown」機能は Bundler 4.0.13 から利用可能です。より古いバージョンをお使いの場合は、チーム全体で一斉に進めるために以下のコマンドで更新し、ロックファイルでのバージョン固定を行います。

$ gem update --system          # または：gem install bundler -v 4.0.13
$ bundle update --bundler=4.0.13

Gemfile の設定

Gemfile

においてソースに対して小さな「cooldown」値を宣言します。これはコードとあわせてコミットされるため、開発者全員および CI ランで自動的に同一の時間ウィンドウが適用されます。

source "https://rubygems.org", cooldown: 7

gem "rails"
gem "puma"

注意点:

• cooldown

  は解決プロセス時に機能します。
• ロックファイルが存在しない場合は

  bundle install

  、存在する場合は

  bundle update

  を実行して再解決を行ってください。
• 既存の

  Gemfile.lock

  は尊重されるため、すでに固定したバージョンへの影響はありません。
• デフォルトでは未設定（unset）であり、指定しないプロジェクトは引き続き最新バージョンを解決します。

その他の設定方法

ソース単位の宣言に加え、以下のいずれかの方法をjしてプロジェクト全体、グローバル、または環境変数を通じて値を適用できます。

設定コマンドと環境変数

$ bundle config set cooldown 7          # このプロジェクトの .bundle/config に保存される
$ bundle config set --global cooldown 7 # このユーザー向けのすべてのプロジェクトに適用される
$ BUNDLE_COOLDOWN=7 bundle install      # ロックファイルが存在しない場合（例：新規 CI チェットアウト時）
$ BUNDLE_COOLDOWN=7 bundle update       # ロックファイルが既に存在する場合の再解決

実行時に指定（一時的な実行向け）

インストールのみを目的とする場合に便利なフラグです。

$ bundle install --cooldown 7
$ bundle update --cooldown 7
$ bundle add rails --cooldown 7
$ bundle outdated --cooldown 7

設定優先順位

複数の指定が存在する場合、以下の順に適用されます：

1. コマンドラインフラグ (

   --cooldown

   ) ※最強
2. 設定値 (

   bundle config

   または環境変数

   BUNDLE_COOLDOWN

   )
3. Gemfile 内のソース単位の設定 (

   cooldown:

   )

制約:

cooldown

値は必ず**非負の整数（日数）**である必要があります。文字列、浮動小数点数、負の数、配列は「InvalidOption エラー」として拒否されます。

ソースの混在への対応

フラグや設定値はすべてのソースに均等に適用されるため、ポリシーが異なるレジストリを扱うにはソース単位のキーワードが適しています。 例：パブリック Gem は待機しつつ、内部レジストリは即時更新するケース

source "https://rubygems.org", cooldown: 7

# 内部ツールだけは恒久的に免除（即時解決）させる設定
source "https://gems.internal.example.com", cooldown: 0 do
  gem "internal-tool"
end

• cooldown: 0

  を指定すると、パブリック Gem が経時化していく中で、その内部ツールだけは常に最新が利用可能になります。
• ⚠️ 注意: コマンドラインフラグ

  --cooldown N

  はすべてのソースを上書きするため、免除対象の内部レジストリを含む場合でも一律に適用されます。

バイパス手段（エスケープハッチ）

コマンドに対して

0

を渡すと、「cooldown」機能を無効化できます。これは以下のシナリオで重要です：

• 必要に応じて最新のバージョンにアクセスしたい時
• ソース単位やグローバル設定を上書きしたい時
• ゼロデイの脆弱性に対する修正パッチが出た場合など、待つことが不適切な状況

--cooldown 0

を使用すれば、他のチームメンバーへのポリシー変更なしで最新バージョンを取得可能です。

$ bundle install --cooldown 0
$ BUNDLE_COOLDOWN=0 bundle update rails   # 今回の更新では設定された cooldown を無視する

動作確認: ジェムの候補となるすべてのバージョンがまだ「クーリングオフ」ウィンドウ内にある場合でも、Bundler は最も新しいリリースには戻らず、除外されたバージョン数を報告します。この状態で継続するには

--cooldown 0

を指定することを確認画面に表示されます。

「Hold Back（保留）」されているものを確認する方法

bundle outdated

コマンドは「cooldown」機能を認識しており、利用可能なまでの残日数を注釈として付与します。これにより、「最新との整合性が取れている（up to date）」状態と、「意図的な待ち時間中の状態（deliberately waiting）」を明確に区別できます。

$ bundle outdated --cooldown 7
Gem             Current   Latest                  Requested   Groups
aws-partitions  1.1251.0  1.1256.0 (cooldown 3d)  = 1.1251.0  default

より広範なセキュリティ投資の一環として

「cooldown」機能は、rubygems.org における広範囲なセキュリティ強化策の一部です。主な防御策の包括的な内容如下：

• インフラの保護: ログイン情報を Have I Been Pwned と照合し、侵害されたパスワードの再利用を防ぐ仕組みを導入済みです（外部から内部への防御）。
• AI 活用によるスキャン: Alpha Omega および Anthropic の支援を受け、専門チームが重要な Gem に対して AI を活用した脆弱性スキャンを実施しています。
• 基準の引き上げ: **信頼できる公開（trusted publishing）と強制二段階認証（2FA）**により、リリースをプッシュできる主体の基準を向上させています。

「cooldown」は、Bundler が rubygems.org の

created_at

タイムスタンプを v2 コンパクトインデックスを通じて公開した事実があって初めて機能します。これはクライアント側の薄いフィルタに過ぎず、rubygems.org チームによる基盤整備がなければ成立しません。

各防御策は異なるギャップをカバーしており、互いを補完強化しています。Ruby プロジェクトとして rubygems.org からの依存関係を解決することは、これらすべての防衛策があなたのために働くことを意味し、最も安全なデフォルト設定となります。