メインコンテンツまでスキップ

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: メールアドレスを確認する

確認メール内のリンクをクリックするか、メールに記載されたトークンを使って確認エンドポイントを直接呼び出してください。

curl "https://npm.flatt.tech/api/v1/tokens/verify?token=<確認トークン>"

レスポンスに API キーが含まれています。

{
  "api_key": "tg_anon_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
警告

この 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 install @panda-guard/test-malicious

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

アンインストール​

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 レジストリに直接アクセスするようになります。ロックファイルの変更は不要です。

に最終更新