pkgxray

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

npm パッケージまたは MCP サーバーを、インストールしたり接続したりする前に検査します。 固定ルールに基づき、根拠を引用して判定した SAFE、REVIEW、または BLOCK の結果が得られます。分析は静的に行われ、npm の依存関係をインストールせずに、お使いのマシン上で実行されます。MIT ライセンスの Acorn パーサーをバージョン固定して同梱しています。通常のスキャンではパッケージコードを実行しません。

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

_{実行例：guard は [email protected] を通過させた後、2024 年の @solana/web3.js 侵害をモデルにしたサンプルをブロックします。}

主な特徴

• npm の依存関係をインストールしません — バージョン固定された JavaScript パーサーを同梱し、Node 上でローカル分析します。
• 承認済みのバイト列をインストール — pkgxray install は npm のロックファイルをスキャンし、保留したアーカイブをスクリプト無効の状態でオフラインインストールして、生成されたファイルを検証します。
• 通常のスキャンではパッケージコードを実行しません — 隔離環境で tarball をバイト列として読み取ります。
• 固定ルールに基づく、根拠を引用した判定 — 各検出項目にはファイル名と根拠が示されます。モデルが判定することはないため、パッケージ内に仕込まれたテキストが判定を誘導することはありません。
• エージェント時代に向けて構築 — MCP サーバーへの接続前に確認し、エージェントが実行するインストールを制御して、稼働中の MCP トラフィックを再監査できます。
• 敵対的テストで明らかになった課題を公開 — 追加の合成ケース 200 件で、検出された攻撃と無害な対照ケースを追跡します。これは内部テストであり、独立した監査ではありません。
• リグレッションゲート — キャリブレーション用コーパスと敵対的コーパスを CI で実行し、過去の上位 1000 件の結果も比較用に利用できます。

1. クイックスタート · 2. スキャン対象と検出内容 · 3. 判定 · 4. 使用方法 · 5. 統合 · 6. 比較 · 7. ドキュメント

背景

AI コーディングアシスタントはパッケージをインストールし、MCP サーバーにすばやく接続しますが、事前にコードを読む人がいないこともよくあります。Sonatype によると、2025 年に監視対象のエコシステム全体で新たに 454,600 件を超える悪意のあるオープンソースパッケージが確認され、その 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 によるスキャンは静的なため、パッケージのコードは実行されません。次の 3 つの機能は異なります。MCP サーバーのツールを一覧表示するとサーバーが起動する場合があり、mcp-proxy はゲートの背後でサーバーを実行し、オプトインの canary はサンドボックス内でパッケージを実行して、その動作を確認します。canary によってパッケージが悪意のあるものだと確認できることはありますが、安全だと証明することはできません。境界の全容については、SECURITY.mdをご覧ください。

スキャンと検出の対象

スキャン対象 — pkgxray guard npm:name@version または pypi:name@version、 github:owner/repo、ローカルディレクトリ、2 つのエコシステムにわたるロックファイル全体（npm：package-lock.json、yarn.lock、pnpm-lock.yaml、package.json。PyPI： requirements.txt、poetry.lock、Pipfile.lock、pyproject.toml）、MCP サーバー、AI エージェントの拡張機能。

検出対象 — 認証情報の窃取（分割されたパス要素を含む）、クラウド インスタンスのメタデータやシークレットストアの収集、プロンプトインジェクション、 Unicode の偽装、Base64 ペイロードや第 2 段階のローダー、外部送信、永続化 （シェルプロファイル、OS スケジューラ、注入された CI/CD ワークフロー）、 自己削除型ドロッパー、レジストリワームの複製（インストール時の npm publish）、 npm のインストールフックおよび PyPI の setup.py によるインストール時の実行、 難読化された計算引数による実行、幻覚／スロップスクワットされた名前（レジストリで公開されたことのないバージョンをロックファイルが指定）、既知の CVE（ダウンロード前に OSV 経由で検出）、npm と GitHub の成果物の不一致、トロイの木馬化された更新（recheck）、MCP の 機能サーフェスの悪用。

網羅性の全容は脅威モデルをご覧ください。既知の盲点である、後からペイロードをダウンロードするパッケージについても記載しています。比較表はウェブサイトにあります。

判定

終了コードは固定されており、CI で扱いやすい値です：0 安全／許可 · 2 ブロック · 3 要確認。

使用方法

pkgxray guard npm:[email protected] [--format json]   # vet a package before install
pkgxray guard pypi:[email protected]                  # same, for a PyPI package (sdist staged + scanned)
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-all]               # also: yarn.lock, pnpm-lock.yaml, package.json
pkgxray audit requirements.txt [--deep]                # PyPI: also poetry.lock, Pipfile.lock, pyproject.toml
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

audit は、解決済みの依存関係を OSV と照合します。--deep を指定すると、ブロック対象の依存関係に対するソーススキャンが追加されます。--deep-all は、解決済みのすべての依存関係に対するソーススキャンを要求します。ディープスキャンが失敗した場合や、ソースの収集が不完全な場合は、すでに BLOCK でない限り REVIEW になります。 guard --deps は、直接依存関係の検出結果を判定に含めます。確認対象となるのは厳密なピン留めのみで、範囲指定やその他の未解決のソースは REVIEW のままです。Guard の出力には、完了、一部完了、無効、失敗したチェックが一覧表示されるため、合格判定でも実行されなかったチェックまで実施されたことにはなりません。 PyPI スキャンでは、ソース配布物のマニフェスト、脆弱性メタデータ、テキストレベルのインジェクションチェックが対象です。Python モジュールの動作を完全に分析したり、wheel を検査したりするものではありません。 Python ソースからは、unsupported-behavior の REVIEW 検出結果が追加されます。動作に関するカバレッジの不足は、allow-review でミュートしたり、判定を引き上げたりできません。ピン留めされたアーティファクトの承認は、明示的なオペレーターによる上書きとして残ります。リンクや特殊ファイルを含むアーカイブは拒否されます。

Node ベースのサーフェスでは、任意の .pkgxray.json でポリシーを調整できます。ブラウザー拡張機能は、指定されたエビデンスをエンジンのデフォルト設定でスキャンし、プロジェクト設定を読み取ることはできません。設定がない場合は、最も厳格な設定が適用されます。設定によって CVE を無視することはできず、緩和する設定はすべて出力されます。また、スキャンでエラーが発生した場合は、フェイルクローズとなり review になります。スキーマとルールについては、configuration.md · .pkgxray.example.json を参照してください。

インテグレーション

すべてのエントリーポイントで同じエンジンを使用します。「対応」とは、ベンダーが推奨するインテグレーションではなく、手順ガイドが公開されていることを意味します。

比較

npm audit と OSV-Scanner は公開済みの CVE を確認するものであり、pkgxray はこれらに取って代わるものではありません。併用してください。同じ領域のツールには Socket.dev、OpenSSF Package Analysis、Cisco MCP Scanner があり、これらもパッケージのコードが何をするかを分析します。機能の詳しい比較は、docs/comparison.md とウェブサイトをご覧ください。

エビデンス

過去のトップ 1000 件の実行結果と、その対象範囲および方法論は、pkgxray.ca/stats で引き続きご覧いただけます。これらの結果は、パーサーベースのフローエンジン導入前のものであり、今回の変更に伴う再実行は行われていません。現在のエンジンは、内部の合成キャリブレーション／チャレンジ用フィクスチャ 270 件すべてに合格しており、悪意のあるケースを SAFE と判定したり、良性のケースを BLOCK と判定したりすることはありません。悪意のあるケースの多くは REVIEW になります。これはリグレッションのエビデンスであり、実環境での検出率を推定するものではありません。

ドキュメント

ドキュメントの目次からご覧ください。

コントリビューション

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の説明に従って非公開で報告してください。リリースは来歴情報 （SLSA 証明）とともに npm に公開され、各リリースはテスト、調整ベンチマーク、 pkgxray 独自のサプライチェーンガードに合格する必要があります。