AgentGuard

AgentGuard 是面向 MCP Agent 的运行时安全网关。在工具发现、调用、审批恢复、审计和评测之间提供统一控制点。项目中的订单、文件、通知服务都是 Mock MCP Server，不连接真实支付、邮件或云资源。

初次了解项目，建议先阅读 项目介绍书：其中解释了项目用途、令牌的含义、浏览器操作步骤与技术实现。

关于下一阶段的企业登录、身份认证与安全管理后台设计，见身份认证与安全管理后台整合方案。

项目解决的问题

当 Agent 想调用工具时，Gateway 会强制检查：

• 用户和 Agent 是否有权发现和调用该工具；

• 参数是否越权、包含 Secret 或危险文件路径；

• 策略是否应当允许、拒绝、转换参数或要求人工审批；

• 工具输出中的不可信内容是否诱导后续敏感读取或数据外发；

• 当前任务是否超过工具调用次数或风险预算；

• 整个过程是否可以通过 trace_id 进行脱敏审计回放。

Related MCP server: mcp-policy-gateway

主要能力

P0 运行时安全闭环

当前版本已经实现以下强制控制；它们发生在后端 Gateway 中，不能通过 Dashboard、Agent 提示词或跳过 tools/list 来绕过：

1. 执行时统一授权：Tool Discovery 只负责最小化暴露工具；每个 tools/call 仍会重新检查 User、Agent、Session、RBAC、ABAC、Agent allowlist、MCP Server 准入和 YAML Policy。

2. 审批不提升权限：审批记录绑定参数并只能消费一次。恢复执行时会读取原始请求人的当前 User/Agent/Session 状态，重新执行 Schema、Server 准入、执行授权、Policy 和 Risk 校验；审批人不会因为自己的经理角色而替请求人获得额外权限。

3. 持久化策略发布：本地 policies/ 是启动时的 Bootstrap Policy。管理员完成草稿、评审、发布后，已发布版本保存到 PostgreSQL；Gateway 重启时会加载最新已发布版本。

4. 不可信数据流保护：Tool 结果默认不可信。检测到提示词注入式指令后，同一 Agent Run 的后续副作用调用会被阻断；检测到 Secret 或 PII 输出后，向外部收件人的消息发送会被阻断。审计中只保存信号和摘要，不保存敏感原文。

5. MCP 运行时完整性：每次调用会验证 Server 当前准入状态和 Tool Metadata；健康巡检会主动 tools/list 并比对已批准 Catalog Digest。发现 Tool 描述、Schema 或目录漂移时，Server 会被撤销准入并禁用。

技术栈

Python 3.12、FastAPI、MCP Python SDK、LangGraph、PostgreSQL、Redis、SQLAlchemy、Alembic、Docker Compose、pytest、ruff、mypy。

快速启动

前提：Docker Desktop。

Copy-Item .env.example .env
docker compose up --build -d
docker compose ps
Invoke-RestMethod http://127.0.0.1:8000/health/ready

打开 Dashboard 后，选择一个演示身份即可在浏览器内执行 Agent 任务、处理审批、回放 Trace 和查看评测；开发 JWT 由服务端以 HttpOnly Cookie 保存，不再需要在页面或终端中复制粘贴。查看日志：

docker compose logs -f gateway

停止服务、保留数据：

docker compose down

本地源码开发

前提：Python 3.12、Docker Desktop，且已安装开发依赖。

docker compose up -d postgres redis
./.venv/Scripts/python.exe -m alembic upgrade head
./.venv/Scripts/python.exe -m scripts.seed_dev_data
./.venv/Scripts/python.exe -m uvicorn main:app --reload

如何使用

脚本 JWT（仅 API 集成测试）

$token = ./.venv/Scripts/python.exe -m scripts.issue_dev_token

在 Dashboard 中操作

1. 打开 http://127.0.0.1:8080，在登录页选择“支持人员”。服务端会签发一个 15 分钟有效的 HttpOnly 会话 Cookie，页面不会显示或保存 JWT。

2. 选择“查询订单”或“读取 FAQ”，点击“运行安全任务”。返回结果会显示真实 trace_id。

3. 点击右上角“退出”后，可选择“经理”或“管理员”重新登录，再进入审批中心处理待审批请求；不再需要粘贴经理令牌。

开发身份仅用于 development/test 环境。所有请求仍会经过后端 RBAC、ABAC、策略、风险和审批校验；前端选择身份不能绕过这些控制。

如需签发经理身份的测试令牌，可使用：

$managerToken = ./.venv/Scripts/python.exe -m scripts.issue_dev_token `
  --subject demo-manager-north `
  --session-id 30000000-0000-4000-8000-000000000003

启用 DashScope Qwen 真实模型 Agent

Dashboard 中的“Qwen 真实模型 Agent”会让 Qwen 理解自然语言、从 Gateway 提供的最小工具目录中选择工具，并把每一次工具调用交回 AgentGuard 做身份验证、策略、风险、审批和审计。Qwen 不会直接访问订单、文件或通知服务。

1. 在阿里云百炼创建 API Key；不要把 Key 提交到 Git 仓库或发送到聊天中。

2. 在本机 .env 中设置：

AG_DASHSCOPE_API_KEY=你的 DashScope API Key
AG_DASHSCOPE_MODEL=qwen-plus

3. 重建并启动服务：

docker compose up --build -d gateway dashboard

4. 打开 Dashboard，选择“支持人员”进入，在“Qwen 真实模型 Agent”中输入例如“帮我查询订单 ORD-N-1001 的状态和可退款余额”，再点击“让 Qwen 安全执行”。

DashScope 使用 OpenAI 兼容接口；默认北京地域地址为 https://dashscope.aliyuncs.com/compatible-mode/v1，如果你的 Key 属于其他地域或工作空间，请按阿里云文档替换 AG_DASHSCOPE_BASE_URL。详见阿里云 Model Studio Base URL 文档。

Dashboard 仅在 development/test 环境挂载；它通过 Nginx 将 /api 转发到 Gateway，浏览器不会直接连接 PostgreSQL、Redis 或 MCP Server。

运行示例 Agent

./.venv/Scripts/python.exe -m agent_demo.cli get_order --order-id ORD-N-1001 --token $token
./.venv/Scripts/python.exe -m agent_demo.cli read_faq --token $token

示例 Agent 只通过 Gateway 调用工具。成功响应带有 trace_id。

回放审计 Trace

./.venv/Scripts/python.exe -m scripts.show_trace <trace-id>

输出只包含脱敏后的参数/结果摘要、策略和审计事件。

运行策略与评测演示

./.venv/Scripts/python.exe -m scripts.week3_identity_smoke
./.venv/Scripts/python.exe -m scripts.week4_policy_smoke
./.venv/Scripts/python.exe -m scripts.run_evaluation --output-dir reports

评测报告保存为 reports/evaluation-report.json 与 reports/evaluation-report.md。

人工审批演示

大额退款会返回 APPROVAL_REQUIRED 和 approval_id。manager/admin 可编辑金额、批准并执行；恢复的 Agent 任务只使用已经批准的参数。执行前 Gateway 会重新验证原始请求人的 User、Agent、Session、Tool 权限、Server 准入、Schema、Policy 和 Risk；如果请求人已经禁用、会话过期或规则现在拒绝该操作，则不会执行。

审批记录是一次性消费的：成功恢复后不能重放。审批人与请求人是不同角色，但审批不是提升请求人权限的方式。

在 .env 启用本地审批台：

AG_MANAGEMENT_API_ENABLED=true
AG_MANAGEMENT_API_KEY=<至少 32 位随机值>

重启 Gateway 后，访问 http://127.0.0.1:8000/approvals/ 。页面需要管理 API Key 和 manager/admin Bearer JWT，仅允许 development/test 环境使用。完整演示见 Demo 脚本。

配置说明

生产 OIDC/SSO

生产环境使用 IdP 签发的短期 OIDC Bearer Token，Gateway 通过 JWKS 校验签名、Issuer、Audience、时效和必需的 agent_id、session_id 绑定声明。必须设置 AG_OIDC_ENABLED=true，并完整提供 AG_OIDC_ISSUER、AG_OIDC_AUDIENCE、AG_OIDC_JWKS_URL、AG_OIDC_CLIENT_ID、AG_OIDC_AUTHORIZATION_ENDPOINT、AG_OIDC_REDIRECT_URI 与 AG_SERVICE_AGENT_ISSUER。

生产环境会拒绝启动，除非上述 OIDC 与服务 Agent 签发方配置完整；同时开发身份切换、开发 JWT、共享管理密钥 API 和安全管理开发入口均不可访问。真实 IdP 的授权码回调地址、MFA/WebAuthn 策略与工作负载身份需在企业 IdP（如 Keycloak、Entra ID、Auth0）中按本组织租户配置，不能使用本项目的演示凭证代替。

主要配置位于 .env，模板见 .env.example：

• AG_POSTGRES_*、AG_REDIS_*：基础设施连接；

• AG_JWT_*：开发 JWT 签名和校验；

• AG_TOOL_TIMEOUT_SECONDS：单次工具调用超时；

• AG_MAX_TOOL_CALLS_PER_RUN、AG_MAX_RISK_BUDGET_PER_RUN：任务级限制；

• AG_REFUND_APPROVAL_THRESHOLD_MINOR：退款审批阈值；

• AG_MANAGEMENT_API_*：开发管理/审批接口。

查看 MCP Server 健康与完整性

/health/ready 除 PostgreSQL、Redis 和 Gateway 进程外，还会返回已批准 MCP Server 的健康状态。Gateway 会对每个 Server 进行工具目录探测与 Catalog Digest 比对：

Invoke-RestMethod http://127.0.0.1:8000/health/ready | ConvertTo-Json -Depth 5

出现 unhealthy、pending_review 或 Registry degraded 时，不应继续把该 MCP Server 视为可执行依赖；请在安全管理台中重新扫描、审核并批准。

不要把 .env 中的开发密钥用于共享或生产环境。

测试与质量检查

./.venv/Scripts/python.exe -m ruff format --check gateway mcp_servers agent_demo scripts tests main.py
./.venv/Scripts/python.exe -m ruff check gateway mcp_servers agent_demo scripts tests main.py
./.venv/Scripts/python.exe -m mypy gateway mcp_servers agent_demo scripts main.py
$env:AG_RUN_INFRASTRUCTURE_TESTS='1'; ./.venv/Scripts/python.exe -m pytest -q

CI 会执行格式、lint、类型检查、单元测试和评测语料校验。

项目结构

gateway/        Gateway、身份、策略、风险、审批、审计、Registry
mcp_servers/    订单、文件、通知 Mock MCP Server
agent_demo/     LangGraph 示例 Agent
policies/       YAML Policy-as-Code
scripts/        Seed、Trace、Smoke、评测脚本
tests/          单元、集成与安全回归测试
docs/           架构、威胁模型、使用与开发文档

安全边界

• 这是参考实现，不承诺 100% 防 Prompt Injection；

• 风险检测与内容检测提供可解释信号；权限、参数校验、审批、数据流阻断与执行边界才是强制控制；

• 跨 Tool 数据流保护目前覆盖已注册 Tool 的副作用标识和 Notification 外部收件人；新增外发型 MCP Tool 时，应同步声明其副作用/外发属性并补充策略与回归用例；

• 审批台和管理接口仅供 development/test；

• LangGraph 当前使用内存 checkpoint，重启后恢复需要持久化 checkpointer；

• 生产还需要 SSO、多租户、密钥管理、网络隔离和持久化任务存储。

进一步阅读

• 架构说明

• 威胁模型

• 安全边界

• 策略编写指南

• MCP Server 接入指南

• 演示脚本

• 面试要点