# Takumi Guard Packagist Support Released

Takumi Guard now supports **Packagist** alongside npm, PyPI, RubyGems, and Go.

PHP projects using **Composer** can now route `composer install` and `composer update` through Takumi Guard to block known-malicious packages before they reach your CI or development environment.

![Takumi Guard now supports Packagist](/docs/_md-assets/89f038953c-eyecatch.png)

## Overview {#overview}

Takumi Guard is a security proxy that sits between your package manager and the upstream registry. It checks every install request against GMO Flatt Security's threat database and blocks known-malicious packages.

With this release, the same protection that npm, Python, Ruby, and Go users have is now available for the PHP ecosystem:

- **[Package Blocking](/docs/t/guard/features/package-blocking)**: Malicious packages are blocked before any code is fetched
- **[Download Tracking](/docs/t/guard/features/installation-logs)**: Records install history for authenticated users
- **[Breach Notifications](/docs/t/guard/features/breach-notifications)**: Get notified if a package you installed is later flagged as malicious

The proxy speaks the standard [Composer repository protocol](https://getcomposer.org/doc/05-repositories.md#composer), the same mechanism used by Private Packagist and Toran Proxy — so no tooling changes are needed, just a one-time repository configuration.

## Getting Started {#getting-started}

The following works anonymously — no account or registration required. Add Takumi Guard as a Composer repository and disable the default Packagist.org so every package resolves through the proxy:

```bash
composer config --global repositories.takumi-guard composer https://packagist.flatt.tech
composer config --global repositories.packagist.org false
```

That's the whole setup. Blocking applies to `composer install` and `composer update` — **including installs from an existing `composer.lock`** (Composer 2.10+), so projects with a committed lock file are protected without any migration step.

:::info Optional: download tracking
To be notified about the exact versions you installed, run `composer update mirrors` once per project (identical to `composer update --lock` — it refreshes the lock file's download URLs without changing versions). This routes artifact downloads through the proxy and is **not required for blocking**.
:::

### GitHub Actions

Use the [`flatt-security/setup-takumi-guard-packagist`](https://github.com/flatt-security/setup-takumi-guard-packagist) action. Blocking-only requires no account or token — it configures the repository, and your existing `composer install` is protected (committed lock files included):

```yaml
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
      - run: composer install --no-interaction
```

For organization-level download tracking and [breach notifications](/docs/t/guard/features/breach-notifications), add a `bot-id` and grant `id-token: write` — the action does the OIDC → short-lived-token exchange automatically, no long-lived secret in CI. See [the Packagist quickstart](/docs/t/guard/quickstart/packagist#setup-ci) for the full pattern.

## Verify Your Setup {#verify}

Confirm blocking is active by trying to require our published test package, `flatt-security/hola-takumi-php` — a harmless package that is permanently on the blocklist:

```bash
composer require --dry-run flatt-security/hola-takumi-php
```

This must **fail** with a flagged-package error. If it resolves successfully, requests are not going through Takumi Guard — re-check `composer config --global --list | grep -E 'repositories|packagist'`. A package on the blocklist is rejected during `composer install`, `composer update`, and `composer require`. For details, see ["Verify Your Setup" in the Packagist quickstart](/docs/t/guard/quickstart/packagist#verify-setup).

## Email Registration Unlocks More (Free) {#email-registration}

Register your email to receive notifications if a package you installed is later found to be malicious. 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

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

**Step 2:** Get your API key from the welcome email. The key is included directly in the email body — no link to click.

**Step 3:** Store the token so Composer authenticates with it on every fetch

```bash
composer config --global --auth http-basic.packagist.flatt.tech token tg_anon_xxxxxx
```

Composer uses HTTP Basic auth keyed by host name — the username is ignored, and the token goes in the password field. Your installs are now tracked, and you will be notified if a downloaded package is later flagged.

## Private Packages {#private-packages}

Public packages go through Takumi Guard; private packages (e.g. a private GitHub repository) should bypass the proxy. Declare them as their own `vcs` or `path` repositories alongside the Guard repository, and Composer fetches each package from the repository that provides it. See the [Packagist quickstart](/docs/t/guard/quickstart/packagist#private-packages) for details.

## Organization-Wide Management, Too {#organization-setup}

Running Takumi Guard across your team? [Installation log search](/docs/t/guard/features/installation-logs), [centralized org user token management](/docs/t/guard/features/token-management), and [breach-notification webhooks](/docs/t/guard/features/breach-notifications) are all available for organization-wide operations. Get started with a Takumi subscription (Guard enabled):

1. Go to [https://cloud.shisho.dev/hello/takumi](https://cloud.shisho.dev/hello/takumi) and sign in
2. Register your organization and subscribe to Takumi
3. Navigate to **Guard** > **Settings** from the sidebar
4. Click "Enable" to activate Guard

![Guard settings page](/docs/_md-assets/59cbcd4424-ui-guard-settings.png)

Once Guard is enabled, configure your CI or developer machines using the [Packagist quickstart](/docs/t/guard/quickstart/packagist).

If you only need a [long-lived org token](/docs/t/guard/quickstart/packagist#setup-org-user-token) from GitHub Actions, **no payment is required**. A payment screen appears during organization registration, but you can skip it — simply register your GitHub organization from the Guard page to receive an org token.