AgentGuard

AgentGuard 是一个面向 MCP Agent 的策略驱动型运行时授权与安全评估平台。项目目标是在 Agent 调用工具之前，对 MCP Server、工具能力、调用参数和运行状态进行可审计、可撤销、默认拒绝的安全控制。

项目依据 AgentGuard_迭代开发计划书.md 分阶段开发，目前已完成第 0～2 周内容：

• 第 0 周：架构、威胁模型、安全边界与工程基线；

• 第 1 周：MCP Gateway、Mock Server、调用代理和 PostgreSQL 审计链；

• 第 2 周：Server Registry、Scanner、人工准入、工具启用控制和 Catalog drift 检测。

当前能力

• 通过 MCP Streamable HTTP 向 Agent 提供统一工具入口；

• 聚合 Order、File、Notification 三个 Mock MCP Server；

• 使用命名空间工具名和固定路由，阻止客户端覆盖后端连接信息；

• 对工具参数执行 JSON Schema 校验和结果大小限制；

• 在工具执行前写入 fail-closed PostgreSQL 审计记录；

• 使用服务端 Profile 注册 MCP Server，禁止 API 提交任意命令、参数或凭据；

• 使用隔离 MCP 会话发现工具并执行安全扫描；

• 支持人工批准、拒绝、暂停和重新扫描；

• Gateway 仅连接 Registry 中已批准的 Server；

• tools/list 仅公开 enabled 工具；

• 每次 tools/call 前重新检查当前准入状态；

• 检测工具新增、删除、描述和 Schema 变化，并自动进入复审；

• Registry、审计或准入状态异常时默认拒绝调用。

Related MCP server: SINT Protocol

运行环境

• Python 3.12

• Docker Desktop 与 Docker Compose

• PostgreSQL 15

• Redis 7

本地启动

Copy-Item .env.example .env
python -m pip install -e ".[dev]"
docker compose up -d
python -m alembic upgrade head
python -m scripts.seed_dev_data
python -m scripts.check_infrastructure
python -m uvicorn main:app --reload

默认地址：

MCP 地址末尾的 / 是挂载路由的一部分，客户端连接时必须保留。

Server 准入机制

Server 连接信息只从 config/server-profiles.yaml 解析。客户端只能提交 profile_key，不能覆盖 command、args、endpoint、environment 或 credential。

准入流程：

服务端 Profile
  → 注册为 untrusted / pending_scan
  → 隔离会话执行 tools/list
  → Scanner 生成标准化 Finding
  → pending_review
  → 人工绑定 scan/profile/catalog/version 审核
  → approved 或 rejected
  → Gateway 启动时构建 eligible Server 集合
  → tools/list 仅返回 enabled 工具
  → tools/call 前再次检查当前准入状态

未批准、已拒绝、已暂停、扫描失败或发生目录漂移的 Server 均不会进入 Agent 工具目录。

完整接入说明请参阅 MCP Server 接入与准入指南。

临时管理 API

第 2 周提供了仅用于 development/test 的临时管理 API，默认关闭。启用方式：

AG_ENVIRONMENT=development
AG_MANAGEMENT_API_ENABLED=true
AG_MANAGEMENT_API_KEY=replace-with-at-least-32-random-characters

所有管理请求必须携带：

X-AgentGuard-Management-Key: <management-key>

写请求还必须携带：

Idempotency-Key: <unique-operation-key>

production 环境禁止启用该接口。完整请求示例和稳定错误码请参阅 Week 2 管理 API 文档。

一键验收

第 2 周 Server 准入闭环

python -m scripts.week2_admission_smoke

该命令会自动验证：

1. 注册专属临时 Server；

2. 使用隔离会话发现真实 MCP 工具；

3. Scanner 产生高风险 Finding；

4. 未批准 Server 不进入运行时目录；

5. 人工仅启用只读工具；

6. Gateway 调用真实 stdio MCP Server；

7. 回读 tool.started → tool.succeeded 审计链；

8. 清理临时 Server、Scan、Tool、Run、Call 和 Audit 数据。

第 1 周 Agent 调用闭环

python -m scripts.week1_smoke

该命令会应用迁移、写入开发 seed、检查基础设施、发现 7 个工具、执行两个确定性 Agent 任务并验证审计链。

Agent 示例

示例 Agent 不需要 LLM Key：

python -m agent_demo.cli get_order --order-id ORD-N-1001
python -m agent_demo.cli read_faq

每次成功调用都会返回 trace_id。可以使用以下命令查询脱敏后的 PostgreSQL 审计链：

python -m scripts.show_trace <trace-id>

当前工具目录

bootstrap seed 默认批准以下 7 个 Mock 工具：

实际公开目录始终以 Registry 当前 approved 状态和工具 enabled 状态为准，而不是单纯信任静态配置。

错误返回

被拒绝的 MCP 调用只返回稳定错误码、安全消息、重试标志和 Gateway 生成的 trace 引用。例如：

{
  "error_code": "INVALID_TOOL_ARGUMENTS",
  "message": "Tool arguments are invalid.",
  "retryable": false,
  "trace_id": "<gateway-generated-uuid>"
}

错误响应不会包含 SQL、堆栈、后端命令、内部路径、Profile 连接配置、Scanner 原始异常或敏感输入。

质量检查

python -m ruff format --check .
python -m ruff check .
python -m mypy gateway mcp_servers agent_demo main.py scripts
python -m pip check
$env:AG_RUN_INFRASTRUCTURE_TESTS = "1"
python -m pytest
python scripts/test_run_gate.py docs/test-runs/week2_full_20260804/test-execution.json --pretty

第 2 周最终验收结果：

Week 2 专项测试：66 passed
全量测试：149 passed，1 skipped
Alembic：0002_registry_admission (head)
Docker PostgreSQL / Redis：healthy
Ruff / MyPy / pip check：passed
Coverage gate：PASS
Release gate：PASS（仅限当前 development/test 范围）

Windows 主机上唯一跳过项是需要操作系统符号链接权限的测试。

安全边界

baseline_allowlist 仍是临时的 development/test 用户授权控制。第 2 周已经实现 Server Registry、扫描、人工准入、enabled 工具选择和运行时 drift 防护，但尚未实现：

• JWT 用户认证；

• 身份感知的 tools/list；

• RBAC 与 ABAC；

• Policy Engine；

• 正式管理端身份和权限；

• 生产级远程 HTTP MCP 网络隔离。

production 环境会拒绝 baseline 模式和临时管理 API。正式身份与权限体系完成后，必须删除 baseline 用户授权路径，不能把它保留为生产后门。

.env.example 中的凭据全部是本地开发占位值，production 配置会拒绝已知 Demo Secret。PostgreSQL 和 Redis 当前只绑定回环地址；Gateway 容器化后应移除宿主机端口发布。

停止服务

停止本地服务但保留数据：

docker compose down

项目结构

gateway/          Gateway、审计、Registry、Scanner 和后续授权组件
mcp_servers/      Order、File、Notification 等 Mock MCP Server
agent_demo/       确定性 Agent 接入示例
config/           Mock Server allowlist 与服务端 Profile
policies/         后续策略即代码定义
frontend/         后续审批、审计和 Server 管理界面
tests/            单元、集成和安全回归测试
scripts/          Seed、诊断、Smoke 和回归门禁脚本
docs/             架构、威胁模型、开发计划、接入指南和完成报告

开发文档

• 第 0 周开发计划

• 第 0 周完成报告

• 第 1 周开发计划

• 第 1 周完成报告

• 第 2 周开发计划

• Scanner 兼容性报告

• 第 2 周完成报告

• MCP Server 接入指南