pkgxray — npmパッケージ、MCPサーバー、AIエージェント向けのインストール前セキュリティ

npmパッケージまたはMCPサーバーをインストールまたは接続する前に検査し、決定的でエビデンスに裏付けられたSAFE、REVIEW、BLOCKの判定を取得します。ローカルで動作する依存関係ゼロの静的解析 — 通常のスキャンではパッケージコードを実行しません。

ウェブサイト · ドキュメント · キャリブレーション · バグ報告

_{実際の実行例: guard が [email protected] をクリアし、その後、2024年の @solana/web3.js 侵害をモデルにしたサンプルをブロックします。}

主な特長

• ランタイム依存関係ゼロ — 純粋なNodeで、完全に手元のマシン上で動作します(静的パス約25ms)。
• 通常のスキャンではパッケージコードを実行しません — tarballは隔離領域でバイト列として読み取られます。
• 決定的で引用付きの判定 — すべての検出結果はファイル名とエビデンスを明示します。判定経路にLLMを含まないため、注入されたテキストで結果を誘導できません。
• エージェント時代に向けて設計 — 接続前にMCPサーバーを検査し、エージェントが実行するインストールをゲートし、稼働中のMCPトラフィックを再監査します。
• キャリブレーション済みで回帰ゲート付き — ダウンロード数上位1000パッケージでヒューリスティックによる誤ブロックがゼロであることをCIで強制しています。

1. クイックスタート · 2. スキャン対象と検出内容 · 3. 判定 · 4. 使い方 · 5. インテグレーション · 6. 他のツールとの比較 · 7. ドキュメント

なぜ必要か

AIコーディングアシスタントは、人間がコードを読むことなく、マシンスピードでパッケージをインストールし、MCPサーバーに接続します。Sonatypeは2025年に監視対象エコシステム全体で45万4600件を超える悪意のあるオープンソースパッケージを新たに特定し、その99%以上がnpm上のものでした(Sonatype)。npm auditは既知のCVEがあるか?を問いかけます。pkgxrayはさらにコードが実際に何をするのかを問いかけます — 何かをインストールする前に。

クイックスタート

1. 既知の良性パッケージをスキャンする(pkgxrayのインストールは不要):

npx --yes [email protected] guard npm:[email protected]

隔離領域にtarballをステージングし、静的チェックとサプライチェーンチェックを実行します — npm installもライフサイクルスクリプトもなく、パッケージコードは実行されません。

Decision: SAFE   Grade: A+ (99/100)
No high- or medium-risk indicators were found in the provided evidence.

Notes:
- INFO npm-vs-github-clean — npm tarball matches the linked GitHub repo at the
  published version. (15/16 files match GitHub @4.21.0)

2. 判定を確認する:

SAFEはパッケージが無害であることの証明ではありません。静的解析では、実行時にのみダウンロードされるペイロードを確認できないためです。脅威モデルを参照してください。

3. 同梱の不活性フィクスチャでBLOCKを確認する:

npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown

このフィクスチャは、分割文字列によるSSHキーの読み取りと外部送信をモデル化した不活性なソーステキストです — 実行されることは決してありません。引用付きのファイルとエビデンスとともにBLOCK(終了コード2)を返します。

4. ワークフローに組み込む — 再チェックとCI、MCP、Hookshotインストールゲート。

2つの実行モデル。 デフォルトのguardとauditスキャンは静的です — パッケージコードは実行されません。MCPサーバーの列挙ではサーバーが起動されることがあり、mcp-proxyはゲートの背後でサーバーを実行します。オプトインのcanaryは、サンドボックス内でパッケージを実行して挙動を確認する、意図的な唯一の例外です — 悪意の確認はできますが、パッケージの安全性を証明することはできません。完全な境界: SECURITY.md。

スキャン対象と検出内容

スキャン対象 — pkgxray guard npm:name@version、github:owner/repo、ローカルディレクトリ、ロックファイル全体(npm、yarn、pnpm)、MCPサーバー、AIエージェント拡張機能。

検出内容 — 認証情報の窃取(分割フラグメント経由のものを含む)、クラウドのインスタンスメタデータおよびシークレットストアの収集、プロンプトインジェクション、Unicodeスマイグリング、base64ペイロードとステージ2ローダー、外部送信、永続化(シェルプロファイル、OSスケジューラー、注入されたCI/CDワークフロー)、自己削除型ドロッパー、レジストリワーム複製(インストール時のnpm publish)、難読化された計算引数の実行、既知のCVE(ダウンロード前のOSV経由)、npm↔GitHubのアーティファクト不一致、トロイの木馬化された更新(recheck)、MCPの機能面の悪用。

完全なカバレッジマトリクス — および既知の「後でダウンロード」という盲点 — は脅威モデルに記載されています。横並びの比較表はウェブサイトにあります。

判定

終了コードは安定しておりCIフレンドリーです: 0 安全/許可 · 2 ブロック · 3 レビュー。

使い方

pkgxray guard npm:[email protected] [--format json]   # vet a package before install
pkgxray mcp --package npm:[email protected] npx some-mcp-server   # vet an MCP server; --recheck catches the rug-pull
pkgxray audit package-lock.json [--deep]               # also: yarn.lock, pnpm-lock.yaml, package.json
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

オプションの.pkgxray.json(すべてのインターフェースで読み込まれます)でポリシーを調整できます。設定ゼロの場合は最大の厳格さになります。CVEを許可で除外することは決してできず、緩和はすべて出力され、エラーが発生したスキャンはreviewにフェイルクローズします。スキーマと不変条件: configuration.md · .pkgxray.example.json。

インテグレーション

すべてのエントリーポイントの背後には単一のエンジンがあります。「Works with(連携対応)」は、ベンダー公認のインテグレーションではなく、セットアップガイドが文書化されていることを意味します。

他のツールとの比較

pkgxrayはnpm audit / OSV-Scannerの代わりではなく、併用してください — それらは*「既知のCVEか?」*に答えます。同じ領域のツール(行動ベースのサプライチェーン検査 — Socket.dev、OpenSSF Package Analysis、Cisco MCP Scanner)との完全な機能比較はdocs/comparison.mdとウェブサイトにあります。

エビデンス

ダウンロード数上位1000パッケージに対するヒューリスティック誤ブロックゼロのキャリブレーションは、CIで回帰ゲートされています(範囲と方法論)。公開された実行結果はpkgxray.ca/statsにあります。この主張は最もインストールされているセットに限定されたものであり、すべてのパッケージで誤ブロックがゼロであるという主張ではありません。

ドキュメント

ドキュメントインデックスから始めてください。

コントリビューション

npm test                 # zero-dep node --test suite
npm run benchmark        # calibration corpus: precision/recall + 0-false-block gate
npm run validate:website # regenerate + validate the calibration pages

プルリクエストは歓迎します — CONTRIBUTING.mdと行動規範をお読みください。脆弱性はSECURITY.mdに従って非公開で報告してください。リリースは、テスト、キャリブレーションベンチマーク、pkgxray自身のサプライチェーンガードでゲートされ、証明情報(SLSAアテステーション)付きでnpmに公開されます。