ExactGround

ExactGround：存在しないパッケージをAIコーディングエージェントがインストールするのを防ぐ

ExactGroundは、AIコーディングエージェントが存在しないnpmまたはPyPIパッケージをインストールするのを防ぎます。また、ホスト型チェックでは、インストール済みの正確なバージョンに関数が存在するかどうかを確認できます。

無料のオープンソースガードは、Claude Code、Codex、Gemini CLI、Cursorでフックとして動作します。コマンドの実行前に、公開npmレジストリとPyPIに対して次の内容を確認します。

• 解析可能なnpm／pnpm／yarn／bun／npxおよびpip／uv／poetry／pdm／pipxのインストールコマンド。
• package.json、requirements*.txt、pyproject.tomlに追加された新しい依存関係。

幻覚によるパッケージ名（スロップスクワッティングの根本原因）、公開されたことのないバージョン、人気パッケージに似た新規または利用の少ないパッケージ、npmのセキュリティプレースホルダーをブロックします。依存関係はゼロで、ローカルで動作し、MITライセンスです。

脅威モデルを簡潔に説明すると： ExactGroundは、通常のインストールコマンドでエージェントがパッケージ名を幻覚したり、入力を間違えたりするのを防ぎます。これは協調的なガードレールであり、サンドボックスではありません。エージェントが意図的に回避しようとすれば（独自のスクリプトを作成する、フックが認識しないファイルを編集する、別の方法でコードを実行するなど）、回避できます。信頼できないエージェントを封じ込めるには、OSまたはコンテナーのサンドボックスを使用してください。

意図的に対象外としていること： ユーザー権限で動作するエージェントがコマンドを意図的に難読化する（プログラム名やファイルパスを実行時に組み立てる、独自のスクリプトを作成する、コマンドをエンコードする）と、このフックを含むフックベースのガードはどれも回避できます。ExactGroundは、認識している難読化パターンを拒否しますが、この種の回避をさらに追跡することはありません。敵対的と見なすエージェントは、OSサンドボックスかコンテナー内で、またはExactGroundの設定を書き換えられない別のOSユーザーとして実行してください。SECURITY.mdを参照してください。

検出できないもの：

• インラインスクリプト（node -e、python -c）、コマンド置換（$(...)）、eval／iex／Start-Process、-EncodedCommand内に隠されたインストールは確認できないため、フックはそれらを拒否し、通常のインストールコマンドを使うよう求めます。変数経由のパッケージマネージャー（n=npm; $n install x）、8.3形式の短縮名（NPM~1.EXE）、.cmd/.ps1サフィックス、フルパスは解決され、チェックされます。プログラム名を実行時に組み立てるもの（& ('np'+'m')、for %I in (npm) do ...）や、変数に格納したパッケージ名（npm install $p）は拒否されます。cmdのキャレット（np^m）は除去してからチェックします。リテラルのマネージャー名を使うループや呼び出し（ForEach-Object { npx eslint $_ }、& $python -m pip install requests）は通常どおり解析され、チェックされます。
• すべてのツール呼び出しを検査します。commandを含むツールはすべてシェルとして扱われ、読み取り専用でないすべてのツールについて、そのファイルパスがExactGround独自のポリシーファイルに照らしてチェックされます。エージェントの外部で実行されるもの（CI、cron、その他のプログラム）は検出されません。
• フックはガードレールであり、サンドボックスではありません。コードを実行する別の手段があるエージェントは、フックを回避できます（上記の脅威モデルを参照してください）。
• レジストリに接続できない場合、またはチェッカー自体が失敗した場合、フックはデフォルトで拒否します。

· ウェブサイト：https://alidaram99.github.io/exactground/ · ホスト型API：https://apify.com/dropin-apis/exactground-api

$ npx -y github:alidaram99/exactground#v0.1.5 check pypi:requests pypi:reqeusts pypi:huggingface-cli [email protected]
OK      pypi:requests
BLOCK   pypi:reqeusts — "reqeusts" does not exist on PyPI; did you mean "requests"? (it is 1 edit away)
BLOCK   pypi:huggingface-cli — "huggingface-cli" does not exist on PyPI
BLOCK   [email protected] — version 99.0.0 of "react" was never published (latest is 19.3.0)

これが重要な理由

• パッケージの幻覚はよく起こり、繰り返し発生します。 USENIX Security 2025 の研究 We Have a Package for You!（Spracklen ほか）では、16 個のモデルに 576,000 個のコードサンプルを書かせました。そこに含まれる 2.23 million 件のパッケージ推奨のうち、440,445 件（19.7%）は存在しないパッケージを挙げており、その名前は 205,474 種類に上りました。別のテストでは、幻覚が生じた 500 個のプロンプトをそれぞれ 10 回ずつ再実行したところ、幻覚として出力された名前の 43% が、10 回すべての実行で再び出力されました（論文）。
• スロップスクワッティングは、これを攻撃に利用します。誰かがその架空の名前でマルウェアを登録し、次に pip install <invented-name> を実行するエージェントがそれをインストールします（Wikipedia、CSA の調査ノート、2026）。上記の huggingface-cli は典型例です。モデルが実在する huggingface_hub[cli] に対して作り出す名前です。
• エージェントは人間の確認なしにインストールします。 CLAUDE.md や AGENTS.md に「パッケージを捏造しない」といったルールを書いても、それはモデルが無視する可能性のあるテキストにすぎません。特に、コンテキストが圧縮された後はその可能性が高くなります。フックは毎回実行されるコードです。

クイックスタート

Node.js 20 以降が必要です。インストールは不要です。

npx -y github:alidaram99/exactground#v0.1.5 check left-pad expresss pypi:numpy==1.26.4
npx -y github:alidaram99/exactground#v0.1.5 scan "npm i zod react-hook-formz && pip install -r requirements.txt"
npx -y github:alidaram99/exactground#v0.1.5 manifest package.json

フックには、タグ付きリリースのローカルチェックアウトを使用してください（より高速で、バージョンが固定され、フックの実行時に何もダウンロードされません）。

git clone --depth 1 --branch v0.1.5 https://github.com/alidaram99/exactground.git ~/tools/exactground

コーディングエージェントに追加する

exactground init <agent> は、チェックアウトへの絶対パスを含む正確な設定を出力します。--write は現在のプロジェクトに設定をマージし、既存のフックを保持します。

Claude Code（プラグイン）

claude plugin marketplace add alidaram99/exactground
claude plugin install exactground@exactground-marketplace

プラグインは Bash|Write|Edit|MultiEdit に対する PreToolUse フックを登録します。

• ブロックされたインストールは拒否され、その理由が Claude に表示されます。例：PyPI に「reqeusts」は存在しません。「requests」のことですか？
• 警告は許可され、コンテキストとして Claude に渡されます。

手動で設定する場合：node ~/tools/exactground/bin/exactground.mjs init claude --write。

Codex

codex plugin marketplace add alidaram99/exactground --ref v0.1.5

プラグインをインストールしたら、/hooks でフックを確認して信頼してください。Codex は信頼されたフックのみを実行します。手動で設定する場合、exactground init codex --write は .codex/hooks.json に Bash と apply_patch を対象とする PreToolUse を書き込みます。これにより、package.json、requirements.txt、pyproject.toml に依存関係を追加するパッチもチェックされます。

Gemini CLI（拡張機能）

gemini extensions install https://github.com/alidaram99/exactground --ref v0.1.5

拡張機能の BeforeTool フックは run_shell_command|write_file|replace を対象とします。手動で設定する場合、exactground init gemini --write は .gemini/settings.json に同じフックを追加します。

Cursor

exactground init cursor --write は .cursor/hooks.json に beforeShellExecution フックを追加します。Cursor はファイル編集が行われる前にそれをブロックできないため、代わりに ExactGround が後続の npm install／pip install／uv sync を検出します。引数なしのインストールでは、まだロックファイルに記載されていないマニフェスト内の依存関係をすべてチェックします。

チェック内容

状況	判定
名前が npm/PyPI に存在しない（npm i reacct-dom、pip install reqeusts）	ブロック。「もしかして」の候補を表示
固定バージョンが一度も公開されていない（[email protected]、numpy==9.9）	ブロック
npm のセキュリティ用プレースホルダー（0.0.1-security：マルウェアが削除された）	ブロック
上位 3,000 件のパッケージに類似し、公開から 180 日未満、または週間ダウンロード数が 500 未満	ブロック
古く、広く使用されている類似パッケージ	警告
公開から 30 日未満、週間ダウンロード数が 500 未満、非推奨、または取り下げ済み	警告
レジストリに接続できない	エージェントフックでは 拒否（フックのデフォルトは strict）。手動 CLI では --strict を指定しない限り警告
--index-url/--extra-index-url を使用中（プライベートパッケージの可能性あり）	見つからない名前のみ警告

確認対象：

• 直接インストール；
• npx/pnpm dlx/bunx/uvx の実行；
• ネストされた -r を含む pip install -r のファイル；
• 引数なしの npm install/yarn/pnpm install/uv sync/poetry install（ロックファイルにない依存関係）；
• package.json、requirements*.txt、pyproject.toml の Write/Edit；
• Codex の apply_patch。

bash -lc "…" でラップされたコマンドは、ラップを解除して処理します。

設定： プロジェクトのルートに、任意で .exactground.json を配置できます。

{ "allow": ["my-internal-lib", "pypi:corp-utils"], "privateScopes": ["@acme"], "newPackageDays": 30, "lowDownloads": 500 }

エージェントが独自の例外を承認することはできません。

• フックがプロジェクトの .exactground.json を適用するのは、ターミナルで あなたが exactground trust を実行した後だけです。これにより、プロジェクトの外にあるユーザー設定ディレクトリに、ファイルの SHA-256 が記録されます。
• その後ファイルを編集した場合は、再度承認が必要です。ユーザーレベルの config.json も同様に扱われます。exactground trust --user で承認してください。
• .exactground.json、承認情報、またはキャッシュを書き込むツール呼び出しは拒否されます。
• すべてのプロジェクトに適用する設定は、~/.config/exactground/config.json（Windows では %APPDATA%\exactground\config.json）に記述できます。

手動 CLI は、検索結果を ~/.cache/exactground に 24 時間キャッシュします。エージェントフックは常にレジストリを再確認するため、キャッシュだけに基づいてインストールを許可することはありません。

バージョンを指定した API チェック（ホステッド、チェックごとの従量課金）

ホステッド API のステータス： 2026-10-03 から Apify Store で公開中です。呼び出しには Apify API トークンが必要です（トークンなしのリクエストは HTTP 401 を返します）。

幻覚の多くは、実在するパッケージの誤用です。たとえば、React 18 プロジェクトでの useActionState の使用や、NumPy 2.0 で削除された後の numpy.asfarray の使用などです。ExactGround API は、公開済みのパッケージ自体を調べて、こうした疑問に回答します。npm は TypeScript コンパイラーで .d.ts を調べ、Python はコードを実行せずに wheel を静的解析します。これは MCP サーバーです。

claude mcp add --transport http exactground https://dropin-apis--exactground-api.apify.actor/mcp --header "Authorization: Bearer $APIFY_TOKEN"

ツール	価格
check_symbols	シンボル 1 件あたり $0.002
check_packages	パッケージ 1 件あたり $0.0005
check_diff	差分 1 件あたり $0.01（変更によって追加されたすべての import）

CLI から実行する場合：APIFY_TOKEN=… exactground api check_symbols '{"ecosystem":"pypi","package":"numpy","version":"2.1.0","symbols":["numpy.asfarray"]}'。

比較

ツール	機能	エージェント内での幻覚によるインストールを阻止しますか？	バージョン完全一致の API チェック？
ExactGround	エージェントフックでレジストリの実態とタイポスクワッティングの兆候を検出（無料）；API チェック（ホスト型）	はい。解析できるインストールコマンドとマニフェストの編集が対象です（Claude Code、Codex、Gemini CLI、Cursor のフック）	はい（ホスト型 API）
Socket Firewall	インストール時に確認済みのマルウェアをブロックするプロキシ	マルウェアはブロックします。存在しない名前はインストールに失敗するだけです（または確認されるまでは、新たに登録された偽装パッケージがインストールされます）	いいえ
Context7	バージョン固有のドキュメントをプロンプトに挿入します	いいえ。エージェントは引き続き名前を捏造する可能性があります	いいえ。はい／いいえを判定するチェックではなく、ドキュメントのテキストです
npm audit / pip-audit	インストール済みパッケージの既知の脆弱性を検出します	いいえ。インストール後に、実在するパッケージを対象に実行されます	いいえ
型チェッカー（tsc、pyright）	インストール後に、型付きコードの API を正確にチェックします	いいえ	はい。ただし、コードと環境が存在してからです

これらは併用できます。ExactGround はインストール前の低コストなゲートとして機能し、Socket と監査ツールが実在するパッケージのセキュリティをカバーします。

FAQ

Claude Code が幻覚で npm や PyPI のパッケージをインストールするのを防ぐには？

ExactGround の Claude Code プラグインをインストールしてください（上記の 2 つのコマンド）。その PreToolUse フックは、解析できる Bash のインストールコマンド、および package.json／requirements.txt／pyproject.toml の編集に含まれるパッケージ名をチェックし、名前が存在しない場合はツール呼び出しを拒否します。解析できないインストールも拒否します。

スロップスクワッティングとは何ですか？

AI モデルが幻覚で生成するパッケージ名を登録し、その提案を信頼したエージェントや開発者に攻撃者のコードをインストールさせることです。この用語は Seth Larson が作り、USENIX 2025 の調査で、モデルが名前を捏造する頻度が測定されました。

ExactGround はコードを外部に送信しますか？

ローカルガードが送信するのは、パブリックレジストリ（registry.npmjs.org、api.npmjs.org、pypi.org）へのパッケージ名のみです。これはパッケージマネージャーが送信するものと同じです。ホスト型 API に送信されるのは、ユーザーが送信した内容のみです。

プライベートパッケージはブロックされますか？

.exactground.json（allow または privateScopes）に登録し、exactground trust でファイルを承認すれば、ブロックされません。pip／uv でカスタムの --index-url を使用している場合、見つからない名前は警告のみとなります。

エージェントの動作は遅くなりますか？

新しいパッケージ名ごとに、キャッシュされる HTTP リクエストが 1 件発生します。通常は 100～400 ms で、何もインストールしないコマンドではリクエストは発生しません。

フックはセキュリティ境界ですか？

いいえ。エージェントフックはガードレールです。Claude Code と Codex のドキュメントでは、フックがタイムアウトしたり回避されたりする可能性があると説明されています。Codex のホスト型ツールにはフックが適用されず、Cursor はファイル編集が行われる前にそれをブロックできません。ExactGround のフックは、デフォルトで内部エラーやレジストリの停止時に拒否します。内部エラー時に許可するには、EXACTGROUND_FAIL_OPEN=1 を設定してください。ロックファイル、CI チェック、インストール時のスキャナーも引き続き使用してください。

対応しているエコシステムは？

npm（npm、pnpm、yarn、bun、npx）と PyPI（pip、uv、poetry、pdm、pipx、uvx）です。

開発

npm test        # 27 offline tests: parser, policy, cache, all four hook formats, manifests, patches

人気パッケージの一覧は、npm-high-impact（MIT）と top-pypi-packages（data/ を参照）に由来します。

同じチームが提供するその他のツール

• DoneLatch：新しく取得した、失敗に敏感な証拠がなければ、エージェントは「完了」できません。
• CanaryIndex：エージェントツール向けの、定期的に再実行される公開スコアカードです。
• Waraq：ノート PC やスマートフォンで使える、エージェントファイル向けの無料オフライン Markdown リーダー兼エディターです。
• すべてのツール：https://alidaram99.github.io/

ライセンス

MIT。npm、PyPI、Anthropic、OpenAI、Google、Cursor とは提携していません。