# Takumi Guard が Packagist に対応

Takumi Guard が npm・PyPI・RubyGems・Go に加えて **Packagist** に対応しました。

PHP プロジェクトで **Composer**（`composer install`・`composer update`）を Takumi Guard 経由でルーティングすることで、CI や開発環境に届く前に悪性パッケージをブロックできるようになりました。

![Takumi Guard が Packagist に対応](/docs/ja/_md-assets/c93dbb709c-eyecatch.png)

## 概要 {#overview}

Takumi Guard は、パッケージマネージャーと上流レジストリの間に位置するセキュリティプロキシです。すべてのインストールリクエストを GMO Flatt Security の脅威データベースと照合し、悪性パッケージをブロックします。

今回のリリースにより、npm・Python・Ruby・Go のユーザーが利用していた保護機能が PHP エコシステムでも利用可能になりました。

- **[パッケージブロック](/docs/ja/t/guard/features/package-blocking)**: 悪性パッケージをコードの取得前にブロック
- **[ダウンロード追跡](/docs/ja/t/guard/features/installation-logs)**: 認証済みユーザーのインストール履歴を記録
- **[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications)**: ダウンロードしたパッケージが後から悪性であると判明した際に通知

Takumi Guard は標準の [Composer リポジトリプロトコル](https://getcomposer.org/doc/05-repositories.md#composer)に対応しています。これは Private Packagist や Toran Proxy でも使われている仕組みで、ツール側の変更は不要です。リポジトリ設定を一度行うだけで利用できます。

## 利用開始 {#getting-started}

以下の手順は匿名で利用できます。アカウント登録は不要です。Takumi Guard を Composer のリポジトリとして追加し、デフォルトの packagist.org を無効化することで、すべてのパッケージがプロキシ経由で解決されます。

```bash
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
```

これで設定は完了です。ブロックは `composer install` と `composer update` に適用され、既存の `composer.lock` からのインストールも対象になります（Composer 2.10 以降）。そのため、ロックファイルをコミット済みのプロジェクトも、移行の手順なしで保護されます。

:::info 任意：ダウンロード追跡
インストールした正確なバージョンについて通知を受け取りたい場合は、プロジェクトごとに一度 `composer update mirrors` を実行してください（`composer update --lock` と同じ動作で、バージョンを変えずにロックファイルのダウンロード URL を更新します）。これはアーティファクトのダウンロードをプロキシ経由にするもので、**ブロックには不要**です。
:::

### GitHub Actions

[`flatt-security/setup-takumi-guard-packagist`](https://github.com/flatt-security/setup-takumi-guard-packagist) Action を使います。ブロックのみであればアカウントもトークンも不要です。Action がリポジトリを設定し、既存の `composer install` がそのまま保護されます（コミット済みのロックファイルも対象です）。

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.3"
          tools: composer:v2
      - uses: flatt-security/setup-takumi-guard-packagist@v1
      - run: composer install --no-interaction
```

組織全体のダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications)が必要な場合は、`bot-id` を指定し、`id-token: write` 権限を付与してください。Action が OIDC から短期トークンへの交換を自動で行うため、CI に長期シークレットを保存する必要はありません。詳しい手順は [Packagist クイックスタート](/docs/ja/t/guard/quickstart/packagist#setup-ci) を参照してください。

## 設定の確認 {#verify}

ブロックが有効になっているかは、当社が公開しているテスト用パッケージ `flatt-security/hola-takumi-php` を require してみることで確認できます。これは無害なパッケージですが、常にブロックリストに登録されています。

```bash
composer require --dry-run flatt-security/hola-takumi-php
```

このコマンドは、パッケージがフラグ付けされているというエラーで必ず**失敗**します。もし成功してしまう場合は、リクエストが Takumi Guard を経由していません。`composer config --global --list | grep -E 'repositories|packagist'` を再確認してください。ブロックリストに登録されたパッケージは、`composer install`・`composer update`・`composer require` のいずれでも拒否されます。詳しくは [Packagist クイックスタートの「設定の確認」](/docs/ja/t/guard/quickstart/packagist#verify-setup) を参照してください。

## メール登録でさらに便利に（無料） {#email-registration}

メールアドレスを登録すると、ダウンロードしたパッケージに後から悪意があると判明した際に通知を受け取れます。無料で利用できます。

:::info
別のエコシステム（npm・PyPI・RubyGems・Go）で組織ユーザートークンやメール認証トークンを取得済みの場合、再登録は不要です。同じトークンが Composer でも利用できます。
:::

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

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

**ステップ 2:** ウェルカムメールから API キーを取得する。キーはメール本文に直接記載されており、リンクをクリックする必要はありません。

**ステップ 3:** パッケージ取得のたびに認証されるよう、トークンを保存する

```bash
composer config --global --auth http-basic.packagist.flatt.tech token tg_anon_xxxxxx
```

Composer はホスト名ごとの HTTP Basic 認証を使います。ユーザー名は無視され、トークンはパスワード欄に入ります。これでインストールが追跡され、ダウンロードしたパッケージが後から悪性と判明した際に通知が届きます。

## プライベートパッケージ {#private-packages}

公開パッケージは Takumi Guard を経由し、プライベートパッケージ（プライベートな GitHub リポジトリなど）はプロキシを経由させないようにします。Guard リポジトリと並べて、それらを独自の `vcs` / `path` リポジトリとして宣言すると、Composer は各パッケージを提供元のリポジトリから解決します。詳しくは [Packagist クイックスタート](/docs/ja/t/guard/quickstart/packagist#private-packages) を参照してください。

## 組織全体での管理にも対応 {#organization-setup}

チーム全体で Takumi Guard を利用する場合、[インストールログ検索](/docs/ja/t/guard/features/installation-logs)、[組織ユーザートークンの一元管理](/docs/ja/t/guard/features/token-management)、[感染可能性の通知 Webhook](/docs/ja/t/guard/features/breach-notifications) を組織全体の運用で利用できます。Takumi サブスクリプション（Guard 有効化）から始められます。

1. [https://cloud.shisho.dev/hello/takumi](https://cloud.shisho.dev/hello/takumi) にアクセスしてサインインする
2. 組織を登録し、Takumi をサブスクライブする
3. サイドバーから **Guard** > **設定** に移動する
4. 「有効化」をクリックして Guard を有効にする

![Guard 設定ページ](/docs/ja/_md-assets/909d624667-ui-guard-settings.png)

Guard を有効化したら、[Packagist クイックスタート](/docs/ja/t/guard/quickstart/packagist) に従って CI や開発端末を設定してください。

GitHub Actions から [長期の組織トークン](/docs/ja/t/guard/quickstart/packagist#setup-org-user-token) を利用するだけであれば、**支払いは不要**です。組織登録時に支払い画面が表示されますが、スキップできます。Guard ページから GitHub 組織を登録するだけで、組織トークンを取得できます。