zn-gate

zn-gate

コーディングエージェント向けのローカルセキュリティレイヤーです。 Claude Code、Codex CLI、Cursor、OpenCode の利用中に、zn-gate がシークレット、データ、システムを保護します。

zn-gate は、エージェントと、エージェントが扱うツールやコンテンツの間で、お使いのマシン上で動作するオープンソースのセキュリティレイヤーです。エージェントが読み取る内容や呼び出す内容にプロンプトインジェクションがないか確認し、モデルに表示される前にツールの出力からシークレットをマスキングし、プロンプト、スキル、設定を監査します。アカウントは不要で、デフォルトではネットワーク通信もありません。実行時の依存関係は、シークレットボルト用の age-encryption（およびその @noble／@scure 依存関係）だけで、package-lock.json で固定されたバージョンがパッケージに同梱されています。

対象： Claude Code、Codex CLI、Cursor、OpenCode、または任意の MCP クライアントを使用する開発者。Python SDK：PyPI の zn-gate。

インストール

すべてお使いのマシン上で動作し、アカウントや API キーは不要です。Node.js 18 以降（nodejs.org の LTS バージョン）が必要です。古い Node.js では、zn-gate コマンドと zn コマンドは停止し、インストール方法を表示します。Claude Code プラグインには Node.js 20.12 以降が必要です。

始め方：4 つの手順、それぞれ 1 つのコマンドです。 お使いのターミナルで実行してください。

1. npx -y zn-gate reach を実行すると、このマシン上でコーディングエージェントがアクセスできるものが表示されます。.env ファイル内のシークレット（名前のみ）、認証情報ファイル、MCP サーバーが対象です。読み取り専用で、何も送信しません。詳しくは docs/reach.md をご覧ください。
2. npx -y zn-gate init は、検出したコーディングエージェントの保護を、手順ごとに設定し、変更の前に確認を求めます。
3. npx -y zn-gate check は、一時フォルダー内の偽のシークレットを使って保護をテストします。init の最後にも実行されます。
4. npx -y zn-gate env shadow .env は、.env の実際の値をローカルボルトに移し、ファイルにはマーカーを残します。初回は npx -y zn-gate unlock を実行してボルトを作成してください。

お使いのマシン上のコーディングエージェントをまとめて設定するコマンド：

npx -y zn-gate init

init が行う処理：

• お使いのマシン上の Claude Code、Codex CLI、Cursor、OpenCode を検出します。
• まだ保護されていないものごとに、設定内容を表示します。Claude Code には zn-gate プラグイン（Node.js が 20.12 より古い場合は zn のフック）、それ以外には zn のフックを使います。
• 各手順は、確認を得てから実行します。
• 最後に zn-gate check を実行します。

ご自身で、お使いのターミナルから実行してください。AI エージェントやスクリプトが実行した場合は、手順を表示するだけです。

Windows PowerShell： デフォルトの実行ポリシーが npm.ps1 をブロックするため、「このシステムではスクリプトの実行が無効になっています」というエラーが発生し、npm と npx が失敗することがあります。代わりに npm.cmd、npx.cmd、zn.cmd を使う（たとえば npm.cmd install -g zn-gate）、コマンドプロンプトからコマンドを実行する、または Set-ExecutionPolicy -Scope CurrentUser RemoteSigned を使ってアカウントのローカルスクリプトを許可してください。

問題が発生した場合：

• npx: command not found、またはNode.jsのバージョンに関するメッセージが表示される場合： Node.js のLTSバージョンをインストールし、新しいターミナルを開いてコマンドをもう一度実行してください。
• Windowsで「このシステムではスクリプトの実行が無効になっています」と表示される場合：上記のPowerShellに関する注意をご覧ください。
• init が手順を表示するだけで何も変更しない場合：AIエージェントまたはスクリプトが実行しました。ご自身のターミナルで実行してください。
• check に NOT protected と表示される場合：その行に理由と実行するコマンドが記載されています。出力の意味。
• init による変更を元に戻したい場合：npx -y zn-gate init --revert。

次に、.env の値をボールトに保管します。 プラグインまたはフックを使うと、エージェントは実際の値が入った .env ファイルを読み取れません。値をzn-gateの暗号化ボールトに移すと、ファイルには __ZN_STRIPE_KEY__ のようなマーカーが残ります。

npx -y zn-gate unlock            # creates the vault the first time
npx -y zn-gate env shadow .env

この後、許可してからzn-gateの run コマンドでアプリを起動すれば、ご自身のアプリも .env 内のマーカーを読み取れます（docs/secrets.md）。元に戻す方法は env shadow で確認できます。

5分間のガイド：docs/secrets.md。制限事項：docs/threat-model.md。知らない用語：用語集。

claude plugin marketplace add usezn/zn
claude plugin install zn-gate@usezn

npm install -g zn-gate
zn hooks install codex           # or: cursor, opencode

python3 -m venv .venv
.venv/bin/pip install zn-gate      # Windows: .venv\Scripts\pip install zn-gate

claude mcp add zn-gate -- npx -y zn-gate mcp     # Claude Code
codex mcp add zn-gate -- npx -y zn-gate mcp      # Codex CLI

init はエージェントの設定ファイルから MCP サーバーを見つけてバックアップを作成し、各ローカル（stdio）サーバーを zn-gate shield でラップします：

npx -y zn-gate init --dry-run   # preview, changes nothing
npx -y zn-gate init --wrap-mcp  # wrap (a .bak.<timestamp> copy is written first)
npx -y zn-gate init --shadow    # log detections without blocking
npx -y zn-gate init --revert    # restore the latest backup

リモート（URL）サーバーはそのままです。init は安全に往復変換できないファイルを書き換えません。コメントを含む OpenCode の JSONC ファイルや、複数行の args を含む Codex エントリーは「手動でラップしてください」と報告されます。

サーバーを1つだけ手動でラップするには：

npx -y zn-gate shield -- uvx mcp-server-fetch

zn-gate の動作を確認する

npx -y zn-gate report

このコンピューターでの過去7日間の概要です。ブロックされた操作、隠されたシークレット、新たに保護された MCP サーバー、承認待ちのツール変更を表示します。ローカルファイルのみを読み取り、アカウントは不要で、情報は送信されません。--since 30d で期間を変更でき、--json でスクリプト向けに出力できます。表示内容。

オプションのクラウドチェックを有効にする

npx -y zn-gate connect

任意の操作で、ご自身のターミナルで手動で行います（エージェントには実行できません）。usezn.com を開き、分析専用 API キーを作成します（使用状況の読み取りやキーの管理はできません）。その後、非表示のプロンプトでキーを貼り付けるよう求められます。フルアクセスキーは拒否されます。キーはシステムのキーチェーン（キーチェーンがない場合は zn のボールト）に保存され、ファイルには決して書き込まれません。また、zn のフックはエージェントがキーを直接読み取る方法を拒否します。設定後、シークレットを検出して取り除いたうえで、あなたまたはエージェントが analyze_prompt を通じて送信するテキストも、usezn.com の Galvanize 2 分類器でチェックされます。この操作を実行するまでは、何も送信されません。zn-gate disconnect を実行すると、このコンピューターからキーが削除され、usezn.com でもキーを失効させるかどうかを確認します（既定では「いいえ」）。仕組み。

動作を確認する

npx -y zn-gate check

ユーザー向けにセットアップされた各エージェントについて、zn-gate はフックに指示し、一時フォルダー内にある偽のキーを含む .env ファイルと通常のファイルをエージェントに読み取らせます。エージェントに何が伝えられるかが表示され、NOT protected と表示された行には修正方法が示されます。ネットワーク経由の送信はなく、設定も変更されません。出力の意味。

npx -y zn-gate test

ローカルのセルフテスト（厳選したベクトル51件：攻撃26件、正常な入力25件）を実行し、このコンピューターでの判定ごとのレイテンシを表示します。これはスモークテストであり、検出率を示すものではありません。ネットワーク経由の送信はありません。

開発者向け：手動でサニタイズを確認する。 偽の AWS キー（AWS のドキュメントにある例）とデータベースパスワードを含むツール出力を、エージェントが使う場合とまったく同じ方法で zn-gate に送信し、出力内の sanitized_content を確認します。このフィールドがモデルに渡される内容です：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_tool_result","arguments":{"tool_name":"read_file","content":"AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nDATABASE_URL=postgres://app:hunter2@db:5432/main"}}}' \
  | npx -y zn-gate@latest mcp

各機能の役割

Scrubber：シークレットをモデルのコンテキストに含めない

• 現在：zn-gate を通過するすべてのデータ（check_tool_result、check_tool_call、および shield / init でラップされたサーバーの出力）から、AWS キー、OpenAI と Anthropic のキー、GitHub トークン、JWT、秘密鍵、データベース URL のパスワードを秘匿します。
• 現在の対象外：エージェントに組み込まれたツール（たとえば Claude Code のネイティブなファイル読み取り）。ただし、その出力が zn-gate を通過する場合を除きます。
• ロードマップ：個人データ（PII）の検出、エージェント組み込みツール向けのフック、ローカルの暗号化された保管庫で管理する安定したプレースホルダー。

Galvanize：プロンプトインジェクションの検出

• 現在、ローカル：同形異字、ゼロ幅文字、BiDi オーバーライド（CVE-2021-42574）、コメントの挿入、Base64 に対する正規化機能を備えた決定論的なルールエンジンです。プロンプト、ツールの引数、ツールの出力、MCP ツールの説明をチェックします。
• 現在、オプションのクラウド：Galvanize 2 分類器（オープンウェイト、Apache-2.0）では、ZN_CLOUD=1 と ZN_API_KEY を設定した場合に限り、analyze_prompt に送信されたプロンプトもチェックできます。
• ロードマップ：zn-gate 内で Galvanize をローカル実行。

Scan：エージェントが信頼しようとしている内容を監査

• 現在：npx -y zn-gate scan <path> は、プロンプトテンプレート、AGENTS.md / SKILL.md ファイル、設定ファイルを監査し、インジェクションの罠や漏えいしたシークレットを検出します。CI 向けに、検出事項がある場合は終了コード 1 を返します。MCP サーバーはウェブ上の usezn.com/scan でチェックできます。
• ロードマップ：追加する前に、CLI から MCP サーバーとスキルを監査。

MCP ツール

マシンの外部に送信されるデータ

デフォルトでは、何もありません。

ZN_API_KEY だけでは何も有効になりません。オプトインするもう 1 つの方法は zn-gate connect です。自分のターミナルで実行すると、キーはシステムのキーチェーンまたは zn のボールトに保存され、ファイルには保存されません（zn-gate disconnect で接続を解除できます。また、確認に同意すれば usezn.com でキーを失効できます。詳しくはこちらをご覧ください）。ZN_LOCAL_ONLY=true（または --local-only）を指定すると、ZN_CLOUD=1 や接続済みのキーよりも優先されます。npx -y zn-gate status で、有効な検出エンジンと任意のクラウドチェックが有効かどうかを確認できます。利用統計の共有はデフォルトでオフになっており、独自のステータスがあります：npx -y zn-gate stats share status。データフロー図：リポジトリの README。

1.4.0 以前： ZN_API_KEY が設定されている場合、ローカルでブロックされなかったツールの出力とツール呼び出しの引数は、伏せ字にされず api.usezn.com に送信されていました。1.4.1 ではこの経路が削除されています。CHANGELOGをご覧ください。

パフォーマンス（ローカルルールエンジン、ネットワーク通信なし）

2026-10-11 に、2 vCPU の Intel Xeon Platinum 8259CL（AWS）、Node 24、zn-gate 1.4.1 で、キャッシュされていない入力を測定しました。p50 は 3 回の実行の中央値、p99 は 3 回の実行のうち最も遅い値です。

check_tool_result にはシークレットの伏せ字化が含まれます。レイテンシーは入力サイズにほぼ比例して増加します。同じホストで、4 KB の check_tool_result における MCP stdio の往復時間は p50 で 0.5 ms でした。

リポジトリから node bench/bench_by_size.js を実行して再現できます。測定結果をぜひお送りください。

精度：ローカルルールで検出できるものとできないもの

ローカルエンジンは、決定論的なシグネチャと正規化のレイヤーです。高速で説明可能ですが、意味を分類するものではありません。

• セルフテスト： 厳選した51個のベクトルに合格しています。これはスモークテストであり、検出率や誤検知率を示すものではありません。
• 既知の制限： check_tool_result から見たソースファイル全体では、通常のコードコメントにフラグを立てることがあります。1.5.0では、コードやドキュメントでの誤検知を減らしていますが、その代わりに、曖昧な表現の上書き試行がローカルルールをすり抜けることがあります。自分のリポジトリのファイルではなく、ウェブやサードパーティのコンテンツに対して check_tool_result を使うことをおすすめします。
• 検出率： 非公開のホールドアウトセットに含まれる3,309件の例では、Galvanize 2は偽陽性率0.81％で再現率83.4％（サービング閾値0.662）を達成しています。これらの数値はクラウド分類器のものであり、ローカルルールエンジンのものではありません。手法、言語ごとの結果、既知の弱点、再現可能なベンチマークについては、モデルカードと発表記事をご覧ください。これは防御の一層であり、保証ではありません。

設定

• ZN_CLOUD：1 にすると、analyze_prompt／zn-gate analyze がクラウド分類器にも問い合わせます。ZN_API_KEY が必要です。デフォルトでは無効です。
• ZN_API_KEY：usezn.com/dashboardで取得したAPIキーです。ZN_CLOUD=1 が設定されていない場合は効果がありません。（zn-gate connect を使うと、代わりにキーが保持され、クラウドチェックが有効になります。）
• ZN_LOCAL_ONLY：true にすると、ZN_CLOUD=1 が設定されていてもローカルのみで処理します。
• ZN_STRICT：1 にすると、デフォルトでは警告のみとなるルールもブロックします（下記を参照）。
• ZN_LONG_INPUT：長いテキスト（1,000文字超）をクラウド分類器に送信する方法です。windows（デフォルト）では、重複する512トークンのウィンドウを最大20個チェックするため、長い文書の途中や末尾にあるインジェクションも見逃しません。off では最初の512トークンのみをチェックします。--long-input windows|off も指定できます。ウィンドウを使うと処理は遅くなり、無害な長文にフラグを立てる可能性がわずかに高まります。また、クラウドチェックはウィンドウの有無にかかわらずテキストサイズに応じて課金されるため、off にしても回数は減りません（2,000文字までは1回、それ以降は1,000文字ごとに1回追加。結果の billed_calls を参照）。詳しくは変更履歴をご覧ください。
• ZN_STAGE：v30（デフォルト、現在の本番API）または prod（旧エンドポイント）です。ZN_API_URL を設定すると、どちらよりも優先されます。
• NO_COLOR（空でない値）または TERM=dumb：コマンド出力から色、記号、罫線をなくします。ステータスの語句（ALLOWED、BLOCKED、PASSEDなど）はそのまま表示されます。出力先がターミナルでない場合も色は無効になります。

1つのMCPサーバーでクラウドチェックを有効にするには、そのエントリーに次を追加します："env": { "ZN_CLOUD": "1", "ZN_API_KEY": "zn_live_..." }。

カスタムルール（.znrules または zn.config.json）

# .znrules
path:.env.production
path:/etc/secrets
CONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+

ローカル監査ログ

zn-gate shield は、すべての判定を ~/.zn/evidence.jsonl に、秘密情報を伏せたプレビュー付きのハッシュチェーン（SHA-256）レコードとして追記します。これにより、誤操作や部分的な編集を検出できます。ただし、ファイルへの書き込み権限を持つ人がチェーン全体を再計算できるため、改ざんを完全に防止するものではありません。

npx -y zn-gate evidence --verify
npx -y zn-gate evidence --ui        # local dashboard on http://localhost:3100
npx -y zn-gate evidence --tail 20

ブロックされるものと警告のみのもの

zn-gateは、ほぼ間違いなく攻撃または情報漏えいにあたるものをブロックします。たとえば、認証情報ファイル（.env、~/.aws/credentials、SSHキー）の読み取り、APIキーやパスワードの要求、隠し画像リンクを使ったデータ送信、Base64や不可視文字に隠された指示、「以前の指示をすべて無視して」という文言、危険なコマンドなどです。

一方、YAMLの system: キー、「キャッシュを回避する」という文言、ジェイルブレイクとは何かを説明する記事など、通常のテキストにも含まれるパターンがあります。こうした場合、zn-gateはテキストを通し、短い警告（結果の advisory）を追加するため、あなたやエージェントが確認できます。

これらもブロックするには、厳格モードを有効にします。ZN_STRICT=1 を設定するか、プロジェクトの zn.config.json に "strict": true を追加するか、.znrules に strict と記述してください。

よくある質問

アカウントや API キーは必要ですか？ いいえ。ローカルでの機能はすべて、アカウントや API キーなしで利用できます。

正当なコンテンツがブロックされることはありますか？ あります。評価中は、init または shield で --shadow を使用すると、ブロックせずに検出内容を記録できます。

削除するにはどうすればよいですか？ npx -y zn-gate init --revert を実行すると、バックアップから設定が復元されます。スタンドアロンのサーバーの場合は、エージェント設定から zn-gate のエントリーを削除してください。

セキュリティ

脆弱性は [email protected] までご報告ください。ポリシーとセーフハーバーについては、SECURITY.md をご覧ください。

ライセンス

MIT © usezn

このパッケージには age-encryption（BSD-3-Clause）とその @noble / @scure 依存関係（MIT）がバンドルされています。詳細は THIRD_PARTY_NOTICES.md をご覧ください。