# PyPI {#pypi}

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

## 設定方法 {#setup}

### 匿名で利用する {#setup-anonymous}

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

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

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

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

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

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

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

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

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

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

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

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

環境変数:

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

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

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

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

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

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

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

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

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

:::

### ユーザー登録して利用する {#setup-email-verified}

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

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

```bash
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 キーはウェルカムメールに直接記載されています。リンクをクリックする手順は不要で、キーはすぐに使用できます。

:::warning
API キーは安全な場所に保存してください。新しいキーが必要な場合は、いつでも再生成できます。`curl -X POST -H 'Authorization: Bearer tg_anon_xxxxxx' https://pypi.flatt.tech/api/v1/tokens/regenerate`
:::

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

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

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

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

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

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

```bash
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 で利用する {#setup-ci}

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

#### 匿名で利用する {#setup-ci-anonymous}

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

```yaml
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 エラーで拒否されますが、ダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)は利用できません。

#### 組織に紐づけて利用する {#setup-ci-org}

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

**前提条件:**

1. Shisho Cloud に Bot ID が登録されていること。Shisho Cloud コンソールのレジストリ設定ページから **Bot ID** をコピーしてください。
2. ワークフロージョブに `id-token: write` および `contents: read` 権限が設定されていること。

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

```yaml
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 入力パラメータ {#action-inputs}

| 入力            | 必須   | デフォルト                | 説明                                                                            |
| --------------- | ------ | ------------------------- | ------------------------------------------------------------------------------- |
| `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 リポジトリ](https://github.com/flatt-security/setup-takumi-guard-pypi) を参照してください。

## プライベートパッケージとの併用 {#private-packages}

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

### Extra Index URL {#private-packages-extra-index}

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

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

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

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

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

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

### GitHub Actions でのプライベートパッケージの利用 {#private-packages-ci}

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

```yaml
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
```

## パッケージの公開 {#publishing}

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

```bash
twine upload dist/*
```

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

## アンインストール {#uninstall}

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

### ローカル環境 {#uninstall-local}

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

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

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

```bash
unset PIP_INDEX_URL
```

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

```bash
unset UV_INDEX_URL
```

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

```bash
poetry source remove takumi-guard
```

### GitHub Actions {#uninstall-ci}

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

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

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