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、审计或准入状态异常时默认拒绝调用。
- 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默认地址：
| 服务 | 地址 |
|---|---|
| Gateway MCP | http://127.0.0.1:8000/mcp/ |
| 健康检查 | http://127.0.0.1:8000/health/ready |
| PostgreSQL | 127.0.0.1:55432 |
| Redis | 127.0.0.1:56379 |
MCP 地址末尾的 / 是挂载路由的一部分，客户端连接时必须保留。
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 接入与准入指南。
第 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 文档。
python -m scripts.week2_admission_smoke该命令会自动验证：
- 注册专属临时 Server；
- 使用隔离会话发现真实 MCP 工具；
- Scanner 产生高风险 Finding；
- 未批准 Server 不进入运行时目录；
- 人工仅启用只读工具；
- Gateway 调用真实 stdio MCP Server；
- 回读
tool.started → tool.succeeded审计链； - 清理临时 Server、Scan、Tool、Run、Call 和 Audit 数据。
python -m scripts.week1_smoke该命令会应用迁移、写入开发 seed、检查基础设施、发现 7 个工具、执行两个确定性 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 工具：
| Server | 工具 | 风险等级 | 副作用 |
|---|---|---|---|
| File | file.delete_file |
critical | 有，临时副本 |
| File | file.list_directory |
low | 无 |
| File | file.read_file |
low | 无 |
| Notification | notify.draft_message |
low | 无 |
| Notification | notify.send_message |
high | 有，内存 outbox |
| Order | order.get_order |
low | 无 |
| Order | order.refund_order |
high | 有，进程内模拟 |
实际公开目录始终以 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 downgateway/ 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/ 架构、威胁模型、开发计划、接入指南和完成报告