npm

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

設定方法

匿名で利用する

認証なしで 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 ではなくインテグリティハッシュでパッケージを検証するため、既存のロックファイルはそのまま使用できます。

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

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

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

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

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

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

ステップ 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 キーと npm のセットアップ手順が表示されるページに遷移します。

警告

この API キーは一度しか表示されません。すぐに保存してください。紛失した場合はトークンのローテーションを参照してください。

ステップ 3: 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 コマンドはトークンで認証され、ダウンロード追跡と感染可能性の通知が有効になります。

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 権限が設定されていること。

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

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC トークン交換に必要
    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_anon_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
    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_anon_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 レジストリに直接アクセスするようになります。ロックファイルの変更は不要です。