Pkgxray – 実行されるものではなく、インストールされるものを検査する
Pkgxray – inspect what gets installed, not what executes (github.com)
要約
Pkgxrayは、npmパッケージ、MCPサーバー、AIエージェントのインストール前に静的解析を行い、セキュリティリスクを評価するツールです。コードを実行せずにパッケージの内容を分析し、SAFE、REVIEW、BLOCKといった判定を証拠と共に提示します。これにより、サプライチェーン攻撃やプロンプトインジェクションなどの脅威を未然に防ぐことを目指しています。
全文翻訳
pkgxray — npmパッケージ、MCPサーバー、AIエージェントのプリインストールセキュリティ
[画像: pkgxray — インストール前にパッケージを分析する]
npmパッケージやMCPサーバーをインストールしたり接続したりする前に検査します。固定ルールに基づいて決定され、引用された証拠に裏付けられた SAFE、REVIEW、または BLOCK の判定が得られます。分析は静的であり、npm依存関係をインストールせずにローカルで実行されます。MITライセンスのAcornパーサーがバンドルされています。通常のスキャンではパッケージコードは実行されません。
[画像: npm version] [画像: npm downloads] [画像: tests] [画像: calibration benchmark] [画像: license: MIT]
ウェブサイト · ドキュメント · キャリブレーション · バグ報告
実際の実行例: guard は express@4.21.0 をクリアし、その後、2024年の@solana/web3.js侵害をモデルにしたサンプルをブロックします。
ハイライト
- npm依存関係のインストール不要 — バンドルされた固定JavaScriptパーサーによるローカルNode.js解析。
- 承認されたバイトをインストール —
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 pkgxray@1.0.5 guard npm:express@4.21.0
これは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 | 0 | 高または中リスクの兆候なし。デフォルトポリシーで昇格が許可されます。 |
REVIEW | 3 | 証拠が不完全、または特権的な機能について人間のレビューが必要です。 |
BLOCK | 2 | 高深刻度の引用された証拠 — 拒否または調査してください。 |
SAFE はパッケージが無害であることの証明ではありません。静的解析では、実行時にのみダウンロードされるペイロードを見ることはできません。脅威モデルを参照してください。
3. 提供された不活性フィクスチャでBLOCKを確認:
npx --yes pkgxray@1.0.5 --file examples/onboarding-malicious.json --format markdown
このフィクスチャは、分割文字列SSHキーの読み取りと漏洩をモデル化した不活性なソーステキストです。決して実行されません。これは、引用されたファイルと証拠とともに BLOCK(終了コード 2)を返します。
4. ワークフローに追加 — 再チェックとCI、MCP、Hookshotインストールゲート。
2つの実行モデル。 デフォルトの
guardとauditスキャンは静的であるため、パッケージコードは実行されません。3つのサーフェスは異なります:MCPサーバーのツールをリストするとそれが起動する可能性があり、mcp-proxyはゲートの後ろでそれを実行し、オプションの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 install-hookおよびPyPI setup.py のインストール時実行、難読化された計算引数実行、幻覚/スロップスワット名(レジストリが公開しなかったロックファイルピン)、既知のCVE(OSV経由、ダウンロード前)、npm↔GitHubアーティファクトの乖離、トロイの木馬化されたアップデート(recheck)、およびMCP機能サーフェス乱用。
完全なカバレッジマトリックスは脅威モデルにあり、既知の盲点(実行時にペイロードをダウンロードするパッケージ)も記載されています。並記比較表はウェブサイトにあります。
判定
| 判定 | あなたが行うべきこと |
|---|---|
SAFE | 報告されたチェック内でブロックする発見事項はありません。インストール前にカバレッジを確認してください。 |
REVIEW | プロモートする前に隔離されたコピーを検査してください。 |
BLOCK | インストールしないでください。すべての発見事項はファイルと証拠を明記します。 |
終了コードは安定しておりCIフレンドリーです:0 安全/許可 · 2 ブロック · 3 レビュー。
使用法
pkgxray guard npm:some-package@1.2.3 [--format json] # インストール前にパッケージを検証
pkgxray guard pypi:some-package@1.2.3 # 同様、PyPIパッケージの場合(sdistステージング+スキャン)
pkgxray mcp --package npm:some-mcp-server@1.4.2 npx some-mcp-server # MCPサーバーを検証;--recheckはラグプルを検出
pkgxray audit package-lock.json [--deep-all] # その他: yarn.lock, pnpm-lock.yaml, package.json
pkgxray audit requirements.txt [--deep] # PyPI: その他 poetry.lock, Pipfile.lock, pyproject.toml
pkgxray recheck package-lock.json # 定期実行:リグレッションがあった場合のみ非ゼロ
audit は解決された依存関係をOSVに対してチェックします。pkgxray はそれらを置き換えるものではありません。--deep はブロックされた依存関係のソーススキャンを追加します。--deep-all はすべての解決された依存関係のソーススキャンを要求します。失敗したディープスキャンと不完全なソース収集は、すでにBLOCKでない限りREVIEWを返します。guard --deps は直接依存関係の発見をその決定に含めます。チェックされるのは正確なピンのみで、範囲やその他の未解決のソースはREVIEWのままです。Guardの出力は完了したチェック、部分的なチェック、無効なチェック、失敗したチェックをリストするため、合格判定は実行されなかったチェックを意味しません。PyPIスキャンはソースディストリビューションマニフェスト、脆弱性メタデータ、およびテキストレベルのインジェクションチェックをカバーします。Pythonモジュールの完全な動作分析やホイールの検査は提供しません。Pythonソースはunsupported-behaviorのREVIEW発見事項を追加します。動作カバレッジのギャップはallow-reviewでミュートまたは昇格することはできません。ピン留めされたアーティファクトの承認は、依然として明示的なオペレーターオーバーライドです。リンクや特殊ファイルを含むアーカイブは拒否されます。
オプションの .pkgxray.json は、Nodeベースのサーフェスでポリシーを調整します。ブラウザ拡張機能は、エンジンデフォルトを使用して提供された証拠をスキャンし、プロジェクト構成を読み取ることはできません。構成がない場合は、最も厳格な設定が適用されます。構成はCVEを許可することは決してなく、すべての緩和策は印刷され、エラーが発生したスキャンは review に失敗します。スキーマとルール: configuration.md · .pkgxray.example.json。
インテグレーション
すべてのエントリーポイントの背後にある単一のエンジン。「Works with」は、ベンダー承認の統合ではなく、文書化されたセットアップガイドを意味します。
| 場所 | 機能 | ガイド |
|---|---|---|
| コーディングエージェント — Codex, Claude Code, Cursor, Windsurf | インストールをゲートし、エージェントに監査ツールを公開する | coding-agents.md |
| MCPクライアント | 接続前にサーバーを検証する。pkgxray自体をMCPサーバーとして実行する | mcp.md |
| GitHub Actions / CI | 依存関係がポリシーを超えた場合にビルドを失敗させる | github-actions.md |
| インストールゲート — Hookshot | エージェントがインストールしようとするすべてのパッケージで guard を実行する | examples/hookshot/ |
| ランタイムMCPゲート | ライブMCPサーバーをプロキシし、すべてのツール呼び出しをゲートする | mcp-proxy |
| 依存関係監視 | インストールされた依存関係を再検証し、スケジュールでアップグレードを事前検証する | recheck |
比較
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を生成します。これはリグレッション証拠であり、実際の検出率の推定値ではありません。
ドキュメント
| ドキュメント | 内容 |
|---|---|
| architecture.md · design.md | パイプライン、サーフェス、原則 |
| threat-model.md | スコープ、盲点、プロンプトインジェクションスタンス |
| mcp.md · mcp-registry.md | MCP検証、ランタイムプロキシ、レジストリエントリ |
| canary-threat-model.md | オプションの動作カナリア |
| configuration.md · reference.md | .pkgxray.json、深刻度ポリシー、recheck、キャッシュサーバー |
| benchmark.md · comparison.md | キャリブレーションと他ツールとの比較 |
| compatibility.md · json-schema.md | 1.0契約、--format jsonスキーマ |
ドキュメントインデックスから開始してください。
貢献
npm test # ゼロ依存のnode --testスイート
npm run benchmark # キャリブレーションコーパス: 精度/再現率 + 0-false-blockゲート
npm run validate:website # キャリブレーションページを再生成+検証
プルリクエストを歓迎します。CONTRIBUTING.mdとCode of Conductを最初に読んでください。脆弱性はSECURITY.mdの説明に従ってプライベートに報告してください。リリースはプロビナンス(SLSAアテステーション)付きでnpmに公開され、各リリースはテスト、キャリブレーションベンチマーク、およびpkgxray自体のサプライチェーンガードによってゲートされます。