npm

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

設定方法

Takumi Guard には3つの利用方法があります。

• 匿名で利用する：トークン不要。レジストリ URL を設定するだけでパッケージブロックが有効になります。
• ユーザー登録して利用する：メール認証トークン（tg_anon_…）を使い、ダウンロード追跡と侵害通知を有効にします。
• 組織ユーザートークンで利用する：組織ユーザートークン（tg_org_…）を使い、組織全体のインストール状況を追跡できます。

有料機能

組織ユーザートークンを利用するには、Guard を有効化した基本サブスクリプションが必要です。詳しくは料金と請求を参照してください。

匿名で利用する

認証なしで Takumi Guard のパッケージブロック機能を利用できます。レジストリ URL を設定するだけで、悪意あるパッケージのブロックが有効になります。ダウンロード追跡や感染可能性の通知は利用できませんが、最も手軽に導入できる方法です。

プロジェクトの .npmrc にレジストリを追加してください。

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

またはグローバルに設定します。

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

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

パッケージマネージャーの互換性

Takumi Guard は npm、pnpm、yarn に対応しています。いずれも .npmrc の registry 設定を読み取ります。切り替え時のロックファイルの移行は不要です。パッケージマネージャーはレジストリ URL ではなくインテグリティハッシュでパッケージを検証するため、既存のロックファイルはそのまま使用できます。

なお、npm v11.15.0 以降および yarn v1 では、Takumi Guard の設定中に追加・更新されたロックファイルのエントリの resolved フィールドに、Takumi Guard のレジストリ URL（npm.flatt.tech）が記録されます。これは npm のサプライチェーンチェックとの互換性のために必要な挙動です。詳細はリリースノートを参照してください。pnpm はロックファイルにレジストリ URL を記録しません。

pnpm の場合は以下でも設定できます。

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

yarn (v1) の場合、.npmrc の設定がそのまま反映されます。yarn berry (v2+) の場合は .yarnrc.yml に追加してください。

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

ユーザー登録して利用する

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

別のエコシステムで tg_anon_ トークンを取得済みの場合

お持ちの tg_anon_ トークンは、そのまま npm / PyPI / RubyGems / Go モジュールいずれのエコシステムでも利用できます。再登録は不要で、下記の ステップ 3 から進めてください。

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

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

language フィールドは省略可能で、デフォルトは "en"（英語）です。"ja" を指定すると、確認メールや感染可能性の通知を含むすべてのメールが日本語で届きます。この設定はトークンに保存され、以降のメールすべてに適用されます。

数秒以内にウェルカムメールが届きます。

ステップ 2: メールに記載された API キーを確認する

API キーはウェルカムメールに直接記載されています。リンクをクリックする手順は不要で、キーはすぐに使用できます。

警告

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

ステップ 3: npm を設定する

入手した tg_anon_… トークンを使って npm を設定します。プロジェクトの .npmrc に以下の 2 行を追加してください。

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

または CLI で設定します。

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

以降の npm install コマンドはトークンで認証され、ダウンロード追跡と感染可能性の通知が有効になります。

組織ユーザートークンで利用する

組織ユーザートークン（tg_org_…）は Takumi / Shisho Cloud コンソールから発行するか、ボットが Guard API を利用して発行できます。発行方法の詳細はトークンの管理をご参照ください。

別のエコシステムで tg_org_ トークンを発行済みの場合

1 つの tg_org_ トークンは、Takumi Guard の全エコシステム（npm / PyPI / RubyGems / Go モジュール）で利用できます。再発行は不要で、お持ちのトークンをそのまま npm の設定に使用してください。

トークンを入手したら、プロジェクトの .npmrc に以下の 2 行を追加してください。

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

または CLI で設定します。

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

以降の npm install コマンドは組織ユーザートークンで認証され、組織内のダウンロード追跡 や、組織宛の感染可能性の通知（Slack・Webhook）が有効になります。

GitHub Actions で利用する

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

匿名で利用する

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

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

      - uses: flatt-security/setup-takumi-guard-npm@v1
        # bot-id なし（匿名モード、ブロックのみ）

      - run: npm install
      - run: npm test

匿名モードでは、Action はレジストリ URL の設定のみを行います。ブロック済みパッケージは引き続き 403 エラーで拒否されますが、ダウンロード追跡と感染可能性の通知は利用できません。

組織に紐づけて利用する

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

前提条件:

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC トークン交換に必要
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: flatt-security/setup-takumi-guard-npm@v1
        with:
          bot-id: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー

      - run: npm install
      - run: npm test

Action は OIDC 交換をすべて自動で処理します。

1. GitHub の OIDC トークンをリクエストする
2. STS サービスを通じて Takumi Guard の短命なアクセストークンと交換する
3. そのトークンを使用して npm を Takumi Guard レジストリに向けるよう設定する

info

Bot ID はシークレットではありません。トークン交換時にトラスト条件を検索するための公開参照キーです。ワークフローファイルに直接コミットできます。Shisho Cloud コンソールには Bot ID があらかじめ入力された、コピーしてすぐ使えるワークフローのスニペットが用意されています。

アクセストークンのデフォルト有効期限は 30 分です（expires-in 入力で最大 24 時間まで設定可能です）。

参考：Action 入力パラメータ

入力	必須	デフォルト	説明
bot-id	いいえ	(なし)	Shisho Cloud の Bot ID。匿名ブロックモードの場合は省略します。
set-registry	いいえ	true	.npmrc を自分で管理し、認証トークンのみ必要な場合は false に設定します。
registry-url	いいえ	https://npm.flatt.tech/	カスタムレジストリ URL。Shisho Cloud サポートから指示された場合のみ変更します。
expires-in	いいえ	30m	アクセストークンの有効期間。最大 24h。

すべての入力と出力の一覧は Action リポジトリ を参照してください。

プライベートパッケージとの併用

Takumi Guard は公開 npm パッケージ向けの読み取り専用セキュリティプロキシです。プロジェクトがプライベートパッケージに依存している場合は、プライベートパッケージが Takumi Guard を経由せず、直接レジストリから取得されるように .npmrc を設定する必要があります。

スコープ付きプライベートパッケージ

npm や pnpm はスコープごとのレジストリルーティングに対応しています。.npmrc にスコープ付きのレジストリ設定を追加することで、プライベートパッケージをそれぞれのレジストリから直接取得しつつ、公開パッケージは引き続き Takumi Guard 経由でスキャンできます。

たとえば、@your-company スコープのプライベートパッケージを npmjs.org で管理している場合は、以下のように設定してください。

# 公開パッケージ → Takumi Guard でスキャン
registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_xxxxxx

# プライベートパッケージ → Takumi Guard をバイパスし、直接取得
@your-company:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

複数のプライベートスコープがある場合は、スコープごとに行を追加します。

@your-company:registry=https://registry.npmjs.org/
@your-other-scope:registry=https://registry.npmjs.org/

プライベートパッケージが GitHub Packages や Artifactory など別のレジストリにホストされている場合は、そのレジストリを指定してください。

@your-company:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

この設定により、パッケージマネージャーは以下のようにリクエストをルーティングします。

• npm install lodash → Takumi Guard 経由で取得（セキュリティスキャン適用）
• npm install @your-company/private-sdk → プライベートレジストリから直接取得（Takumi Guard をバイパス）

警告

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

スコープなしプライベートパッケージ

npm や pnpm はスコープ単位のレジストリルーティングのみに対応しており、パッケージ単位のルーティングには対応していません。@scope/ プレフィックスのないスコープなしプライベートパッケージを使用している場合、上記の .npmrc による回避策は適用できません。

この場合は、プライベートパッケージをスコープ付きの名前に移行することを推奨します（例: private-utils → @your-company/private-utils）。スコープ付きパッケージは、npm が組織向けパッケージとして推奨する標準的なアプローチです。

GitHub Actions でのプライベートパッケージの利用

flatt-security/setup-takumi-guard-npm Action をプライベートパッケージと併用する場合は、set-registry を false に設定し、.npmrc を手動で管理してください。

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

      - uses: flatt-security/setup-takumi-guard-npm@v1
        with:
          bot-id: "BT01EXAMPLE..."
          set-registry: false # .npmrc を手動管理

      # レジストリを手動で設定
      - run: |
          echo "registry=https://npm.flatt.tech/" >> .npmrc
          echo "//npm.flatt.tech/:_authToken=${{ steps.guard.outputs.token }}" >> .npmrc
          echo "@your-company:registry=https://registry.npmjs.org/" >> .npmrc
          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" >> .npmrc

      - run: npm install
      - run: npm test

セットアップの確認

Takumi Guard が正しく動作していることを確認するには、テスト用のブロック済みパッケージをインストールしてみてください。

npm install @panda-guard/test-malicious

このパッケージはブロックリストに常時登録されています。Takumi Guard が正しく設定されていれば、npm は 403 Forbidden エラーを報告し、インストールは失敗します。確認後、package.json から安全に削除できます。

パッケージの公開とログイン

Takumi Guard は読み取り専用のセキュリティプロキシです。npm login、npm publish、npm adduser などの書き込み操作はプロキシ経由では実行できません。これらの操作を行う際は、対象のレジストリを直接指定してください。

npm login --registry=https://registry.npmjs.org/
npm publish --registry=https://registry.npmjs.org/

Takumi Guard をグローバルレジストリに設定している場合でも、公開時には必ず --registry フラグを指定して、コマンドが正しいレジストリに送信されるようにしてください。

アンインストール

Takumi Guard の利用を停止するには、レジストリ設定を公開 npm レジストリに戻してください。

ローカル環境

プロジェクトの .npmrc から Takumi Guard 関連の行を削除します。

# 以下の行を削除
registry=https://npm.flatt.tech/
//npm.flatt.tech/:_authToken=tg_xxxxxx

グローバル設定を変更していた場合は、以下のコマンドでデフォルトに戻します。

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

pnpm や yarn berry を使用している場合も同様に、それぞれの設定ファイル（.npmrc または .yarnrc.yml）から Takumi Guard のレジストリ URL を削除してください。

GitHub Actions

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

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

info

レジストリ設定を削除すると、npm install は公開 npm レジストリに直接アクセスするようになります。ロックファイルの resolved フィールドに npm.flatt.tech の URL が記録されている場合（npm v11.15.0 以降または yarn v1 でインストールした場合）は、ロックファイルを削除して npm install を再実行するなどして再生成し、以降のインストールが Takumi Guard を参照しないようにしてください。

組織ユーザートークンの失効

組織ユーザートークン（tg_org_…）を使用している場合は、パッケージマネージャーの設定変更に加えて、Takumi / Shisho Cloud コンソールの Guard > トークン からトークンを失効させてください。有効なトークンが残っている限り課金対象となります。詳細は料金を参照してください。

クイックリファレンス

パッケージマネージャーと利用ティアの組み合わせごとに、最低限必要な設定をまとめます。tg_anon_xxxxxx / tg_org_xxxxxx は実際のトークンに置き換えてください。

npm

匿名

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

匿名（メール認証）

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

組織

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

pnpm

匿名

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

匿名（メール認証）

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

設定後、プロジェクトの .npmrc に以下を追記してください。

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

組織

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

設定後、プロジェクトの .npmrc に以下を追記してください。

//npm.flatt.tech/:_authToken=tg_org_xxxxxx

yarn (v1)

.npmrc の設定をそのまま読み取るため、npm と同じ手順で設定できます。

yarn berry (v2+)

.yarnrc.yml を編集します。

匿名

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

匿名（メール認証） / 組織

npmRegistryServer: "https://npm.flatt.tech/"
npmRegistries:
  "https://npm.flatt.tech/":
    npmAuthToken: "tg_xxxxxx" # tg_anon_ または tg_org_