Packagist

Takumi Guard は Composer のリポジトリプロトコルに対応しているため、Private Packagist や Toran Proxy などのミラーと同じ要領で composer install・composer update を経由させることができます。このページでは、ローカル開発環境と CI の両方について、それぞれの利用方法を説明します。

Composer 2.10 以降が必要です

既存の composer.lock からのインストールに対するブロックは、Composer 2.10（2026 年 5 月）で追加された依存ポリシー機能を利用します。それより古い Composer では、ブロックは composer update や composer require には適用されますが、既存ロックファイルからの composer install には適用されません。Composer をアップグレードしてください。

設定方法

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

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

有料機能

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

匿名で利用する

認証なしで Takumi Guard のパッケージブロック機能を利用できます。プロキシを Composer のリポジトリとして追加し、デフォルトの packagist.org を無効化することで、すべてのパッケージがプロキシ経由で解決されるようになります。

# Guard プロキシを Composer のリポジトリとして追加する（グローバル設定）
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech

# デフォルトの packagist.org を無効化する。パッケージの二重読み込みを防ぎ、
# ブロックリストを回避する直接フォールバックを起こさないためです。
composer config --global repositories.packagist.org false

# Guard に到達できないとき、Guard を迂回せずに失敗させる（Composer 2.10 以降）
composer config --global policy.ignore-unreachable false

Composer v2 は packagist.org から取得するはずのパッケージを Guard 経由でミラーします。packagist.org を無効化することで経路が明確になり、ブロックリストを回避する直接フォールバックを防げます。詳しくはこちらをご覧ください。

これで設定は完了です。パッケージブロックは composer install と composer update の両方に適用され、既存の composer.lock からのインストールも対象になります（Composer 2.10 以降）。

任意：ダウンロード追跡を有効にする

composer update mirrors

composer update mirrors は composer update --lock と同じ動作で、パッケージのバージョンを変えずに composer.lock 内の dist URL をプロキシ経由に書き換えます。これはブロックには不要で、ダウンロードしたパッケージが後から悪性と判明した際に通知を受け取れるよう、バージョン単位のダウンロード追跡を有効にするためのものです（ユーザー登録して利用するを参照）。プロジェクトごとに一度実行してください。実行しなくても、次回の composer update 時に自動的に反映されます。

グローバル設定ではなくプロジェクト単位で設定する

グローバル設定を変更したくない場合は、同じ 2 つの repositories エントリをプロジェクトの composer.json に直接記述することもできます。

{
  "repositories": [
    { "type": "composer", "url": "https://packagist.flatt.tech" },
    { "packagist.org": false }
  ]
}

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

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

別のエコシステムで tg_anon_ トークンを取得済みの場合

お持ちの tg_anon_ トークンは、そのまま npm / PyPI / RubyGems / Go / Composer いずれのエコシステムでも利用できます。再登録は不要で、下記の ステップ 3 から進めてください。

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

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

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

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

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

API キーはウェルカムメールの本文に直接記載されています。リンクをクリックする必要はなく、すぐに利用できます。

警告

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

ステップ 3: トークンを送信するよう Composer を設定する

Composer はホスト名ごとの HTTP Basic 認証でリポジトリに認証します。ユーザー名は無視され、トークンはパスワード欄に入れます。

# 1. リポジトリを追加する（未設定の場合）
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false

# 2. トークンを保存する（グローバルの auth.json に書き込まれます）
composer config --global --auth http-basic.packagist.flatt.tech token tg_anon_xxxxxx

# 3. トークンが使えなくなったとき、Guard を迂回せずに失敗させる（Composer 2.10 以降）
composer config --global policy.ignore-unreachable false

# 4. ダウンロードをプロキシ経由にし、インストールをトークンに紐づけて追跡する
#    （プロジェクトごとに一度実行。バージョンは変わらず URL のみ更新されます）
composer update mirrors

これ以降、Composer はパッケージ取得のたびに tg_anon_ トークンで認証します。ロックファイルをプロキシ経由にしておくと、インストールが追跡され、ダウンロードした正確なバージョンに対して感染可能性の通知が届きます。

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

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

info

1 つの tg_org_ トークンは、すべての Takumi Guard エコシステム（npm、PyPI、RubyGems、Go、Composer）で利用できます。別のエコシステムで発行済みであれば、同じトークンをそのまま利用できます。

トークンを取得したら、リポジトリを設定し、トークンを保存します。最後の composer update mirrors は任意で、ダウンロードをプロキシ経由にしてインストールをトークンに紐づけて追跡するためのものです。

composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_org_xxxxxx
composer config --global policy.ignore-unreachable false

# 任意（インストール追跡を有効化。ブロックには不要）
composer update mirrors

これ以降、composer install は組織ユーザートークンで認証し、組織全体のインストール追跡と、組織宛の感染可能性の通知（Slack、Webhook など）が有効になります。

packagist.org を無効化する理由

公開パッケージのリポジトリは Guard プロキシのみとし、packagist.org は無効化してください。

packagist.org を有効なままにすると、Composer はそれを同列のリポジトリとして扱い、パッケージを packagist.org や GitHub から直接解決・ダウンロードして、Guard のブロックリストを回避することがあります。無効化することで、すべての公開パッケージが必ず Takumi Guard 経由で解決されるようになります。

なお、組織独自のプライベートパッケージはこのプロキシを経由させるべきではありません。プライベートパッケージとの併用で説明するとおり、別の vcs リポジトリや path リポジトリとして宣言してください。

CI/CD で利用する

GitHub Actions
GitLab CI/CD

GitHub Actions のワークフローに Takumi Guard を組み込むには、flatt-security/setup-takumi-guard-packagist Action を使います。匿名でも、組織と連携しても利用できます。Action はリポジトリ設定とトークン注入を行い、既存の composer install がそのまま保護されます。コミット済みのロックファイルに対してもブロックが適用され、移行の手順は不要です。Action には Composer 2.10 以降が必要です。

匿名で利用する

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

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
        # bot-id なし — 匿名モード、ブロックのみ

      # 既存のインストールがそのまま保護されます。コミット済みの composer.lock
      # からでもブロック対象のパッケージは拒否されます（Composer 2.10 以降）。移行は不要です。
      - run: composer install --no-interaction

匿名モードでは、Action は Composer のリポジトリ設定のみを行います。ブロック対象のパッケージは composer install 時に拒否されますが、ダウンロード追跡や感染可能性の通知は利用できません。

組織に紐づけて利用する

Shisho Cloud 組織と連携すると、組織全体のダウンロード追跡と感染可能性の通知（Webhook 経由）が利用できます。CI 環境に長期シークレットを保存する必要はありません。 GitHub OIDC トークンを Shisho Cloud STS サービスで短期アクセストークンに交換することで、安全に認証します。

事前準備:

Shisho Cloud に登録した Bot アイデンティティ。Shisho Cloud コンソールのレジストリ設定ページから Bot ID をコピーします。
ワークフローのジョブに id-token: write と contents: read の権限を付与します。

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC トークン交換に必要
      contents: read
    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
        with:
          bot-id: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー

      # すぐに保護されます。コミット済みの composer.lock もブロック対象です。
      # （バージョン単位のダウンロード追跡を Bot 認証で行いたい場合は、この前に
      #  `composer update mirrors` を追加してください。）
      - run: composer install --no-interaction

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

GitHub OIDC トークンを取得する（audience はレジストリホスト）
STS サービスで短期 Takumi Guard アクセストークンに交換する
Composer のリポジトリを設定し、トークンを COMPOSER_AUTH に書き込む

info

Bot ID はシークレットではありません。サインインするボットを指定するための公開された識別子で、認証は OIDC トークンとボットの信頼条件の照合によって行われます。ワークフローファイルに直接コミットできます。Shisho Cloud コンソールでは、Bot ID を埋め込んだコピー可能なワークフロー断片を提供しています。

アクセストークンはデフォルトで 30 分後に失効します（expires-in 入力で最大 24 時間まで設定可能）。認証に失敗した場合（bot-id の誤り、OIDC 権限の不足、STS への到達不可など）、ステップは明確なエラーメッセージで終了します。匿名モードへ暗黙的にフォールバックすることはありません。

参考：Action 入力パラメータ

入力	必須	デフォルト	説明
`bot-id`	いいえ	—	Shisho Cloud の Bot ID。省略すると匿名（ブロックのみ）モードになります。
`set-repository`	いいえ	`true`	Composer のリポジトリを自分で管理する場合は `false` を指定します。
`fail-closed`	いいえ	`true`	`true` の場合、Guard プロキシに到達できない場合やアクセストークンが使えなくなった場合に、`composer install`・`composer update` が失敗します。`false` の場合、Composer は `composer.lock` のパッケージを、記録された GitHub などの取得元から Takumi Guard を経由せずにダウンロードするため、ブロック対象のパッケージもインストールされます。Composer 2.10 以降が必要です。
`registry-url`	いいえ	`https://packagist.flatt.tech`	カスタムレジストリ URL。Shisho Cloud サポートの指示がある場合のみ変更します。
`sts-url`	いいえ	`https://sts.cloud.shisho.dev`	OIDC からアクセストークンへの交換に使う STS サービス URL。
`expires-in`	いいえ	`1800`（秒）	アクセストークンの有効期間（秒）。最大 `86400`（24 時間）。

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

GitLab CI/CD では、ジョブの before_script で Composer の接続先を Takumi Guard に設定します。匿名で利用する方法と、組織に紐づけて利用する方法があります。

匿名で利用する

Shisho Cloud アカウントがなくても、パッケージブロックのために CI で Takumi Guard を利用できます。ジョブに、レジストリの設定を追加してください。

build:
  image: php:8.3-cli-bookworm
  before_script:
    # Composer をインストールする
    - apt-get update -qq && apt-get install -y -qq git unzip
    - curl -fsSL https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

    # Composer の接続先を Takumi Guard にする
    - composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
    - composer config --global repositories.packagist.org false
    # Guard に到達できないとき、Guard を迂回せずに失敗させる（Composer 2.10 以降）
    - composer config --global policy.ignore-unreachable false
  script:
    - composer install --no-interaction

匿名で利用する場合、ブロック済みパッケージは引き続き拒否されますが、ダウンロード追跡と感染可能性の通知は利用できません。

組織に紐づけて利用する

GitLab.com の GitLab CI/CD で Takumi Guard を利用するには、OIDC でボットとして Shisho Cloud に認証し、取得したアクセストークンを Composer に設定します。CI 環境に長期有効なシークレットを保存する必要はなく、GitHub Actions と同様に、パッケージのダウンロード履歴が組織に記録されます。

前提条件:

Shisho Cloud に、対象プロジェクトの GitLab CI/CD の信頼条件を設定したボットが作成されていること。信頼条件の設定方法はボットの認証を参照してください。また、作成したボットの Bot ID を控えてください。
curl と bash が使え、shishoctl の Linux 版（glibc、x86_64 または aarch64）が動作するコンテナイメージを使用すること。Debian ベースの公式イメージ（-slim 版を除く）などが該当します。Alpine ベースのイメージには対応していません。arm64 のランナーでは、shishoctl の URL の x86_64 を aarch64 に置き換えてください。

.gitlab-ci.yml に、以下のようなジョブを追加してください。

build:
  image: php:8.3-cli-bookworm
  id_tokens:
    ID_TOKEN:
      aud: https://gitlab.com
  variables:
    SHISHOCLOUD_BOT_ID: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー
  before_script:
    # Composer をインストールする
    - apt-get update -qq && apt-get install -y -qq git unzip
    - curl -fsSL https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

    # shishoctl をインストールする
    - SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-x86_64-unknown-linux-gnu"
    - curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
    - chmod +x /usr/local/bin/shishoctl

    # ボットとしてサインインし、アクセストークンを取得する
    - shishoctl auth signin:bot
      --bot ${SHISHOCLOUD_BOT_ID}
      <<< ${ID_TOKEN}
      --expires-in-minutes 30 # 既定は 30 分（最大 1440 分）。ジョブに合わせて調整する
    - export ACCESS_TOKEN="$(shishoctl auth print-access-token)"

    # アクセストークンを Composer に設定する
    - composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
    - composer config --global repositories.packagist.org false
    - composer config --global --auth http-basic.packagist.flatt.tech token "$ACCESS_TOKEN"
    # トークンが使えなくなったとき、Guard を迂回せずに失敗させる（Composer 2.10 以降）
    - composer config --global policy.ignore-unreachable false
  script:
    # バージョン単位のダウンロード追跡を Bot 認証で行いたい場合は、この前に
    # `composer update mirrors` を追加してください。
    - composer install --no-interaction

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

プライベートパッケージとの併用

Takumi Guard は公開パッケージ向けの読み取り専用セキュリティプロキシです。プロジェクトがプライベートパッケージ（プライベートな GitHub リポジトリや Private Packagist など）に依存している場合は、それらを独自のリポジトリとして宣言し、Guard を経由せず直接取得させます。

{
  "repositories": [
    { "type": "composer", "url": "https://packagist.flatt.tech" },
    { "type": "vcs", "url": "https://github.com/your-org/private-lib" },
    { "packagist.org": false }
  ]
}

Composer は各パッケージを、それを提供するリポジトリから解決します。公開パッケージは Takumi Guard を経由し、vcs / path リポジトリは既存の Git 認証情報を使って直接取得されます。

警告

VCS から直接取得されるプライベートパッケージは、Takumi Guard のセキュリティ検査を経由しません。組織独自のパッケージであれば許容できますが、これらのパッケージはブロックリストと照合されない点に注意してください。

セットアップの確認

Composer が Takumi Guard 経由になっているかを確認するには、設定されたリポジトリを確認し、実際の取得がプロキシホストを経由する様子を観察します。

# 1. Guard リポジトリが設定され、packagist.org が無効化されていることを確認する
composer config --global --list | grep -E 'repositories|packagist'

# 2. ブロックが機能していることを確認する。flatt-security/hola-takumi-php は、
#    当社が公開している無害なテスト用パッケージで、常にブロックリストに登録されています。
#    そのため、このコマンドは必ず失敗します。--dry-run はプロジェクトに書き込まずに解決します。
composer require --dry-run flatt-security/hola-takumi-php

2 番目のコマンドは必ず失敗し、パッケージがフラグ付けされているためインストールできないと報告されます。もし成功してしまう場合は、リクエストが Takumi Guard を経由していません（手順 1 を再確認してください）。ブロックリストに登録されたパッケージは composer install・composer update・composer require のいずれでも拒否されます（Composer 2.10 以降では、既存ロックファイルからのインストールでも適用されます）。許可されたパッケージの特定バージョンがブロック対象の場合は、そのバージョンが解決から除外されるため、Composer はそのバージョンを選択しません。

アンインストール

Takumi Guard の利用をやめるには、リポジトリ設定を削除し、デフォルトの Packagist に対して再解決します。

ローカル環境

# 1. Guard リポジトリを削除し、packagist.org を再度有効化する
composer config --global --unset repositories.takumi-guard
composer config --global --unset repositories.packagist.org

# 2. 保存したトークンと、Guard を迂回せずに失敗させる設定を削除する
composer config --global --unset --auth http-basic.packagist.flatt.tech
composer config --global --unset policy.ignore-unreachable

# 3. 各プロジェクトのロックファイルをデフォルトの Packagist で再解決する
composer update mirrors

CI/CD

GitHub Actions
GitLab CI/CD

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

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

.gitlab-ci.yml の before_script から、Composer を Takumi Guard に向ける設定の行を削除してください。組織に紐づけて利用している場合は、shishoctl の行も削除してください。

組織ユーザートークンの失効

組織ユーザートークン（tg_org_…）を利用している場合は、ローカル設定の更新に加えて、Shisho Cloud コンソールの Guard > トークン からトークンを失効させてください。有効なトークンは課金が継続します。詳しくは料金を参照してください。

クイックリファレンス

各利用ティアの最小構成です。tg_anon_xxxxxx / tg_org_xxxxxx は実際のトークンに置き換えてください。ブロックの設定は composer config の行で完了します。末尾の composer update mirrors は任意で、ダウンロード追跡を有効にするためのものです（プロジェクトごとに一度実行）。

匿名

composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global policy.ignore-unreachable false
composer update mirrors  # 任意: ダウンロード追跡

匿名（メール認証）

composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_anon_xxxxxx
composer config --global policy.ignore-unreachable false
composer update mirrors  # 任意: ダウンロード追跡

組織

composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_org_xxxxxx
composer config --global policy.ignore-unreachable false
composer update mirrors  # 任意: ダウンロード追跡

設定方法​

匿名で利用する​

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

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

packagist.org を無効化する理由​

CI/CD で利用する​

匿名で利用する​

組織に紐づけて利用する​

参考：Action 入力パラメータ​

匿名で利用する​

組織に紐づけて利用する​

プライベートパッケージとの併用​

セットアップの確認​

アンインストール​

ローカル環境​

CI/CD​

組織ユーザートークンの失効​

クイックリファレンス​

匿名​

匿名（メール認証）​

組織​

設定方法

匿名で利用する

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

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

packagist.org を無効化する理由

CI/CD で利用する

匿名で利用する

組織に紐づけて利用する

参考：Action 入力パラメータ

匿名で利用する

組織に紐づけて利用する

プライベートパッケージとの併用

セットアップの確認

アンインストール

ローカル環境

CI/CD

組織ユーザートークンの失効

クイックリファレンス

匿名

匿名（メール認証）

組織