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

PyPI

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

設定方法​

匿名で利用する​

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

以下の行をシェルプロファイル（.bashrc、.zshrc など）に追加すると、pip と uv のすべてのコマンドが恒久的に Takumi Guard を経由するようになります。

# Add to your shell profile (.bashrc, .zshrc, etc.):
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/

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

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

pip install --index-url https://pypi.flatt.tech/simple/ <package>
パッケージマネージャーの互換性

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

uv は PIP_INDEX_URL を自動的に参照します。上記で設定済みであれば、追加の設定は不要です。

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 キーと pip、uv、poetry のセットアップ手順が表示されるページに遷移します。

警告

この API キーは一度しか表示されません。すぐに保存してください。紛失した場合はトークンのローテーションを参照してください。

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

以下の行をシェルプロファイル（.bashrc、.zshrc など）に追加してください。

# Add to your shell profile (.bashrc, .zshrc, etc.):
export PIP_INDEX_URL=https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

または pip.conf に設定してください。

[global]
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 権限が設定されていること。

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

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC トークン交換に必要
    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いいえtruepip.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
    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 インデックスに直接アクセスするようになります。ロックファイルの変更は不要です。

に最終更新