PyPI

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

設定方法

匿名で利用する

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

pip の場合は、以下のコマンドを実行するだけでインデックス URL を恒久的に設定できます。

pip config set global.index-url https://pypi.flatt.tech/simple/

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

環境変数で設定する方法もあります。シェルプロファイル（.bashrc、.zshrc など）に以下を追加してください。

# シェルプロファイル（.bashrc、.zshrc など）に追加
export PIP_INDEX_URL=https://pypi.flatt.tech/simple/

または pip.conf（Linux/macOS では ~/.config/pip/pip.conf、Windows では %APPDATA%\pip\pip.ini）に設定してください。

[global]
index-url = https://pypi.flatt.tech/simple/

環境を変更せずに一度だけ試す場合は、--index-url を直接指定することもできます。

pip install --index-url https://pypi.flatt.tech/simple/ <package>

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

Takumi Guard は pip、uv、poetry に対応しています。ロックファイルの移行は不要です。パッケージマネージャーはインデックス URL ではなくインテグリティハッシュでパッケージを検証するため、既存のロックファイルはそのまま使用できます。

uv は PIP_INDEX_URL や pip.conf を参照しません。以下のいずれかの方法で設定してください。

環境変数:

export UV_INDEX_URL=https://pypi.flatt.tech/simple/

または ~/.config/uv/uv.toml（ユーザーレベル）に設定:

# ~/.config/uv/uv.toml
[[index]]
url = "https://pypi.flatt.tech/simple/"
default = true

または pyproject.toml（プロジェクト単位）に設定:

# pyproject.toml
[[tool.uv.index]]
url = "https://pypi.flatt.tech/simple/"
default = true

pip と uv の両方に環境変数で対応するには、シェルプロファイルに両方の行を追加してください。

export PIP_INDEX_URL=https://pypi.flatt.tech/simple/
export UV_INDEX_URL=https://pypi.flatt.tech/simple/

poetry の場合は Takumi Guard をプライマリソースとして追加してください。

poetry source add --priority=primary takumi-guard https://pypi.flatt.tech/simple/

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

メールアドレスを登録すると、匿名利用のパッケージブロックに加えて、ダウンロード追跡と感染可能性の通知が利用可能になります。ダウンロードしたパッケージに後からセキュリティアドバイザリが公開された場合、登録したメールアドレスに通知が届きます。Shisho Cloud アカウントは不要で、無料で利用できます。

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

curl -X POST https://pypi.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://pypi.flatt.tech/api/v1/tokens/regenerate

ステップ 3: pip を設定する

以下のコマンドを一度実行するだけで、設定がディスクに永続化されます。

pip config set global.index-url https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

uv を使用している場合は、シェルプロファイル（.bashrc、.zshrc など）に以下も追加してください。uv は pip config を参照しません。

export UV_INDEX_URL=https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

環境変数で両方を設定する方法もあります。シェルプロファイルに以下を追加してください。

export PIP_INDEX_URL=https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/
export UV_INDEX_URL=https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

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

GitHub Actions で利用する

GitHub Actions ワークフローに Takumi Guard を導入するには、flatt-security/setup-takumi-guard-pypi GitHub Action を使用します。匿名で利用する方法と、組織に紐づけて利用する方法があります。

匿名で利用する

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: flatt-security/setup-takumi-guard-pypi@v1
        # bot-id なし（匿名モード、ブロックのみ）

      - run: pip install -r requirements.txt
      - run: pytest

匿名モードでは、Action はインデックス URL の設定のみを行います。ブロック済みパッケージは引き続き 403 エラーで拒否されますが、ダウンロード追跡と感染可能性の通知は利用できません。

組織に紐づけて利用する

Shisho Cloud 組織に紐づけることで、組織レベルでのダウンロード追跡と感染可能性の通知（Webhook 経由）が利用可能になります。CI 環境に長期有効なシークレットを保存する必要はありません。GitHub の OIDC トークンを Shisho Cloud の STS サービス経由で短命なアクセストークンと交換する仕組みにより、安全に認証が行われます。

前提条件:

1. Shisho Cloud に Bot 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: flatt-security/setup-takumi-guard-pypi@v1
        with:
          bot-id: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー

      - run: pip install -r requirements.txt
      - run: pytest

Action は OIDC 交換をすべて自動で処理します。

1. GitHub の OIDC トークンをリクエストする
2. STS サービスを通じて Takumi Guard の短命なアクセストークンと交換する
3. そのトークンを使用して pip を Takumi Guard インデックスに向けるよう設定する

info

Bot ID はシークレットではありません。トークン交換時にトラスト条件を検索するための公開参照キーです。ワークフローファイルに直接コミットできます。Shisho Cloud コンソールには Bot ID があらかじめ入力された、コピーしてすぐ使えるワークフローのスニペットが用意されています。

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

参考：Action 入力パラメータ

入力	必須	デフォルト	説明
bot-id	いいえ	—	Shisho Cloud の Bot ID。匿名ブロックモードの場合は省略します。
set-index-url	いいえ	true	pip.conf を自分で管理し、認証トークンのみ必要な場合は false に設定します。
registry-url	いいえ	https://pypi.flatt.tech	カスタムレジストリ URL。Shisho Cloud サポートから指示された場合のみ変更します。
expires-in	いいえ	1800	アクセストークンの有効期間（秒）。最大 86400（24 時間）。

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

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

Takumi Guard は公開 PyPI パッケージ向けの読み取り専用セキュリティプロキシです。プロジェクトがプライベートパッケージに依存している場合は、--extra-index-url を使用して、プライベートパッケージを別のインデックスから取得しつつ、公開パッケージは Takumi Guard 経由でルーティングできます。

Extra Index URL

Takumi Guard をプライマリインデックスに設定し、プライベートインデックスをエクストラソースとして追加します。pip.conf に以下のように設定してください。

[global]
index-url = https://pypi.flatt.tech/simple/
extra-index-url = https://pypi.your-company.com/simple/

またはコマンドラインで両方を指定します。

pip install \
  --index-url https://pypi.flatt.tech/simple/ \
  --extra-index-url https://pypi.your-company.com/simple/ \
  <package>

この設定により、pip は両方のインデックスを検索し、最も適合するバージョンをインストールします。

警告

エクストラインデックスから取得されたプライベートパッケージは、Takumi Guard のセキュリティスキャンを受けません。自組織のパッケージであれば問題ありませんが、ブロックリストによるチェックが適用されない点にご注意ください。

GitHub Actions でのプライベートパッケージの利用

flatt-security/setup-takumi-guard-pypi Action をプライベートパッケージと併用する場合は、Action に Takumi Guard インデックスの設定を任せたうえで、PIP_EXTRA_INDEX_URL でプライベートインデックスを追加してください。

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: flatt-security/setup-takumi-guard-pypi@v1
        with:
          bot-id: "BT01EXAMPLE..."

      # プライベートインデックスをエクストラソースとして追加
      - run: echo "PIP_EXTRA_INDEX_URL=https://pypi.your-company.com/simple/" >> "$GITHUB_ENV"

      - run: pip install -r requirements.txt
      - run: pytest

パッケージの公開

Takumi Guard はパッケージインストール向けの読み取り専用セキュリティプロキシです。パッケージの公開には影響しません。twine upload などのツールは https://upload.pypi.org/（または設定されたアップロードエンドポイント）と直接通信するため、インデックス URL を経由しません。

twine upload dist/*

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

アンインストール

Takumi Guard の利用を停止するには、インデックス URL の設定をデフォルトの PyPI インデックスに戻してください。

ローカル環境

pip.conf から Takumi Guard 関連の行を削除します。

# 以下の行を削除
[global]
index-url = https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

環境変数でインデックス URL を設定していた場合は、解除します。

unset PIP_INDEX_URL

uv を使用している場合は、対応する変数も解除します。

unset UV_INDEX_URL

poetry のソースを追加していた場合は、削除します。

poetry source remove takumi-guard

GitHub Actions

ワークフローファイルから flatt-security/setup-takumi-guard-pypi のステップを削除してください。

# 以下のステップを削除
- uses: flatt-security/setup-takumi-guard-pypi@v1
  with:
    bot-id: "BT01EXAMPLE..."

info

インデックス URL の設定を削除すると、pip install は公開 PyPI インデックスに直接アクセスするようになります。ロックファイルの変更は不要です。