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

PyPI

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

設定方法​

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

いずれの利用方法も pip・uv・poetry に対応しています。パッケージマネージャーはインデックス URL ではなくインテグリティハッシュでパッケージを検証するため、既存のロックファイルの移行は不要です。ただし、pip・uv・poetry は設定の仕組みがそれぞれ異なるため、利用するパッケージマネージャーごとに設定が必要です。

有料機能

組織ユーザートークンを利用するには、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>

uv​

uv は pip とは独立した設定体系を持ち、PIP_INDEX_URL や pip.conf を参照しません。以下のいずれかの方法で設定してください。

環境変数で設定する場合は、シェルプロファイルに以下を追加してください。

export UV_DEFAULT_INDEX=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_DEFAULT_INDEX=https://pypi.flatt.tech/simple/

poetry​

poetry は pip / uv と異なり、利用するプロジェクトごとに設定が必要です。poetry を使う各リポジトリで以下のコマンドを 1 回実行し、pyproject.toml への変更をコミット・プッシュしてください。詳細は poetry についてを参照してください。

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

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

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

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

お持ちの tg_anon_ トークンは、そのまま npm / PyPI / RubyGems / Go モジュールいずれのエコシステムでも利用できます。再登録は不要で、下記の ステップ 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 / poetry を設定する

pip​

入手した tg_anon_… トークンを使って以下のコマンドを実行してください。設定がディスクに永続化されます。

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

uv​

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

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

環境変数で両方を設定したい場合は、シェルプロファイルに以下を追加してください。

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

poetry​

pip / uv とは異なり、利用するプロジェクトごとに設定が必要です。まずは、poetry を使う各リポジトリで以下のコマンドを 1 回実行し、pyproject.toml への変更をコミット・プッシュしてください。

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

その後、端末ごとの認証情報の設定を行ってください。

poetry config http-basic.takumi-guard token tg_anon_xxxxxx

詳細は poetry についてを参照してください。

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

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

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

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

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

pip​

入手したトークンを使って以下のコマンドを実行してください。

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

uv​

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

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

poetry​

pip / uv とは異なり、利用するプロジェクトごとに設定が必要です。まずは、poetry を使う各リポジトリで以下のコマンドを 1 回実行し、pyproject.toml への変更をコミット・プッシュしてください。

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

その後、端末ごとの認証情報の設定を行ってください。

poetry config http-basic.takumi-guard token tg_org_xxxxxx

詳細は poetry についてを参照してください。

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

poetry について

poetry には、パッケージの取得先（source）をユーザー単位（グローバル）に設定する仕組みがありません。source の設定（poetry source add）はプロジェクト単位で、実行したリポジトリの pyproject.toml（[[tool.poetry.source]] セクション）に書き込まれます。変更をコミット・プッシュすれば、リポジトリのすべての開発者と CI に同じ設定が適用されます。

一方、認証情報（poetry config http-basic.takumi-guard）はユーザー単位の設定ファイル（auth.toml）に保存されます。各開発者の端末で 1 回設定すれば、source を設定したすべてのプロジェクトで共通して使われます。匿名で利用する場合、認証情報の設定は不要です。

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いいえ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
      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​

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

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

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

unset PIP_INDEX_URL

uv​

環境変数で設定していた場合は、解除します。

unset UV_DEFAULT_INDEX

poetry​

poetry のソースを追加していた場合は、削除します。source はプロジェクト単位の設定のため、追加した各リポジトリで実行してください。

poetry source remove takumi-guard

poetry の認証情報を設定していた場合は、あわせて削除してください。こちらはユーザー単位の設定のため、端末ごとに 1 回実行してください。

poetry config --unset http-basic.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_DEFAULT_INDEX を設定する方法と、uv.toml で永続的に設定する方法の 2 通りがあります。

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

匿名

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

匿名（メール認証）

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

組織

export UV_DEFAULT_INDEX=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 は pip / uv と異なり、source の設定は利用するプロジェクトごと、認証情報の設定は端末ごとに必要です。詳細は poetry についてを参照してください。

匿名

poetry を使う各リポジトリで以下のコマンドを 1 回実行し、pyproject.toml の変更をコミット・プッシュしてください。認証情報の設定は不要です。

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

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

poetry を使う各リポジトリで以下のコマンドを 1 回実行し、pyproject.toml の変更をコミット・プッシュしてください。

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

あわせて、各開発者の端末で 1 回、認証情報を設定してください。

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 でのバージョン固定など）をできるだけ併用し、サプライチェーン上の攻撃面を不用意に広げないよう注意してください。

に最終更新