Packagist

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 speaks the Composer repository protocol, so you can route composer install and composer update through it the same way you'd point at a Private Packagist or Toran Proxy mirror. This page covers setup for local development and CI.

Requires Composer 2.10 or newer

Blocking from an existing composer.lock relies on Composer's dependency-policy feature, added in Composer 2.10 (May 2026). On older Composer versions, blocking applies during composer update / composer require but not during composer install from a pre-existing lock file — upgrade Composer.

Setup

Takumi Guard offers three ways to get started for Composer:

• Anonymous — No token required. Configure the repository 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.

Paid Feature

Org user tokens require an active base subscription with Guard enabled. See Pricing & Billing for details.

Anonymous Usage

You can use Takumi Guard's package blocking without authentication. Add the proxy as a Composer repository and disable the default Packagist.org so every package resolves through Guard:

# Add the Guard proxy as a Composer repository (global config).
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech

# Disable the default packagist.org so packages are not loaded twice and
# cannot silently bypass the blocklist.
composer config --global repositories.packagist.org false

# Fail instead of bypassing Guard if Guard cannot be reached (Composer 2.10+)
composer config --global policy.ignore-unreachable false

Composer v2 mirrors packages it would otherwise fetch from packagist.org through Guard. Disabling packagist.org makes the routing explicit and prevents a direct fallback that would skip the blocklist. See details.

That's the whole setup — package blocking now applies to composer install and composer update, including installs from an existing composer.lock (Composer 2.10+).

Optional: enable download tracking

composer update mirrors

composer update mirrors is identical to composer update --lock: it rewrites the dist URLs in composer.lock to route artifact downloads through Guard without changing any package versions. This is not required for blocking — it only enables version-level download tracking so you can be notified if a package you installed is later flagged (see Email-Verified Access). Run it once per project; otherwise it happens automatically the next time you composer update.

Per-project instead of global

If you prefer not to change global config, add the same two repositories entries to a project's composer.json instead:

{
  "repositories": [
    { "type": "composer", "url": "https://packagist.flatt.tech" },
    { "packagist.org": false }
  ]
}

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 an org user token or email-verified token from using Takumi Guard with npm, PyPI, RubyGems, or Go, you don't need to register again — the same token works for Composer.

Step 1: Register your email

curl -X POST https://packagist.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://packagist.flatt.tech/api/v1/tokens/regenerate

Step 3: Configure Composer to send the token

Composer authenticates to repositories with HTTP Basic auth, keyed by host name. The username is ignored; the token goes in the password field.

# 1. Add the repository (if not already done)
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false

# 2. Store the token (written to your global auth.json)
composer config --global --auth http-basic.packagist.flatt.tech token tg_anon_xxxxxx

# 3. Fail instead of bypassing Guard if the token stops working (Composer 2.10+)
composer config --global policy.ignore-unreachable false

# 4. Route downloads through the proxy so installs are tracked under your token
#    (run once per project; refreshes lock URLs only, no version changes)
composer update mirrors

Composer now authenticates with your tg_anon_ token on every package fetch. With the lock file pointed at the proxy, your installs are tracked and breach notifications cover the exact versions you downloaded.

Org User Tokens

Org user tokens (tg_org_…) can be issued from the Takumi / 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, Composer). If you have already issued a token for another ecosystem, the same token can be used here.

Once you have a token, configure the repository and store the token. The final composer update mirrors is optional — it routes downloads through the proxy so installs are tracked under your token:

composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_org_xxxxxx
composer config --global policy.ignore-unreachable false

# Optional (enables install tracking; not required for blocking):
composer update mirrors

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

Why disable packagist.org?

Set the Guard proxy as your only public-package repository, and disable packagist.org.

If packagist.org remains enabled, Composer treats it as an equal repository and may resolve and download a package directly from packagist.org / GitHub, bypassing Guard's blocklist. Disabling it guarantees that every public package is resolved through Takumi Guard.

Your organization's own private packages should not be routed through this proxy — declare them as separate vcs or path repositories, as described in Using with Private Packages.

CI/CD

GitHub Actions

To integrate Takumi Guard into your GitHub Actions workflow, use the flatt-security/setup-takumi-guard-packagist GitHub Action. You can use it anonymously or linked to an organization. The action configures the repository and injects the token; your existing composer install is then protected — blocking applies to your committed lock file with no migration step. The action requires Composer 2.10 or later.

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: shivammathur/setup-php@v2
        with:
          php-version: "8.3"
          tools: composer:v2

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

      # Your existing install is now protected — blocked packages are rejected
      # even from a committed composer.lock (Composer 2.10+). No migration needed.
      - run: composer install --no-interaction

In anonymous mode, the action only configures the Composer repository. Blocked packages are rejected during composer install, 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.

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Required for OIDC token exchange
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.3"
          tools: composer:v2

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

      # Protected immediately — blocking covers your committed composer.lock.
      # (Add `composer update mirrors` before this if you want version-level
      # download tracking under your bot identity.)
      - run: composer install --no-interaction

The action handles the full OIDC exchange automatically:

1. Requests a GitHub OIDC token (with the registry host as audience)
2. Exchanges it for a short-lived Takumi Guard access token via the STS service
3. Configures the Composer repository and writes the token to COMPOSER_AUTH

info

The Bot ID is not a secret. It is a public identifier that specifies the bot to sign in as; authentication relies on verifying the OIDC token against the bot's trust conditions. 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). If authentication fails (invalid bot-id, missing OIDC permission, STS unreachable, etc.), the step exits with a clear error message — there is no silent fallback to anonymous mode.

Action Inputs Reference

Input	Required	Default	Description
bot-id	No	—	Bot ID from Shisho Cloud. Omit for anonymous blocking-only mode.
set-repository	No	true	Set to false if you manage the Composer repository yourself.
fail-closed	No	true	When true, composer install / update fail if the Guard proxy is unreachable or the access token is no longer valid. With false, Composer then downloads the packages in composer.lock from the source recorded there, such as GitHub, without going through Takumi Guard, so blocked packages are installed. Requires Composer 2.10+.
registry-url	No	https://packagist.flatt.tech	Custom registry URL. Override only if directed by Shisho Cloud support.
sts-url	No	https://sts.cloud.shisho.dev	STS service URL used for the OIDC → access-token exchange.
expires-in	No	1800 (seconds)	Access token lifetime in seconds. Maximum 86400 (24 hours).

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

GitLab CI/CD

In GitLab CI/CD, point Composer at Takumi Guard in the job's before_script. 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. Add the registry configuration to your job:

build:
  image: php:8.3-cli-bookworm
  before_script:
    # Install Composer
    - apt-get update -qq && apt-get install -y -qq git unzip
    - curl -fsSL https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

    # Use Takumi Guard for Composer
    - composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
    - composer config --global repositories.packagist.org false
    # Fail instead of bypassing Guard if Guard cannot be reached (Composer 2.10+)
    - composer config --global policy.ignore-unreachable false
  script:
    - composer install --no-interaction

In anonymous mode, blocked packages are still rejected, but download tracking and breach notifications are not available.

With Shisho Cloud Organization

To use Takumi Guard in GitLab CI/CD on GitLab.com, authenticate to Shisho Cloud as a bot using OIDC, then configure Composer with the access token. No long-lived secrets need to be stored in your CI environment, and as with GitHub Actions, package download history is recorded under your organization.

Prerequisites:

1. A bot in Shisho Cloud with a GitLab CI/CD trust condition for the target project. See Bot authentication for how to set up the trust condition. Also note the Bot ID of the bot.
2. A container image with curl and bash that can run the Linux (glibc) build of shishoctl for x86_64 or aarch64, such as the Debian-based official images (not the -slim variants). Alpine-based images are not supported. On arm64 runners, replace x86_64 with aarch64 in the shishoctl URL.

Add a job like the following to your .gitlab-ci.yml:

build:
  image: php:8.3-cli-bookworm
  id_tokens:
    ID_TOKEN:
      aud: https://gitlab.com
  variables:
    SHISHOCLOUD_BOT_ID: "BT01EXAMPLE..." # Copy from Shisho Cloud console
  before_script:
    # Install Composer
    - apt-get update -qq && apt-get install -y -qq git unzip
    - curl -fsSL https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

    # Install 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

    # Sign in (as bot) and take the access token
    - shishoctl auth signin:bot
      --bot ${SHISHOCLOUD_BOT_ID}
      <<< ${ID_TOKEN}
      --expires-in-minutes 30 # Default 30 (max 1440). Adjust to your job
    - export ACCESS_TOKEN="$(shishoctl auth print-access-token)"

    # Use the access token for Composer
    - composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
    - composer config --global repositories.packagist.org false
    - composer config --global --auth http-basic.packagist.flatt.tech token "$ACCESS_TOKEN"
    # Fail instead of bypassing Guard if the token stops working (Composer 2.10+)
    - composer config --global policy.ignore-unreachable false
  script:
    # Add `composer update mirrors` before this if you want version-level
    # download tracking under your bot identity.
    - composer install --no-interaction

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

Using with Private Packages

Takumi Guard is a read-only security proxy for public packages. If your project depends on private packages (e.g. a private GitHub repository or a private Packagist), declare them as their own repositories so they bypass Guard and are fetched directly:

{
  "repositories": [
    { "type": "composer", "url": "https://packagist.flatt.tech" },
    { "type": "vcs", "url": "https://github.com/your-org/private-lib" },
    { "packagist.org": false }
  ]
}

Composer resolves each package from the repository that provides it. Public packages flow through Takumi Guard; your vcs / path repositories are fetched directly using your existing Git credentials.

warning

Private packages routed directly via VCS bypass Takumi Guard's security scanning. This is acceptable for your organization's own packages, but be aware that those packages are not checked against the blocklist.

Verify Your Setup

To confirm that Composer is routing through Takumi Guard, inspect the configured repositories and watch a real fetch go through the proxy host:

# 1. Confirm the Guard repository is configured and packagist.org is disabled.
composer config --global --list | grep -E 'repositories|packagist'

# 2. Confirm blocking works. flatt-security/hola-takumi-php is a harmless test
#    package we publish that is permanently on the blocklist, so this must fail.
#    --dry-run resolves without writing to your project.
composer require --dry-run flatt-security/hola-takumi-php

The second command must fail — Composer reports that the package cannot be installed because it is flagged. If it instead resolves successfully, requests are not going through Takumi Guard (re-check step 1). A blocklisted package is rejected during composer install, composer update, and composer require (Composer 2.10+ enforces this even for installs from an existing lock file); a blocklisted version of an otherwise-allowed package is removed from resolution so Composer won't select it.

Uninstall

To stop using Takumi Guard, remove the repository configuration and re-resolve against the default Packagist.

Local Environment

# 1. Remove the Guard repository and re-enable packagist.org
composer config --global --unset repositories.takumi-guard
composer config --global --unset repositories.packagist.org

# 2. Remove the stored token and the setting that makes Composer fail instead of bypassing Guard
composer config --global --unset --auth http-basic.packagist.flatt.tech
composer config --global --unset policy.ignore-unreachable

# 3. Re-resolve each project's lock file against the default Packagist
composer update mirrors

CI/CD

GitHub Actions

Remove the Takumi Guard action from your workflow file:

# Remove the following step
- uses: flatt-security/setup-takumi-guard-packagist@v1

GitLab CI/CD

Remove the lines that configure Composer for Takumi Guard from before_script in your .gitlab-ci.yml. If you linked the job to an organization, also remove the shishoctl lines.

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 local config. Active tokens continue to be billed. See Pricing for details.

Quick Reference

Minimum configuration for each usage tier. Replace tg_anon_xxxxxx / tg_org_xxxxxx with your actual token. The composer config lines are the complete setup for blocking; the trailing composer update mirrors is optional and only enables download tracking (run once per project).

Anonymous

composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global policy.ignore-unreachable false
composer update mirrors  # optional: download tracking

Anonymous (email-verified)

composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_anon_xxxxxx
composer config --global policy.ignore-unreachable false
composer update mirrors  # optional: download tracking

Organization

composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
composer config --global --auth http-basic.packagist.flatt.tech token tg_org_xxxxxx
composer config --global policy.ignore-unreachable false
composer update mirrors  # optional: download tracking