PyPI

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

設定方法

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

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

有料機能

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

匿名で利用する

認証なしで 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 アカウントは不要で、無料で利用できます。

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

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

ステップ 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 / uv を設定する

入手した tg_anon_… トークンを使って 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 コマンドはトークンで認証され、ダウンロード追跡と感染可能性の通知が有効になります。

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

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

別のエコシステムで tg_org_ トークンを発行済みの場合

1 つの tg_org_ トークンは、Takumi Guard の全エコシステム（npm / PyPI / RubyGems）で利用できます。再発行は不要で、お持ちのトークンをそのまま PyPI の設定に使用してください。

トークンを入手したら、pip / uv を以下のように設定してください。

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

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

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

以降の pip install コマンドは組織ユーザートークンで認証され、組織内のダウンロード追跡や、組織宛の感染可能性の通知（Slack・Webhook）が有効になります。

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 サービス経由で短命なアクセストークンと交換する仕組みにより、安全に認証が行われます。

前提条件:

Shisho Cloud に Bot ID が登録されていること。Shisho Cloud コンソールのレジストリ設定ページから Bot ID をコピーしてください。
ワークフロージョブに 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 交換をすべて自動で処理します。

GitHub の OIDC トークンをリクエストする
STS サービスを通じて Takumi Guard の短命なアクセストークンと交換する
そのトークンを使用して 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_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 インデックスに直接アクセスするようになります。ロックファイルの変更は不要です。

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

組織ユーザートークン（tg_org_…）を使用している場合は、パッケージマネージャーの設定変更に加えて、Takumi / Shisho Cloud コンソールの Guard > トークン からトークンを失効させてください。有効なトークンが残っている限り課金対象となります。詳細は料金を参照してください。

クイックリファレンス

パッケージマネージャーと利用ティアの組み合わせごとに、最低限必要な設定をまとめます。tg_anon_xxxxxx / tg_org_xxxxxx は実際のトークンに置き換えてください。

pip

匿名

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

匿名（メール認証）

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

組織

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

uv

uv は pip config や PIP_INDEX_URL を読み取りません。シェルプロファイル（.bashrc / .zshrc など）に UV_INDEX_URL を設定する方法と、uv.toml で永続的に設定する方法の 2 通りがあります。

環境変数で設定する場合

匿名

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

匿名（メール認証）

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

組織

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

`uv.toml` で設定する場合

ユーザーレベルの設定は ~/.config/uv/uv.toml に、プロジェクトレベルの設定は uv.toml か pyproject.toml（[[tool.uv.index]] セクション）に記述します。

匿名（~/.config/uv/uv.toml）

[[index]]
url = "https://pypi.flatt.tech/simple/"
default = true

匿名（メール認証） / 組織（~/.config/uv/uv.toml）

[[index]]
url = "https://token:tg_xxxxxx@pypi.flatt.tech/simple/" # tg_anon_ または tg_org_
default = true

poetry

poetry source add で Takumi Guard をプライマリソースとして登録します。

匿名

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

匿名（メール認証） / 組織

poetry source add --priority=primary takumi-guard https://pypi.flatt.tech/simple/
poetry config http-basic.takumi-guard token tg_xxxxxx # tg_anon_ または tg_org_

poetry 利用時の注意

poetry そのものや、poetry プラグイン・インストーラーは curl ... | python 形式の外部スクリプトを直接実行して導入されることが多いツールです。Takumi Guard は公開レジストリから取得するパッケージを保護しますが、poetry 本体の導入経路や poetry source の挙動は Guard の保護対象外です。pinning（公式インストーラのバージョン明示、社内ミラーへの配置、CI でのバージョン固定など）をできるだけ併用し、サプライチェーン上の攻撃面を不用意に広げないよう注意してください。

設定方法​

匿名で利用する​

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

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

GitHub Actions で利用する​

匿名で利用する​

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

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

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

Extra Index URL​

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

パッケージの公開​

アンインストール​

ローカル環境​

GitHub Actions​

クイックリファレンス​

pip​

uv​

環境変数で設定する場合​

uv.toml で設定する場合​

poetry​

設定方法

匿名で利用する

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

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

GitHub Actions で利用する

匿名で利用する

組織に紐づけて利用する

参考：Action 入力パラメータ

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

Extra Index URL

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

パッケージの公開

アンインストール

ローカル環境

GitHub Actions

クイックリファレンス

pip

uv

環境変数で設定する場合

`uv.toml` で設定する場合

poetry