パッケージのブロック
Takumi Guard が悪性と判定したパッケージをリクエストすると、レジストリは 403 Forbidden エラーを返します。これはすべての認証ティアに適用されます。ブロックは常に有効です。
npm ERR! 403 Forbidden - GET https://npm.flatt.tech/test-blocked-pkg/-/test-blocked-pkg-1.0.0.tgz
npm はインストール失敗として報告します。パッケージの tarball はダウンロードされません。
ブロックリストのチェックはリクエストされた特定のバージョンに対して適用されます。後続のバージョンがクリーンであれば、そのバージョンを指定してインストールできます。
リクエストの流れ
Takumi Guard は、npm クライアントと公開 npm レジストリの間に位置する透過プロキシとして動作します。npm クライアントが npm install を実行すると、リクエストはメタデータの取得と tarball のダウンロードの 2 段階で処理されます。
tarball 自 体は Takumi Guard を経由せず、クライアントが公開 npm レジストリから直接ダウンロードします。これにより、プロキシの帯域消費を抑えつつ、ブロックチェックを確実に適用しています。
tarball URL の書き換え
メタデータ内の tarball ダウンロード URL は Takumi Guard 経由に書き換えられます。これにより、ロックファイルに registry.npmjs.org の URL が直接記載されていても、以降のインストールは Takumi Guard を通るようになります。
パッケージマネージャーとの互換性
Takumi Guard は標準的な npm レジストリ API に準拠しているため、npm・pnpm・yarn のいずれからも利用できます。既存のロックファイルを変更する必要はありません。パッケージマネージャーはレジストリ URL ではなくインテグリティハッシュでパッケージを検証するため、レジストリの切り替えによる整合性の問題は発生しません。
認証
Takumi Guard は、リクエストに含まれる認証トークンに応じて動作を切り替えます。
| トークンの種類 | 認証方式 | ダウンロード追跡 |
|---|---|---|
| なし（匿名） | 不要 | なし |
| メール認証トークン | .npmrc の _authToken | トークン単位 |
| STS アクセストークン | OIDC 交換（CI 連携参照） | Bot 単位（GitHub リポジトリ・ワークフロー情報付き） |
認証トークンの有無に関わらず、ブロックリストによるパッケージブロックは常に有効です。
ブロックの基準
Takumi Guard のブロックリストは、GMO Flatt Security のセキュリティリサーチチームが独自に調査・収集した情報をもとに構築されています。具体的には、以下のようなパッケージがブロック対象となります。
- マルウェア:インストール時や実行時に悪意ある動作（情報窃取、バックドアの設置など）を行うパッケージ
- タイポスクワッティング:人気パッケージに酷似した名前を持ち、ユーザーの入力ミスを狙って悪意あるコードを配布するパッケージ
- 侵害済みパッケージ:正規のパッケージがアカウント乗っ取りなどにより侵害され、悪意あるコードが混入されたバージョン
npm エコシステムにおいては、npm レジストリがパッケージの新規公開・更新をリアルタイムに配信する変更フィード（Replicate API）を継続的に監視し、公開直後のパッケージを即座に取得しています。取得したパッケージはリサーチチームが構築した 分析パイプラインにかけられ、悪意ある挙動の有無が判定されます。この仕組みにより、公開されているアドバイザリデータベースだけでは検出できないゼロデイの悪意あるパッケージにも対応できます。
ブロックリストは随時更新されるため、新たに発見された脅威にも迅速に対応します。
セットアップの確認
Takumi Guard が正しく動作していることを確認するには、テスト用のブロック済みパッケージをインストールしてみてください。
npm install @panda-guard/test-malicious
このパッケージはブロックリストに常時登録されています。Takumi Guard が正しく設定されていれば、npm は 403 Forbidden エラーを報告し、インストールは失敗します。確認後、package.json から安全に削除できます。