PyPI

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

設定方法

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

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

いずれの利用方法も 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

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 を設定したすべてのプロジェクトで共通して使われます。匿名で利用する場合、認証情報の設定は不要です。

CI/CD で利用する

GitHub Actions
GitLab CI/CD

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 はシークレットではありません。サインインするボットを指定するための公開された識別子で、認証は OIDC トークンとボットの信頼条件の照合によって行われます。ワークフローファイルに直接コミットできます。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 リポジトリを参照してください。

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

匿名で利用する

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

build:
  image: python:3.12-bookworm
  before_script:
    # pip の接続先を Takumi Guard にする
    - pip config set global.index-url https://pypi.flatt.tech/simple/
  script:
    - pip install -r requirements.txt
    - pytest

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

組織に紐づけて利用する

GitLab.com の GitLab CI/CD で Takumi Guard を利用するには、OIDC でボットとして Shisho Cloud に認証し、取得したアクセストークンを pip に設定します。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: python:3.12-bookworm
  id_tokens:
    ID_TOKEN:
      aud: https://gitlab.com
  variables:
    SHISHOCLOUD_BOT_ID: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー
  before_script:
    # 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)"

    # アクセストークンを pip に設定する
    - pip config set global.index-url "https://token:${ACCESS_TOKEN}@pypi.flatt.tech/simple/"
  script:
    - pip install -r requirements.txt
    - pytest

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

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

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

CI/CD

GitHub Actions
GitLab CI/CD

ワークフローファイルから 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 > トークン からトークンを失効させてください。有効なトークンが残っている限り課金対象となります。詳細は料金を参照してください。

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

クイックリファレンス

パッケージマネージャーと利用ティアの組み合わせごとに、最低限必要な設定をまとめます。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 でのバージョン固定など）をできるだけ併用し、サプライチェーン上の攻撃面を不用意に広げないよう注意してください。

設定方法​

匿名で利用する​

pip​

uv​

poetry​

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

pip​

uv​

poetry​

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

pip​

uv​

poetry​

CI/CD で利用する​

匿名で利用する​

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

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

匿名で利用する​

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

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

Extra Index URL​

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

パッケージの公開​

アンインストール​

ローカル環境​

pip​

uv​

poetry​

CI/CD​

クイックリファレンス​

pip​

uv​

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

uv.toml で設定する場合​

poetry​

設定方法

匿名で利用する

pip

uv

poetry

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

pip

uv

poetry

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

pip

uv

poetry

CI/CD で利用する

匿名で利用する

組織に紐づけて利用する

参考：Action 入力パラメータ

匿名で利用する

組織に紐づけて利用する

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

Extra Index URL

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

パッケージの公開

アンインストール

ローカル環境

pip

uv

poetry

CI/CD

クイックリファレンス

pip

uv

環境変数で設定する場合

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

poetry