Skip to main content
View as Markdown

PyPI

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

Takumi Guard setup varies depending on your environment and the features you need. This page covers setup for both local development and GitHub Actions.

Setup​

Takumi Guard offers three ways to get started:

  • Anonymous — No token required. Set the index URL to enable package blocking.
  • Email-Verified — Use an email-verified token (tg_anon_…) for download tracking and breach notifications.
  • Org User Token — Use an org user token (tg_org_…) to track installations across your organization.

All three options work with pip, uv, and poetry. No lockfile migration is needed — package managers verify packages by integrity hash, not by index URL. Note, however, that pip, uv, and poetry each have their own configuration mechanism, so every package manager you use needs its own setup.

Anonymous Usage​

You can use Takumi Guard's package blocking without authentication. Simply set the index URL to enable malicious package blocking. Download tracking and breach notifications are not available, but this is the easiest way to get started.

pip​

Run the following command to permanently set the index URL:

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

That's it. All pip install commands now route through Takumi Guard.

Alternatively, you can set the index URL via an environment variable in your shell profile (.bashrc, .zshrc, etc.):

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

Or configure in pip.conf (~/.config/pip/pip.conf on Linux/macOS, %APPDATA%\pip\pip.ini on Windows):

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

For a single one-time install without changing your environment, you can also pass --index-url directly:

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

uv​

uv has its own configuration mechanism independent from pip and does not read PIP_INDEX_URL or pip.conf. Use one of the following.

To configure via an environment variable, add the following to your shell profile:

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

To configure in ~/.config/uv/uv.toml (user-level):

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

To configure in pyproject.toml (per-project):

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

If you use both pip and uv, the easiest way is to add both environment variables to your shell profile:

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

poetry​

poetry, unlike pip and uv, must be configured per project. Run the following command once in each repository that uses poetry, then commit and push the pyproject.toml change. See About poetry for details.

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

Email-Verified Access​

Registering your email address enables download tracking and breach notifications in addition to package blocking. If a security advisory is published for a package you previously downloaded, a notification is sent to your registered email address. No Shisho Cloud account is required, and this is free of charge.

info

If you already have a tg_anon_ token from using Takumi Guard with npm, RubyGems, or Go modules, you don't need to register again — the same token works for PyPI. Skip to Step 3: Configure pip / uv / poetry below.

Step 1: Register your email

curl -X POST https://pypi.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "en"}'

The language field is optional and defaults to "en". Set it to "ja" to receive emails in Japanese. This preference is stored with your token and applies to all future emails, including breach notifications.

You'll receive a welcome email within a few seconds.

Step 2: Get your API key from the email

Your API key is included directly in the welcome email. The key is ready to use immediately — no link to click.

warning

Save this key somewhere secure. If you need a new one, you can regenerate it anytime: curl -X POST -H 'Authorization: Bearer tg_anon_xxxxxx' https://pypi.flatt.tech/api/v1/tokens/regenerate

Step 3: Configure pip / uv / poetry

pip​

Run the following command with the tg_anon_… token you just received. The setting persists to disk:

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

uv​

Add the following to your shell profile (.bashrc, .zshrc, etc.) — uv does not read pip config:

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

Alternatively, you can set both via environment variables in your shell profile:

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​

Unlike pip / uv, poetry must be configured per project. First, run the following command once in each repository that uses poetry, then commit and push the pyproject.toml change.

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

After that, configure the credential once per machine.

poetry config http-basic.takumi-guard token tg_anon_xxxxxx

See About poetry for details.

Your pip install commands now authenticate with the token, enabling download tracking and breach notifications.

Org User Tokens​

Org user tokens (tg_org_…) let you track and search package installations across your organization members. Tokens can be issued from Guard > Tokens in the Shisho Cloud console, or by a bot via the Guard API. See Token Management for details on issuing tokens.

info

A single tg_org_ token works across all Takumi Guard ecosystems (npm, PyPI, RubyGems, Go modules). If you have already issued a token for another ecosystem, the same token can be used here.

pip​

Run the following command with your token:

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

uv​

Add the following to your shell profile (.bashrc, .zshrc, etc.) — uv does not read pip config:

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

poetry​

Unlike pip / uv, poetry must be configured per project. First, run the following command once in each repository that uses poetry, then commit and push the pyproject.toml change.

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

After that, configure the credential once per machine.

poetry config http-basic.takumi-guard token tg_org_xxxxxx

See About poetry for details.

Your pip install commands now authenticate with the org user token, enabling organization-wide install tracking and organization-level breach notifications (Slack, webhook, etc.).

About poetry

poetry has no user-level (global) setting for package sources. The source setting (poetry source add) is per project — it is written to the repository's pyproject.toml (the [[tool.poetry.source]] section). Once the change is committed and pushed, the same setting applies to every developer and CI on the repository.

The credential (poetry config http-basic.takumi-guard), on the other hand, is stored in the user-level config file (auth.toml). Set it once per machine and it is shared by every project that has the source configured. No credential is needed for anonymous usage.

GitHub Actions​

To integrate Takumi Guard into your GitHub Actions workflow, use the flatt-security/setup-takumi-guard-pypi GitHub Action. You can use it anonymously or linked to an organization.

Anonymous Mode​

If you don't have a Shisho Cloud account yet, you can still use Takumi Guard in CI for package blocking. Omit the bot-id input:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: flatt-security/setup-takumi-guard-pypi@v1
        # No bot-id — anonymous mode, blocking only

      - run: pip install -r requirements.txt
      - run: pytest

In anonymous mode, the action only configures the index URL. Blocked packages are still rejected with a 403 error, but download tracking and breach notifications are not available.

With Shisho Cloud Organization​

Linking to a Shisho Cloud organization enables organization-level download tracking and breach notifications (via webhook). No long-lived secrets need to be stored in your CI environment. Authentication is performed securely by exchanging a GitHub OIDC token for a short-lived access token via the Shisho Cloud STS service.

Prerequisites:

  1. A bot identity registered in Shisho Cloud. Copy the Bot ID from the registry settings page in the Shisho Cloud console.
  2. The id-token: write and contents: read permissions in your workflow job.

Step 1: Add the action to your workflow

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Required for OIDC token exchange
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: flatt-security/setup-takumi-guard-pypi@v1
        with:
          bot-id: "BT01EXAMPLE..." # Copy from Shisho Cloud console

      - run: pip install -r requirements.txt
      - run: pytest

The action handles the full OIDC exchange automatically:

  1. Requests a GitHub OIDC token
  2. Exchanges it for a short-lived Takumi Guard access token via the STS service
  3. Configures pip to use the Takumi Guard index with that token
info

The Bot ID is not a secret — it is a public reference key used to look up the allowlist during token exchange. You can commit it directly in your workflow file. The Shisho Cloud console provides a ready-to-copy workflow snippet with the Bot ID pre-filled.

The access token expires after 30 minutes by default (configurable up to 24 hours via the expires-in input).

Action Inputs Reference​

InputRequiredDefaultDescription
bot-idNo—Bot ID from Shisho Cloud. Omit for anonymous blocking-only mode.
set-index-urlNotrueSet to false if you manage pip.conf yourself and only need the auth token.
registry-urlNohttps://pypi.flatt.techCustom registry URL. Override only if directed by Shisho Cloud support.
expires-inNo1800Access token lifetime in seconds. Maximum 86400 (24 hours).

For the full list of inputs and outputs, see the action repository.

Using with Private Packages​

Takumi Guard is a read-only security proxy for public PyPI packages. If your project depends on private packages, you can use --extra-index-url to fetch private packages from a separate index while routing public packages through Takumi Guard.

Extra Index URL​

Configure Takumi Guard as the primary index and your private index as an extra source. In pip.conf:

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

Or pass both on the command line:

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

With this configuration, pip searches both indexes and installs the best matching version.

warning

Private packages fetched from an extra index bypass Takumi Guard's security scanning. This is acceptable for your organization's own packages, but be aware that those packages will not be checked against the blocklist.

GitHub Actions with Private Packages​

When using the flatt-security/setup-takumi-guard-pypi action with private packages, let the action configure the Takumi Guard index as usual and add your private index via 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..."

      # Add your private index as an extra source
      - 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 is a read-only security proxy for package installs. Publishing packages is not affected because twine upload and similar tools communicate directly with https://upload.pypi.org/ (or your configured upload endpoint), not through the index URL.

twine upload dist/*

No changes to your publishing workflow are needed.

Uninstall​

To stop using Takumi Guard, revert your index URL settings to the default PyPI index.

Local Environment​

pip​

Remove the Takumi Guard lines from your pip.conf:

# Remove the following lines
[global]
index-url = https://token:tg_xxxxxx@pypi.flatt.tech/simple/

If you set the index URL via an environment variable, unset it:

unset PIP_INDEX_URL

uv​

If you set the environment variable, unset it:

unset UV_DEFAULT_INDEX

poetry​

If you added a poetry source, remove it. The source is a per-project setting, so run this in every repository where it was added:

poetry source remove takumi-guard

If you configured a poetry credential, remove it as well. This is a user-level setting, so run it once per machine:

poetry config --unset http-basic.takumi-guard

GitHub Actions​

Remove the flatt-security/setup-takumi-guard-pypi step from your workflow file:

# Remove the following step
- uses: flatt-security/setup-takumi-guard-pypi@v1
  with:
    bot-id: "BT01EXAMPLE..."
info

Once the index URL setting is removed, pip install will access the public PyPI index directly. No lockfile changes are required.

Revoking Org User Tokens​

If you are using org user tokens (tg_org_…), revoke them from Guard > Tokens in Shisho Cloud console in addition to updating your package manager configuration. Active tokens continue to be billed. See Pricing for details.

Quick Reference​

Minimum required configuration for each package-manager × usage-tier combination. Replace tg_anon_xxxxxx / tg_org_xxxxxx with your actual token.

pip​

Anonymous

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

Anonymous (email-verified)

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

Organization

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

uv​

uv does not read pip config or PIP_INDEX_URL. You can either set UV_DEFAULT_INDEX in your shell profile (.bashrc / .zshrc etc.), or persist the configuration in uv.toml.

Via environment variable​

Anonymous

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

Anonymous (email-verified)

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

Organization

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

Via uv.toml​

User-level config goes in ~/.config/uv/uv.toml. Project-level config goes in uv.toml or in the [[tool.uv.index]] section of pyproject.toml.

Anonymous (~/.config/uv/uv.toml)

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

Anonymous (email-verified) / Organization (~/.config/uv/uv.toml)

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

poetry​

Unlike pip / uv, poetry needs the source configured per project and the credential configured per machine. See About poetry for details.

Anonymous

Run the following command once in each repository that uses poetry, then commit and push the pyproject.toml change. No credential is needed.

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

Anonymous (email-verified) / Organization

Run the following command once in each repository that uses poetry, then commit and push the pyproject.toml change.

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

Additionally, configure the credential once per machine (per developer).

poetry config http-basic.takumi-guard token tg_xxxxxx # tg_anon_ or tg_org_
Caution when using poetry

Poetry itself, along with its plugins and installer, is commonly bootstrapped via curl ... | python-style external scripts. Takumi Guard protects packages fetched through public registries, but poetry's own install path and the poetry source mechanism sit outside Guard's protection. Pair this setup with explicit pinning where possible — pinning the installer version, mirroring it internally, and locking the poetry version in CI — so that adopting these third-party scripts does not silently widen your supply-chain attack surface.

Last updated on