agentgate

English · 中文

agentgate

エージェントが実行するツールのコントロールプレーンです。使用中のツールを一覧化し、あらゆる主張の根拠を記録し、企業として許容しないものを明示して、その判断を CI と実行時に適用します。

プロジェクト全体は、次のルールに従います。

すべてのチェックが実行された場合にのみ、clean を出力します。測定できなかったものは unmeasured となり、未測定の部分を含む成果物は incomplete です。clean にはなりません。

これは、セキュリティスキャナーでよくある失敗が、誰も作業していないのにビルドが成功することだからです。ここでは、チェックがクラッシュすると結果は未完了になるため、問題がひそかに見過ごされることはありません。

4つの要素

要素	内容	パッケージ
inventory	レジストリを列挙し、パッケージを解決し、リポジトリを取得します	packages/collect
evidence	サーバーごとに1つのレコードにまとめ、あらゆる主張の根拠となるバイト列を保存します	packages/collect
policy	企業として許容しないものを、設定、フック、マニフェスト、ソースからスキャンします	packages/guard
verification	主張の内容を、その主張の外部にある情報と照合します	packages/verify

実行方法

サーバーのセットアップについては、docs/operations/deployment-runbook.mdを参照してください。 2026-09-16の初回デプロイについては、チェックした内容と未確認の内容とともに docs/verification.mdに記録しています。

docs/capabilities.mdには、このプロジェクトが主張できることとできないことを1行ずつ記載しており、各行に実行可能なコマンドが付いています。以前、あるコンサルタントが私たちに代わって機能を記録しましたが、実際にはない機能を4つ含めていたため、このファイルを用意しました。

インストールせずに試す

サービスは https://xn--5kvo87g.com/ で稼働しています。同じホストで、ランディングページ、料金、エビデンスのインデックス（毎日再構築）、APIを提供しています。

https://ciceroyang.github.io/agentgate/ は GitHub Pages 上のランディングページです。インデックスは https://ciceroyang.github.io/agentgate/evidence.html にある、閲覧可能な単一ページで、ライブレジストリから毎日再構築されます。レコードは埋め込まれており、絞り込みはローカルで行われるため、登録は不要です。料金と10分間のウォークスルーもご覧ください。

クイックスタート

**0.6.0 にアップグレードする場合：**既存のアドミッションゲートまたは監視環境を置き換える前に、アップグレードガイドをお読みください。0.5.0 パッケージは、エビデンスが存在しない場合に、必須エビデンスのゲートを誤って通過させることがあります。新しいゲートには使用しないでください。インストールしたバージョンを確認し、公開パッケージの検証についてはリリース記録を参照してください。ソースをチェックアウトした環境とホスト型サービスでは、異なるバージョンが実行されている場合があります。

Node 20 以降が必要です。依存関係はありません。クローンにはサンプルインデックスが含まれているため、サービスはすぐに応答します。refresh を実行すると、最新のインデックスに置き換わります。

node bin/agentgate.mjs serve
# agentgate serving http://127.0.0.1:8080

curl -s localhost:8080/health
curl -s localhost:8080/v1/index/summary
curl -s localhost:8080/v1/servers/<name>
curl -s localhost:8080/badge/<name>.svg

パッケージは npm で @zhiliangtech/agentgate として公開されています。v* タグをプッシュすると、CI がプロベナンス情報を付けて公開します。セットアップと検証内容の記録については、publish-checklist.mdを参照してください。

npx --yes --ignore-scripts @zhiliangtech/[email protected] check --root .
npx --yes --ignore-scripts @zhiliangtech/[email protected] serve

バージョンを指定しない npx コマンドは、このチェックアウトではなく、latest の dist-tag に従います。承認済みのバージョンを指定してください。ローカルのバージョン番号を編集しても、公開パッケージは変わりません。

ポリシーファイルがない場合、check は追加の拒否対象がない組み込みのデフォルトを使用し、serve はパッケージに同梱されたスナップショットから応答します。refresh はインストール済みパッケージ内ではなく、手元の ./data に書き込みます。

Docker でも同じコマンドを実行できます。

docker compose up                            # the service on :8080
docker compose --profile collect run --rm refresh   # rebuild data/index.json and seed the first snapshot

ツール一覧

node bin/agentgate.mjs serve を実行し、表示されたアドレスで /inventory.html を開きます。ツール名のリストを貼り付けるか、テキスト／JSON ファイルを選択し、曖昧な一致を解決して、実際に使用しているバージョンを入力すると、単体で使える HTML レポートをダウンロードできます。照合は、埋め込みインデックススナップショットを使ってブラウザーのメモリ上で行われます。リストがアップロードまたは保存されることはなく、お使いのマシンがスキャンされたり、ツールが実行されたりすることもありません。レコードにカバレッジブロックが含まれている場合、レポートには実行されたスキャナーと実行されなかったスキャナー、およびその理由も記載されます。レコード自身のカバレッジブロックで必須のスキャナーが完了していないと示されている場合、ほかの証拠がどれほどそろっていても、一致したものとして表示されません。

ブラウザーを使わずに同じことを行うには：

node bin/agentgate.mjs inventory --input examples/inventory/tools.json --out my-tools.html
node bin/agentgate.mjs inventory --input tools.json --index data/index.json --format json

入力には、1 行に 1 つの名前、JSON 配列、または { "tools": [...] } を指定します。各オブジェクトに指定できるのは name、server、package、registry、version のみで、それ以外は指定できません。クライアント設定全体や認証情報は意図的に拒否されます。詳しくはインベントリーガイドをご覧ください。

一致しない項目、曖昧な項目、バージョンがない項目、バージョンが一致しない項目、証拠が不完全な項目は、レポートに残ります。バージョンが一致しても、実際にインストールされているものの証明にはなりません。コミット済みのサンプルは過去のもので、確認済みの一致を示すことはできません。また、コンテンツとの厳密な紐付けがない古い証拠も同様です。確認済みの一致であっても、安全性の認証や新たなスキャンを意味するものではありません。これを信頼する前に、対象範囲、検出結果、スナップショットの日付、欠落している情報を確認してください。

終了コード 0 はレポートが生成されたことを示すものであり、すべてのツールに問題がなかったことを示すものではありません。不正な入力や読み取れないデータの場合は 2 で終了します。また、--out は既存のファイルを上書きしません。CI で何かを拒否したい場合は、inventory ではなく check を使ってください。

まずリストを取得する

このリストを手作業で用意する必要はありません。discover はマシン上にある MCP 設定ファイルを読み取り、inventory --input で受け付けられる形式の入力を生成します。エクスポートされた識別子がすべて判明している場合は、パッケージの座標を行ごとに出力します。エントリのいずれかがエイリアスのみの場合は、[email protected] のようなエイリアスが、検証済みのパッケージやバージョンと誤認されないよう、JSON を使います。

node bin/agentgate.mjs discover --out tools.txt          # home directory + current directory
node bin/agentgate.mjs discover --roots ~/code/a,~/code/b --format json

env の値、ヘッダー、引数は決して出力しません。また、パスやクエリー文字列にはトークンが含まれるため、リモートアドレスはホストまでに切り詰められます。設定されたサーバーを起動せずに、Codex の .codex/config.toml にある MCP テーブルを読み取ります。明示的に無効化されたエントリは --format json では表示されますが、テキストおよびインベントリーへのエクスポートでは除外されます。サポート対象外の MCP TOML 形式、不正なファイル、読み取れないファイルは理由とともに一覧表示され、コマンドは終了コード 2 で終了します。パッケージ名とバージョンには、認識可能な宣言済みランナー引数から取得したものだけが使われます。カスタムコマンドやリモートホストは、検証済みのパッケージやランタイムバージョンとして扱われません。

複数のリポジトリ

node bin/agentgate.mjs audit --roots ~/code/a,~/code/b,~/code/c --index data/index.json

ディレクトリごとに 1 回スキャンし、全体に対して 1 つの判定を行います。未完了のディレクトリが 1 つでもあれば監査は未完了となり、存在しないディレクトリはスキップではなく未計測として扱われます。

前回からの変更

node bin/agentgate.mjs watch --input tools.txt --index data/index.json --archive ./archive
node bin/agentgate.mjs watch --verify --archive ./archive
node bin/agentgate.mjs watch --input tools.txt --index data/index.json --archive ./archive \
  --webhook https://example.invalid/hook --webhook-format wecom

実行のたびに、連鎖アーカイブに 1 行追加します（prev は直前の行のハッシュです）。また、検出した内容を snapshots/<sha256>.json に保存します。--verify はチェーンと保持されているすべてのスナップショットを再計算し、一致しないものがあれば 1 で終了します。--webhook にアドレスが指定されない限り、何も外部に送信されません。また、プッシュの前にアーカイブを書き込むため、チャットサービスが停止していても取得内容が失われることはありません。

質問票との対応付け

node bin/agentgate.mjs framework                       # who answers which AI-CAIQ item
node bin/agentgate.mjs inventory --input tools.json --framework aicaiq --out report.html

各 AI-CAIQ 項目について、対応付けでは提供できる内容、カバレッジの限界、回答者が当社、顧客、独立評価者のいずれであるかを示します。これは証拠について説明するものです。コンプライアンスに関する結論ではなく、公式の文面を再現するものでもありません。レビュー担当者がベンダーに尋ねる 4 つのドメインの全 58 項目が分類されており、当社が回答するものは 13 項目、顧客が回答するものは 41 項目、独立評価者が必要なものは 4 項目です。

エビデンスパック

マッピングには、提供できる内容が記されています。pack は成果物そのものを生成します。ベンダーがレビュー担当者に渡す単一のディレクトリで、主張するすべての回答が同じディレクトリ内のエビデンスを示し、測定できなかった項目はすべて冒頭にまとめられます。

node bin/agentgate.mjs pack --input tools.json --archive ./agentgate-archive --out agentgate-pack
node bin/agentgate.mjs pack --verify agentgate-pack     # recompute every hash and the seal

pack.json（機械可読）、pack.html（レビュー担当者向け）、answers.aicaiq.md（全58項目をそれぞれ分類）、manifest.txt（ファイルごとに1つのsha256）、およびmanifest.sha256（マニフェストの改ざんを防ぐシール）を書き出します。エビデンスが不足している回答はunmeasuredと表示され、コマンドは0ではなく2で終了します。ライブインデックスから作成した例はこちらです： docs/samples/evidence-pack-example — pack --verifyで検証できます。仕様：docs/spec/evidence-pack-v1.md。

MCP サーバー

MCP に対応するものであれば、インデックスに直接問い合わせることができます。claude_desktop_config.json、リポジトリの.mcp.json、またはクライアントが読み込む設定ファイルに次の内容を追加してください。

{
  "mcpServers": {
    "agentgate": { "command": "npx", "args": ["--yes", "@zhiliangtech/agentgate@next", "mcp"] }
  }
}

読み取り専用のツールが4つあります：lookup_server（カバレッジブロックを含む1件のレコード）、inventory_tools（実際に使用するツールを照合）、coverage_report（インデックスのうち測定済みの範囲）、check_project（ローカルディレクトリをスキャン）。ローカルインデックスを読み取るだけで、書き込みやアップロードは行わず、スキャン対象のツールも実行しません。不完全なレコードは不完全として報告され、インデックスにないレコードは安全ではなく、欠落として報告されます。詳細：docs/spec/mcp-server-v1.md。

ポリシー

ポリシーには、企業が許可しないことを記述します。ポリシーはコードではなくデータであり、仕様もあります：docs/spec/policy-v1.md。

{
  "version": "agentgate.policy/v1",
  "threshold": "high",
  "required": { "pinnedPackages": true, "measuredEvidence": ["packageManifest"] },
  "forbidden": { "rules": ["AG-INSTALL-001"], "servers": ["internal/*"] }
}

node bin/agentgate.mjs check --policy agentgate.policy.json --root . --index data/index.json

上記のポリシーでは、インデックス化されたエビデンスが必要です。ローカルの npm パッケージと名前およびバージョンが完全に一致する実際のインデックスを指定してください。エビデンスがない場合は2で終了し、インデックスが明示的に欠落している場合、形式が不正な場合、またはサンプルの場合は3で終了します。ローカルソースのスキャンは、必須のパッケージエビデンスの代わりにはなりません。

ポリシーファイルも--policyも指定しなくても、チェックは実行されます。チェックで見つかった内容を報告し、何も追加で拒否しない組み込みのデフォルトを使用したことを示します。あなたに代わって義務を作り出すと、結果の意味が薄れてしまいます。明示的に指定したポリシーを読み込めない場合は、入力ミスなのでエラーになります。

同じ評価結果を、ターミナルではなく担当者向けに出力することもできます：

node bin/agentgate.mjs check --policy agentgate.policy.json --root . --index data/index.json --format html --out report.html

スクリプトを含まない、静的で印刷可能な単一ファイルです。測定できなかった内容はすべて、チェック結果より前の専用セクションにまとめられます。未チェックの項目を目立たない場所に埋め込んだレポートでは、実際以上に網羅的に見えてしまいます。このファイルは、無料チェックアップで提供されるものです。

結果は3種類あり、incompleteはfindingsより優先されます。チェックの実行に失敗した場合、またはポリシーで必要とされるエビデンスブロックがunmeasuredの場合、チェック結果がどれほど問題なさそうに見えても、終了コードは2です。しきい値によって不完全な回答が合格になることはありません。

exit	意味
0	問題なし
1	指摘事項あり
2	不完全

強制適用

ポリシーで拒否されるものをプルリクエストが追加した場合、そのプルリクエストはマージされません。また、誰も開かないログに理由を残すのではなく、プルリクエスト上に理由が投稿されます。

- uses: ciceroyang/agentgate@main
  with:
    policy: agentgate.policy.json
    index: data/index.json

examples/github-actions/policy.ymlを参照してください。このアクションはチェックを実行し、コードスキャン用のSARIFを書き出し、レポートをプルリクエストにコメントし、チェック自体の終了コードで終了します。そのため、不完全なスキャンも2でビルドを失敗させます。

ランタイム

クライアントからサーバーに直接接続する代わりに、サーバーの前段にゲートウェイを置けば、同じポリシーをすでにリリース済みのものにも適用できます：

node bin/agentgate.mjs proxy --policy agentgate.policy.json --log calls.jsonl -- \
  npx -y @modelcontextprotocol/server-filesystem /data

ポリシーで拒否された呼び出しには、理由を付けてローカルで応答し、サーバーには到達させません。禁止されたツールは公開リストから削除されるため、クライアントはそのツールを一切要求できません。許可された判断も拒否された判断もすべてログに追記されます。

履歴

インデックスは保持されるため、2つのビルドを比較できます。注目すべきなのは最後の列です。 リリースで説明されていたはずなのに、説明されなかった変更です。

node bin/agentgate.mjs diff --from previous-index.json --to data/index.json

  added:           0
  removed:         0
  verdict changed: 1
  package changed: 0
  silent (no version move, different evidence): 1

バージョンが変わっていないのに新しい検出結果が見つかった場合、リリースなしでパッケージが置き換えられた、リポジトリがその場で編集された、またはスキャンで何かが検出されるようになったことを示しているのが一般的です。この記録を後から埋めることはできません。その時点で誰かが確認していた場合にのみ存在します。

インデックスを支えるパイプライン

node packages/collect/mcp-audit.mjs --max 6000 --out data/census.json
node packages/collect/scripts/guard-scan.mjs --census data/census.json --out data/guard-scan.json
node packages/collect/scripts/build-index.mjs --census data/census.json --guard data/guard-scan.json --out data/index.json
node scripts/coverage-stats.mjs --index data/index.json   # how much of it was actually measured

ローカルプロジェクトのスキャナーはこちらです。

node packages/guard/bin/agent-guard.mjs . --fail-on high
node packages/collect/bin/agent-add.mjs --index data/index.json <server-name>

執筆記事

• 11,605件のMCPレコードをインデックス化し、そのうち258件を監査できました (中文) — 収集したサーバーのうち、実際に測定できた数と、残りの測定を妨げた要因について説明します。数値は、記事の執筆時に対象とした2026-09-19のビルドに基づいています。インデックスは1日に数回再構築され、内容は変わります。
• 最も目立つルールは9回中9回、誤っていました
• 「クリーン」は、実施した作業についての主張です
• 検出結果のように読める理由 — 対象について説明すべきではなく、スキャナーについて説明すべきだった、カバレッジの不足が5件ありました。そのうち4件は私の責任です。

テスト

npm test                              # the whole suite; it prints how many ran
node scripts/bench.mjs 50000 200      # lookups must stay under 10 ms p50
node scripts/measure-verify.mjs       # claim extraction, against a small labelled set
node packages/guard/scripts/regression.mjs   # benign must stay silent, positives must fire

ディレクトリ構成

packages/guard     the scanner: engine, nine checks, CLI, corpus, GitHub Action
packages/collect   census, package and repository scanning, the evidence index
packages/policy    policy evaluation and human-readable reports
packages/gateway   runtime policy enforcement for MCP servers over stdio
packages/history   index snapshots and change comparisons
packages/service   the read-only evidence API
packages/verify    cross-model claim checking
docs/              architecture and product notes

検証

テストは、コードを書いた人たちが作成しています。 docs/verification.mdには、それとは異なる未実施の検証を記録しています。ゲートウェイ経由で実際のMCPサーバーを確認することと、未検証の項目一覧です。

node scripts/verify-real-server.mjs

インデックスのhighとcriticalの検出結果が、記録済みの人によるレビューと今も一致しているか確認するには、node scripts/review-criticals.mjsを実行します。レビューでは、検出結果とその証拠を、正確なパッケージバージョンおよびスキャン済みコンテンツの完全な来歴（SHA-256ダイジェストとスコープを含む）に結び付ける必要があります。結び付けが欠落または変更されている場合は、別の人によるレビューが必要です。また、過去の承認が自動的に更新されることはありません。--acceptは、すでに実施したレビューを記録し、来歴が不完全な場合は処理を拒否します。レビューを実施するものでも、サードパーティーのコードを認証するものでもありません。

運用

• docs/operations/deployment-runbook.md — ICP登録に関する注意事項を含む、aliyunと智量.comドメインの手順です。
• docs/operations/plan-b-no-icp.md — 中国本土のサーバーにICP登録がない場合の対応方法です。
• deploy/ — サーバーにそのままコピーできるCaddyfileとsystemdユニットです。
• docs/operations/pilot-package.md — パイロット導入の概要資料です。成果物、スケジュール、こちらからお願いすることとお願いしないことを記載しています。
• site/index.htmlとsite/pricing.html — 外部アセットに依存しない、自己完結型のランディングページと料金ページです。
• scripts/onboard-server.sh — 実行予定の内容を表示し、--applyを指定した場合にのみ実際に処理する、デプロイ手順のスクリプトです。
• scripts/smoke.mjs — デプロイ後の確認です。アクセス可能か、インデックスが存在し最新か、レコードがサンプルではなく実データかを確認します。

ステータス

これは初期段階のオープンソースコアです。収集、エビデンスインデックス、スキャン、CI でのポリシーチェック、stdio 経由の MCP サーバー用ランタイムゲートウェイ、履歴差分、読み取り専用サービスに対応しています。デプロイスクリプトとランブックはリポジトリ内にあり、最初のデプロイとそのチェックについてはdocs/verification.mdに記載されています。この記述は、ホストされたサービスの現在の状態については何も述べていません。コンテナの経路は保証されていませんが、ビルドはされています。CI は docker compose up --build を実行し、起動中のコンテナに対してヘルスチェックを行います。

バージョン識別子が保証する内容と、サポート対象のバージョンについては docs/spec/compatibility.mdに記載されています。SECURITY.mdには、脆弱性の報告方法と、報告後に想定される対応が記載されています。いずれも上記のゲート 3 およびゲート 4 の代わりにはなりません。エンタープライズ向けの機能はまだ不足しており、このリポジトリの外部で依存している人もまだいません。

料金提案に記載されたエンタープライズ機能、つまり SSO/SAML、RBAC、マルチテナンシー、署名付き監査エクスポートは実装されていません。Team と Enterprise の価格は未検証の仮説であり、これを求める人がいるかどうかを検証する方法が無料パイロットです。パイロットの範囲とライセンスをご覧ください。

テストスイートでは、クラッシュしたチェックが clean を返すことは決してないという不変条件を確認しています。現在の数値は npm test を実行して確認してください。このページではテスト件数を繰り返しません。

ライセンス

AGPL-3.0-only。変更を公開せずに、変更を加えた agentgate をクローズドなサービスとして提供する場合（これは AGPL では許可されていません）は、商用ライセンスを利用できます。docs/product/licensing.mdをご覧ください。