<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — インストール前にパッケージを分析" width="820"> # pkgxray — npmパッケージ、MCPサーバー、AIエージェント向けのインストール前セキュリティ npmパッケージまたはMCPサーバーをインストールまたは接続する**前に**検査し、決定的でエビデンスに裏付けられた`SAFE`、`REVIEW`、`BLOCK`の判定を取得します。ローカルで動作する依存関係ゼロの静的解析 — 通常のスキャンではパッケージコードを実行しません。 [](https://www.npmjs.com/package/pkgxray) [](https://www.npmjs.com/package/pkgxray) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-test.yml) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-benchmark.yml) [](LICENSE) [**ウェブサイト**](https://pkgxray.ca) · [**ドキュメント**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**キャリブレーション**](https://pkgxray.ca/stats) · [**バグ報告**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="pkgxray guardが[email protected]をSAFE A+判定でクリアし、その後トロイの木馬化されたサンプルをBLOCK F判定とHIGHの認証情報アクセス検出でブロックする様子" width="820"> <sub>実際の実行例: <code>guard</code> が <code>[email protected]</code> をクリアし、その後、2024年の <code>@solana/web3.js</code> 侵害をモデルにしたサンプルをブロックします。</sub> </div> ## 主な特長 - **ランタイム依存関係ゼロ** — 純粋なNodeで、完全に手元のマシン上で動作します(静的パス約25ms)。 - **通常のスキャンではパッケージコードを実行しません** — tarballは隔離領域でバイト列として読み取られます。 - **決定的で引用付きの判定** — すべての検出結果はファイル名とエビデンスを明示します。判定経路にLLMを含まないため、注入されたテキストで結果を誘導できません。 - **エージェント時代に向けて設計** — 接続前にMCPサーバーを検査し、エージェントが実行するインストールをゲートし、稼働中のMCPトラフィックを再監査します。 - **キャリブレーション済みで回帰ゲート付き** — ダウンロード数上位1000パッケージでヒューリスティックによる誤ブロックがゼロであることをCIで強制しています。 > **[1. クイックスタート](#quick-start)** · [2. スキャン対象と検出内容](#what-it-scans--detects) · [3. 判定](#verdicts) · [4. 使い方](#usage) · [5. インテグレーション](#integrations) · [6. 他のツールとの比較](#how-it-compares) · [7. ドキュメント](#documentation) ## なぜ必要か AIコーディングアシスタントは、人間がコードを読むことなく、マシンスピードでパッケージをインストールし、MCPサーバーに接続します。Sonatypeは**2025年に監視対象エコシステム全体で45万4600件を超える悪意のあるオープンソースパッケージを新たに特定**し、その99%以上がnpm上のものでした([Sonatype](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware))。`npm audit`は*既知のCVEがあるか?*を問いかけます。pkgxrayはさらに*コードが実際に何をするのか*を問いかけます — 何かをインストールする前に。 ## クイックスタート **1. 既知の良性パッケージをスキャンする**(pkgxrayのインストールは不要): ```bash npx --yes [email protected] guard npm:[email protected] ``` 隔離領域にtarballをステージングし、静的チェックとサプライチェーンチェックを実行します — `npm install`もライフサイクルスクリプトもなく、パッケージコードは実行されません。 <details> <summary>出力例</summary> ```text 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) ``` </details> **2. 判定を確認する:** | Verdict | Exit | 意味 | |---|---:|---| | `SAFE` | `0` | 高リスクまたは中リスクの兆候なし。デフォルトポリシーで昇格が許可されます。 | | `REVIEW` | `3` | エビデンスが不完全、または特権的な機能に人間のレビューが必要です。 | | `BLOCK` | `2` | 高重大度の引用付きエビデンス — 拒否または調査してください。 | `SAFE`はパッケージが無害であることの証明ではありません。静的解析では、実行時にのみダウンロードされるペイロードを確認できないためです。[脅威モデル](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md)を参照してください。 **3. 同梱の不活性フィクスチャでBLOCKを確認する:** ```bash npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown ``` このフィクスチャは、分割文字列によるSSHキーの読み取りと外部送信をモデル化した不活性なソーステキストです — **実行されることは決してありません**。引用付きのファイルとエビデンスとともに`BLOCK`(終了コード`2`)を返します。 **4. ワークフローに組み込む** — [再チェックとCI](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck)、[MCP](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#the-pkgxray-mcp-server)、[Hookshotインストールゲート](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot)。 > **2つの実行モデル。** デフォルトの`guard`と`audit`スキャンは**静的**です — パッケージコードは実行されません。MCPサーバーの列挙ではサーバーが起動されることがあり、`mcp-proxy`はゲートの背後でサーバーを実行します。オプトインの[`canary`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md)は、サンドボックス内でパッケージを*実行*して挙動を確認する、意図的な唯一の例外です — 悪意の確認はできますが、パッケージの安全性を証明することはできません。完全な境界: [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope)。 ## スキャン対象と検出内容 **スキャン対象** — `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の機能面の悪用。 完全なカバレッジマトリクス — および既知の「後でダウンロード」という盲点 — は[脅威モデル](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md)に記載されています。横並びの比較表は[ウェブサイト](https://pkgxray.ca/#catches)にあります。 ## 判定 | Verdict | 対応 | |---|---| | `SAFE` | インストールしてよい。デフォルトでは`safe`のみが隔離領域から昇格します。 | | `REVIEW` | 昇格する前に隔離されたコピーを調査してください。 | | `BLOCK` | インストールしないでください。すべての検出結果がファイルとエビデンスを明示します。 | 終了コードは安定しておりCIフレンドリーです: **`0`** 安全/許可 · **`2`** ブロック · **`3`** レビュー。 ## 使い方 ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [`.pkgxray.example.json`](https://github.com/adamsjack711-ux/pkgxray/blob/main/.pkgxray.example.json)。 ## インテグレーション すべてのエントリーポイントの背後には単一のエンジンがあります。「Works with(連携対応)」は、ベンダー公認のインテグレーションではなく、セットアップガイドが文書化されていることを意味します。 | 場所 | 機能 | ガイド | |---|---|---| | コーディングエージェント — Codex、Claude Code、Cursor、Windsurf | インストールをゲートし、監査ツールをエージェントに公開する | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | MCPクライアント | 接続前にサーバーを検査し、pkgxray自身をMCPサーバーとして実行する | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | 依存関係がポリシーに違反したときにビルドを失敗させる | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | インストールゲート — Hookshot | エージェントがインストールしようとするすべてのパッケージに対して`guard`を実行する | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | ランタイムMCPゲート | 稼働中のMCPサーバーをプロキシし、すべてのツール呼び出しをゲートする | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | 依存関係モニタリング | インストール済みの依存関係を再検査し、アップグレードをスケジュールに従って事前検査する | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## 他のツールとの比較 pkgxrayは`npm audit` / OSV-Scannerの*代わり*ではなく、*併用*してください — それらは*「既知のCVEか?」*に答えます。同じ領域のツール(行動ベースのサプライチェーン検査 — Socket.dev、OpenSSF Package Analysis、Cisco MCP Scanner)との完全な機能比較は[docs/comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md)と[ウェブサイト](https://pkgxray.ca/#comparison)にあります。 ## エビデンス **ダウンロード数上位1000パッケージに対するヒューリスティック誤ブロックゼロのキャリブレーション**は、CIで回帰ゲートされています([範囲と方法論](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md))。公開された実行結果は[pkgxray.ca/stats](https://pkgxray.ca/stats)にあります。この主張は最もインストールされているセットに限定されたものであり、すべてのパッケージで誤ブロックがゼロであるという主張ではありません。 ## ドキュメント | ドキュメント | 内容 | |---|---| | [architecture.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/architecture.md) · [design.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design.md) | パイプライン、インターフェース、設計原則 | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | 範囲、盲点、プロンプトインジェクションへの姿勢 | | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) · [mcp-registry.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp-registry.md) | MCP検査、ランタイムプロキシ、レジストリ登録 | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | オプトインの行動観察型カナリア | | [configuration.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [reference.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md) | `.pkgxray.json`、重大度ポリシー、`recheck`、キャッシュサーバー | | [benchmark.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md) · [comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) | キャリブレーションと他ツールとの比較 | | [compatibility.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/compatibility.md) · [json-schema.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/json-schema.md) | 1.0契約、`--format json`スキーマ | [ドキュメントインデックス](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md)から始めてください。 ## コントリビューション ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md)と[行動規範](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md)をお読みください。脆弱性は[SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md)に従って非公開で報告してください。リリースは、テスト、キャリブレーションベンチマーク、pkgxray自身のサプライチェーンガードでゲートされ、証明情報(SLSAアテステーション)付きでnpmに公開されます。 <div align="center"> <sub>作者: <a href="https://github.com/adamsjack711-ux">Jack Adams-Lovell</a> · <a href="https://github.com/adamsjack711-ux/pkgxray/blob/main/LICENSE">MIT</a> · <a href="https://pkgxray.ca">pkgxray.ca</a></sub> </div>
