npm

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

Anonymous Usage

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

Add the registry to your project's .npmrc:

registry=https://npm.flatt.tech/

Or set it globally:

npm config set registry https://npm.flatt.tech/

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

Package Manager Compatibility

Takumi Guard works with npm, pnpm, and yarn. All three read the registry setting from .npmrc. No lockfile migration is needed — existing lockfiles continue to work because package managers verify packages by integrity hash, not by registry URL.

For pnpm, you can also set it via:

pnpm config set registry https://npm.flatt.tech/

For yarn (v1), the .npmrc setting is respected. For yarn berry (v2+), add to .yarnrc.yml:

npmRegistryServer: "https://npm.flatt.tech/"

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.

Step 1: Register your email

curl -X POST https://npm.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 verification email within a few seconds.

Step 2: Verify your email

Click the link in the verification email, or call the verification endpoint directly with the token from the email:

curl "https://npm.flatt.tech/api/v1/tokens/verify?token=<verification-token>"

The response contains your API key:

{
  "api_key": "tg_anon_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

warning

Save this key immediately — it is shown once and cannot be retrieved again. If you lose it, see Rotating Your Token.

Step 3: Configure npm

Add both lines to your project's .npmrc:

registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_anon_xxxxxx

Or configure via the CLI:

npm config set registry https://npm.flatt.tech/
npm config set //npm.flatt.tech/:_authToken tg_anon_xxxxxx

Your npm install commands now authenticate with your token, enabling download tracking and breach notifications.

GitHub Actions

To integrate Takumi Guard into your GitHub Actions workflow, use the flatt-security/setup-takumi-guard-npm 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-npm@v1
        # No bot-id — anonymous mode, blocking only

      - run: npm install
      - run: npm test

In anonymous mode, the action only configures the registry 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 permission 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
    steps:
      - uses: actions/checkout@v4

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

      - run: npm install
      - run: npm test

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 npm to use the Takumi Guard registry 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

Input	Required	Default	Description
bot-id	No	—	Bot ID from Shisho Cloud. Omit for anonymous blocking-only mode.
set-registry	No	true	Set to false if you manage .npmrc yourself and only need the auth token.
registry-url	No	https://npm.flatt.tech/	Custom registry URL. Override only if directed by Shisho Cloud support.
expires-in	No	30m	Access token lifetime. Maximum 24h.

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

Verify Your Setup

You can confirm that Takumi Guard is working by attempting to install a known test package:

npm install @panda-guard/test-malicious

This package is permanently on the blocklist. If Takumi Guard is configured correctly, npm will report a 403 Forbidden error and the install will fail. You can safely remove it from your package.json afterward.

Uninstall

To stop using Takumi Guard, revert your registry settings to the public npm registry.

Local Environment

Remove the Takumi Guard lines from your project's .npmrc:

# Remove the following lines
registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_anon_xxxxxx

If you changed the global configuration, reset it to the default:

npm config delete registry
npm config delete //npm.flatt.tech/:_authToken

If you use pnpm or yarn berry, similarly remove the Takumi Guard registry URL from the respective config files (.npmrc or .yarnrc.yml).

GitHub Actions

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

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

info

Once the registry setting is removed, npm install will access the public npm registry directly. No lockfile changes are required.