# RubyGems {#rubygems}

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

## 設定方法 {#setup}

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

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

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

:::info 有料機能
組織ユーザートークンを利用するには、Guard を有効化した Takumi サブスクリプションが必要です。詳しくは[料金と請求](/docs/ja/t/guard/billing/index.md)を参照してください。
:::

### 匿名で利用する {#setup-anonymous}

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

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

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

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

:::tip パッケージマネージャーの互換性
Takumi Guard は **Bundler** 経由での利用に対応しています。Bundler は `~/.bundle/config` からミラー設定を読み取るため、`Gemfile` の変更は不要です。
:::

### ユーザー登録して利用する {#setup-email-verified}

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

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

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

```bash
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 キーはウェルカムメールに直接記載されています。リンクをクリックする手順は不要で、キーはすぐに使用できます。

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

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

### 組織ユーザートークンで利用する {#setup-org-user-token}

組織ユーザートークン（`tg_org_…`）は Takumi / Shisho Cloud コンソールから発行するか、ボットが Guard API を利用して発行できます。発行方法の詳細は[トークンの管理](/docs/ja/t/guard/features/token-management.md#user-tokens)を参照してください。

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

### Bundler の設定方法 {#setup-bundler}

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

```bash
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 で利用する {#setup-ci}

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

#### 匿名で利用する {#setup-ci-anonymous}

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

```yaml
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 エラーで拒否されますが、ダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)は利用できません。

#### 組織に紐づけて利用する {#setup-ci-org}

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

**前提条件:**

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

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

```yaml
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 入力パラメータ {#action-inputs}

| 入力           | 必須 | デフォルト値                   | 説明                                                                   |
| -------------- | ---- | ------------------------------ | ---------------------------------------------------------------------- |
| `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 リポジトリ](https://github.com/flatt-security/setup-takumi-guard-rubygems) を参照してください。

## プライベート gem での利用 {#private-gems}

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

### Gemfile のソースブロック {#private-gems-source-block}

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

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

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

```ruby
# パブリック 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` を指すだけで済み、トークンをバージョン管理にコミットせずに済みます。
:::

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

## セットアップの確認 {#verify-setup}

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

```bash
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` で成功してしまいます。その場合は以下で事前に削除してから再実行してください。

```bash
gem uninstall hola-takumi --all --force
```

:::

## パッケージの公開 {#publishing}

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

```bash
gem push your-gem-1.0.0.gem
```

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

## アンインストール {#uninstall}

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

### ローカル環境 {#uninstall-local}

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

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

### GitHub Actions {#uninstall-ci}

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

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

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