RubyGems

Takumi Guard のセットアップは、利用環境と必要な機能に応じて異なります。このページでは、ローカル開発環境と GitHub Actions の両方について、それぞれの利用方法を説明します。

設定方法

Takumi Guard には3つの利用方法があります。

• 匿名で利用する — トークン不要。ミラー URL を設定するだけでパッケージブロックが有効になります。
• ユーザー登録して利用する — メール認証トークン（tg_anon_…）を使い、ダウンロード追跡と侵害通知を有効にします。
• 組織ユーザートークンで利用する — 組織ユーザートークン（tg_org_…）を使い、組織全体のインストール状況を追跡できます。

メール認証トークンと組織ユーザートークンによる利用は、いずれもパッケージマネージャーでの設定方法は同じです。

有料機能

組織ユーザートークンを利用するには、Guard を有効化した Takumi サブスクリプションが必要です。詳しくは料金と請求を参照してください。

匿名で利用する

認証なしで Takumi Guard のパッケージブロック機能を利用できます。ミラー URL を設定するだけで、悪意あるパッケージのブロックが有効になります。ダウンロード追跡や感染可能性の通知は利用できませんが、最も手軽に導入できる方法です。

Bundler をミラー URL で設定してください。

bundle config set --global mirror.https://rubygems.org https://rubygems.flatt.tech/

以上です。以降の bundle install コマンドはすべて Takumi Guard 経由でルーティングされます。

パッケージマネージャーの互換性

Takumi Guard は Bundler 経由での利用に対応しています。Bundler は ~/.bundle/config からミラー設定を読み取るため、Gemfile の変更は不要です。

ユーザー登録して利用する

メールアドレスを登録すると、匿名利用のパッケージブロックに加えて、ダウンロード追跡と感染可能性の通知が利用可能になります。ダウンロードした Gem が後から悪性であると判明した場合、登録したメールアドレスに通知が届きます。Shisho Cloud アカウントは不要で、無料で利用できます。

info

既に npm や PyPI で Takumi Guard を利用していて、組織ユーザートークンやメール認証トークンをお持ちの場合は、再取得の必要はありません。そのまま RubyGems の設定でも利用できます。

ステップ 1: メールアドレスを登録する

curl -X POST https://rubygems.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "ja"}'

language フィールドは省略可能で、デフォルトは "en"（英語）です。"ja" を指定すると、確認メールや感染可能性の通知を含むすべてのメールが日本語で届きます。この設定はトークンに保存され、以降のメールすべてに適用されます。

数秒以内にウェルカムメールが届きます。

ステップ 2: メールに記載された API キーを確認する

API キーはウェルカムメールに直接記載されています。リンクをクリックする手順は不要で、キーはすぐに使用できます。

警告

API キーは安全な場所に保存してください。新しいキーが必要な場合は、いつでも再生成できます。curl -X POST -H 'Authorization: Bearer tg_anon_xxxxxx' https://rubygems.flatt.tech/api/v1/tokens/regenerate

トークンを入手したら、下記の「Bundler の設定方法」に進んでください。

組織ユーザートークンで利用する

組織ユーザートークン（tg_org_…）は Takumi / Shisho Cloud コンソールから発行するか、ボットが Guard API を利用して発行できます。発行方法の詳細はトークンの管理を参照してください。

トークンを入手したら、下記の「Bundler の設定方法」に進んでください。

Bundler の設定方法

お持ちのトークン（メール認証トークンまたは組織ユーザートークン）を使って Bundler を設定してください。推奨されるプライマリな設定方法です。

bundle config set --global mirror.https://rubygems.org https://token:YOUR_API_KEY@rubygems.flatt.tech/

このコマンドにより、すべての bundle install 呼び出しが透過的に Takumi Guard 経由でルーティングされます。Gemfile の変更は不要で、Bundler がミラー設定を自動的に適用します。

以降の bundle install コマンドはトークンで認証され、ダウンロード追跡と感染可能性の通知が利用可能になります。

GitHub Actions で利用する

GitHub Actions ワークフローに Takumi Guard を統合するには、flatt-security/setup-takumi-guard-rubygems GitHub Action を使用してください。匿名モードまたは組織にリンクされたモードで利用できます。

匿名で利用する

Shisho Cloud アカウントをお持ちでない場合でも、CI でパッケージブロック機能を利用できます。bot-id 入力を省略してください。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"

      - uses: flatt-security/setup-takumi-guard-rubygems@v1
        # bot-id を指定しない — 匿名モード（ブロックのみ）

      - run: bundle install
      - run: bundle exec rspec

匿名モードでは、Action は rubygems.org 向けの Bundler ミラーを設定するだけです。ブロック対象のパッケージは 403 エラーで拒否されますが、ダウンロード追跡と感染可能性の通知は利用できません。

組織に紐づけて利用する

Shisho Cloud の組織にリンクすると、組織レベルのダウンロード追跡と感染可能性の通知（ウェブフック経由）が利用可能になります。長寿命なシークレットをCI環境に保存する必要がなく、GitHub OIDC トークンと Shisho Cloud STS サービスの短期アクセストークン交換により、認証が安全に行われます。

前提条件:

1. Shisho Cloud に登録されたボット ID。Shisho Cloud コンソールのレジストリ設定ページから Bot ID をコピーしてください。
2. ワークフロージョブの id-token: write と contents: read パーミッション。

ステップ 1: Action をワークフローに追加する

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC トークン交換に必要
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"

      - uses: flatt-security/setup-takumi-guard-rubygems@v1
        with:
          bot-id: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー

      - run: bundle install
      - run: bundle exec rspec

この Action は OIDC 交換を自動で処理します。

1. GitHub OIDC トークン（audience はレジストリホスト）を取得
2. STS サービスで Takumi Guard の短期アクセストークンに交換
3. Takumi Guard レジストリを指すように rubygems.org の Bundler ミラーを設定

info

Bot ID は秘匿情報ではありません。トークン交換時に許可リストを参照するための公開識別子です。ワークフローファイルに直接コミットできます。Shisho Cloud コンソールには、Bot ID が事前入力されたコピー可能なワークフロースニペットが用意されています。

アクセストークンの有効期限はデフォルトで 30 分です（expires-in 入力で最大 24 時間まで設定可能）。

参考：Action 入力パラメータ

入力	必須	デフォルト値	説明
bot-id	No	—	Shisho Cloud の Bot ID。省略した場合は匿名ブロックのみのモードになる。
set-mirror	No	true	Bundler ミラーを自分で管理する場合は false に設定する。
registry-url	No	https://rubygems.flatt.tech	レジストリ URL。Shisho Cloud サポートから指示があった場合のみ上書き。
sts-url	No	https://sts.cloud.shisho.dev	OIDC → アクセストークン交換に使用する STS サービス URL。
expires-in	No	1800（秒）	アクセストークンの有効期限（秒）。最大 86400（24 時間）。

入力・出力の完全なリストは Action リポジトリ を参照してください。

プライベート gem での利用

Takumi Guard はパブリックな gem の読み取り専用セキュリティプロキシです。プロジェクトがプライベート gem に依存している場合、プライベート gem が Takumi Guard をバイパスして直接レジストリから取得されるように Gemfile を設定する必要があります。

Gemfile のソースブロック

Bundler は Gemfile の source ブロックを使用した、ソースごとのレジストリルーティングに対応しています。プライベートレジストリ用のソースブロックを追加することで、プライベート gem を直接ルーティングしながら、パブリック gem は引き続き Takumi Guard 経由でルーティングできます。

例えば、プライベート gem をカスタム gem サーバーでホストしている場合。

Gemfile には rubygems.org をそのまま記述してください。上述の bundle config mirror 設定により、rubygems.org 向けのリクエストは自動的に Takumi Guard 経由でルーティングされます。プライベートレジストリ用のソースブロックだけを明示的に追加します。

# パブリック gem → bundle config の mirror 設定により Takumi Guard 経由で取得
source 'https://rubygems.org' do
  gem 'rails', '~> 7.1'
  gem 'bundler', '~> 2.4'
end

# プライベート gem → Takumi Guard をバイパス、直接取得
source 'https://gem-server.your-company.com/' do
  gem 'your-company-utils'
  gem 'your-company-auth'
end

この設定により、Bundler は以下のようにリクエストをルーティングします。

• gem 'rails' → mirror 設定により Takumi Guard 経由で取得（セキュリティスキャン適用）
• gem 'your-company-utils' → プライベートレジストリから直接取得（Takumi Guard をバイパス）

tip

Gemfile に Takumi Guard の URL や API キーを直接書く必要はありません。bundle config mirror で設定しておけば、Gemfile は通常どおり rubygems.org を指すだけで済み、トークンをバージョン管理にコミットせずに済みます。

警告

別のレジストリにルーティングされたプライベート gem は、Takumi Guard のセキュリティスキャンをバイパスします。組織独自のパッケージについては許容されますが、これらのパッケージはブロックリストに対してチェックされないことにご注意ください。

セットアップの確認

Takumi Guard が正しく動作していることを確認するには、検証用・無害なブロック済み gem hola-takumi のバージョン 0.1.0 をインストールしてみてください。hola-takumi は Takumi Guard の動作確認用に GMO Flatt Security が公開している無害なテスト gem です。

cd $(mktemp -d) && printf 'source "https://rubygems.org"\ngem "hola-takumi", "0.1.0"\n' > Gemfile && bundle install

Takumi Guard が正しく設定されていれば、proxy 側で当該バージョンがフィルタリングされるため、Bundler は以下のエラーでインストールに失敗します。

Fetching gem metadata from https://rubygems.flatt.tech/.
Could not find gem 'hola-takumi (= 0.1.0)' in rubygems repository
https://rubygems.org/ or installed locally.

note

過去に hola-takumi 0.1.0 をローカルに install したことがある場合、Bundler は proxy 経由で取得せずにローカルの gem を流用し、エラーにならずに Using hola-takumi 0.1.0 で成功してしまいます。その場合は以下で事前に削除してから再実行してください。

gem uninstall hola-takumi --all --force

パッケージの公開

Takumi Guard はパッケージインストール用の読み取り専用セキュリティプロキシです。パッケージの公開は影響を受けません。gem push などのツールはミラー URL を通さず https://rubygems.org に直接通信するためです。

gem push your-gem-1.0.0.gem

公開ワークフローの変更は不要です。

アンインストール

Takumi Guard の利用を停止する場合は、ミラー設定を削除してください。

ローカル環境

Bundler の Takumi Guard ミラー設定を削除します。

bundle config unset --global mirror.https://rubygems.org

GitHub Actions

ワークフローファイルから Takumi Guard の Action を削除します。

# 以下のステップを削除
- uses: flatt-security/setup-takumi-guard-rubygems@v1

info

Action が削除されると、bundle install はパブリック RubyGems レジストリに直接アクセスします。ロックファイルの変更は不要です。