メインコンテンツまでスキップ

Takumi Guard が Packagist に対応

· 約8分
Deividas Turskis
Deividas Turskis
Software Engineer @ GMO Flatt Security Inc.

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

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

Takumi Guard が Packagist に対応

概要​

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

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

Takumi Guard は標準の Composer リポジトリプロトコルに対応しています。これは Private Packagist や Toran Proxy でも使われている仕組みで、ツール側の変更は不要です。リポジトリ設定を一度行うだけで利用できます。

利用開始​

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

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 以降）。そのため、ロックファイルをコミット済みのプロジェクトも、移行の手順なしで保護されます。

任意：ダウンロード追跡

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

GitHub Actions​

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

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

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

設定の確認​

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

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 クイックスタートの「設定の確認」 を参照してください。

メール登録でさらに便利に（無料）​

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

info

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

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

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

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

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

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

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

プライベートパッケージ​

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

組織全体での管理にも対応​

チーム全体で Takumi Guard を利用する場合、インストールログ検索、組織ユーザートークンの一元管理、感染可能性の通知 Webhook を組織全体の運用で利用できます。Takumi サブスクリプション（Guard 有効化）から始められます。

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

Guard 設定ページ

Guard を有効化したら、Packagist クイックスタート に従って CI や開発端末を設定してください。

GitHub Actions から 長期の組織トークン を利用するだけであれば、支払いは不要です。組織登録時に支払い画面が表示されますが、スキップできます。Guard ページから GitHub 組織を登録するだけで、組織トークンを取得できます。