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

パッケージのブロック

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 を通るようになります。

この書き換えに伴い、ロックファイルに tarball URL を記録するパッケージマネージャー（npm v11.15.0 以降および yarn v1）では、新規追加・更新されたエントリに Takumi Guard のレジストリ URL（npm.flatt.tech）が記録されます。

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

Takumi Guard は標準的な npm レジストリ API に準拠しているため、npm・pnpm・yarn のいずれからも利用できます。切り替え時に既存のロックファイルを変更する必要はありません。パッケージマネージャーはレジストリ URL ではなくインテグリティハッシュでパッケージを検証するため、レジストリの切り替えによる整合性の問題は発生しません。なお、npm v11.15.0 以降および yarn v1 では、新規追加・更新されたロックファイルのエントリに Takumi Guard のレジストリ URL が記録されます。詳細は上記の tarball 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 から安全に削除できます。

に最終更新