# AgentGuard

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

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

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

## 项目解决的问题

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

- 用户和 Agent 是否有权发现和调用该工具；
- 参数是否越权、包含 Secret 或危险文件路径；
- 策略是否应当允许、拒绝、转换参数或要求人工审批；
- 工具输出中的不可信内容是否诱导后续敏感读取或数据外发；
- 当前任务是否超过工具调用次数或风险预算；
- 整个过程是否可以通过 trace_id 进行脱敏审计回放。

## 主要能力

| 模块 | 内容 |
| --- | --- |
| MCP Gateway | 代理并聚合 Order、File、Notification 三个 Mock MCP Server |
| 身份与授权 | JWT、RBAC、ABAC、Agent allowlist；发现与每次执行调用均重新授权 |
| 策略引擎 | YAML Policy-as-Code：allow、deny、transform、require_approval；草稿、评审、发布与重启恢复 |
| 风险控制 | Secret、敏感路径、退款阈值、调用次数、风险预算、超时 |
| 人工审批 | 参数编辑、批准/拒绝、单次执行；恢复时以原请求人的当前身份重新校验 |
| 不可信内容 | Prompt Injection、Secret/PII 输出标签与跨 Tool 副作用、外发阻断 |
| MCP Registry | 扫描、人工准入、Catalog 漂移失效、运行时健康/完整性巡检 |
| 审计与评测 | PostgreSQL 哈希链 Trace、50 条版本化攻防/可用性语料 |

## 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。

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

| 服务 | 地址 |
| --- | --- |
| Gateway 健康检查 | http://127.0.0.1:8000/health/ready（若 `.env` 设置 `AG_GATEWAY_PORT=8001`，则为 8001） |
| MCP Streamable HTTP 入口 | http://127.0.0.1:8000/mcp/ |
| Dashboard 控制台 | http://127.0.0.1:8080 |
| PostgreSQL | 127.0.0.1:55432 |
| Redis | 127.0.0.1:56379 |

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

~~~powershell
docker compose logs -f gateway
~~~

停止服务、保留数据：

~~~powershell
docker compose down
~~~

## 本地源码开发

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

~~~powershell
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 集成测试）

~~~powershell
$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、策略、风险和审批校验；前端选择身份不能绕过这些控制。

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

~~~powershell
$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` 中设置：

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

3. 重建并启动服务：

~~~powershell
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 文档](https://www.alibabacloud.com/help/en/model-studio/base-url)。

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

### 运行示例 Agent

~~~powershell
./.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

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

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

### 运行策略与评测演示

~~~powershell
./.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 启用本地审批台：

~~~text
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 脚本](docs/demo-script.md)。

## 配置说明

### 生产 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](.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 比对：

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

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

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

## 测试与质量检查

~~~powershell
./.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、类型检查、单元测试和评测语料校验。

## 项目结构

~~~text
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、多租户、密钥管理、网络隔离和持久化任务存储。

## 进一步阅读

- [架构说明](docs/architecture.md)
- [威胁模型](docs/threat-model.md)
- [安全边界](docs/security-boundaries.md)
- [策略编写指南](docs/policy-authoring.md)
- [MCP Server 接入指南](docs/server-onboarding.md)
- [演示脚本](docs/demo-script.md)
- [面试要点](docs/interview-notes.md)