vishnushri19/agentic-api-security-framework

# Agentic API 安全治理框架 将 F5 WAAP 应用于 MCP / AI-agent API 流量。完整项目包括：项目章程、 架构、可用的检测引擎（已通过模拟及真实 MCP 协议流量验证）、 多 Agent Claude 分析流水线、 F5 策略构件、扩展的精确率/召回率基准测试，以及实时 仪表盘 —— 所有这些都构建在同一个检测引擎之上。 **📄 [阅读白皮书](WHITEPAPER.md)** — *“保护 Agentic 攻击面： 面向 MCP 和 AI-Agent API 流量的 F5 WAAP 治理框架。”* 其中的每一个数据都可以通过本 README 中的命令进行复现。 ## 亮点 - 在涵盖所有 5 条检测规则的 36 个事件标记基准测试中实现了 **100% 召回率，0 误报**，并作为每次 push 的 CI 门禁强制执行 - 检测准确率**在面对真实的 MCP JSON-RPC 协议流量时依然稳定**（基于官方 MCP SDK），而不仅仅是合成的模拟器 - 每一个发现都 1:1 映射到可部署的 **F5 AS3 声明或 iRule** —— 参见 [`f5-policy-artifacts/`](f5-policy-artifacts/) - 4-Agent Claude 流水线（**分流 → 根因分析 → 补救措施 → 报告生成**）对每一个 CRITICAL/HIGH 级别的发现进行分流处理，并附带记录在案、 可审计的推理轨迹 - 实时仪表盘将上述所有内容整合在一起 —— 流量 feed、检测结果、 Agent 推理、基准测试趋势 —— 尽收眼底 ## 目录 - [流量实况](#traffic-flow-live) - [项目结构](#project-structure) - [运行仪表盘（推荐全栈运行）](#run-the-dashboard-full-stack-recommended) - [仅运行 POC（无 UI）](#run-just-the-poc-no-ui) - [运行真实 MCP 协议实验室](#run-the-real-mcp-protocol-lab) - [运行多 Agent 分析流水线](#run-the-multi-agent-analysis-pipeline) - [运行测试](#run-the-tests) - [使用 Docker Compose 运行](#run-with-docker-compose) - [API 参考](#api-reference) - [延伸阅读](#further-reading) ## 流量实况

绿色的流量原封不动地直接发往下游 API；灰色的 镜像副本才是 WAF 层实际检查的内容；任何触发了 5 条检测规则之一的流量都会变红，并被转移进入 SIEM → 工单路径。这是一个端到端相同的规则引擎 —— POC、 真实 MCP 实验室、基准测试和仪表盘都通过未修改的 `poc/waf_detection_engine.py` 对流量进行评分。 ## 项目结构 ``` agentic-api-security-framework/ ├── PROJECT_CHARTER.md Scope, phases, success metrics ├── ARCHITECTURE.md System design + traffic flow ├── assets/ Animated SVG diagrams embedded in this README ├── poc/ Standalone simulator + detection engine (first-stage signal generator) │ ├── mcp_traffic_simulator.py │ ├── waf_detection_engine.py │ ├── run_demo.py │ ├── tests/ pytest suite (recall + false-positive checks) │ └── sample_output/ ├── mcp_layer/ Real MCP server/client (official MCP SDK) — genuine JSON-RPC │ │ traffic against the unchanged detection engine │ ├── mcp_server.py │ ├── client_agents.py │ └── run_lab.py ├── agents/ Multi-agent Claude pipeline │ ├── triage_agent.py Severity/priority + false-positive triage │ ├── root_cause_agent.py Why it happened, with a confidence level │ ├── remediation_agent.py Proposed F5 AS3/iRule diff │ ├── report_writer_agent.py Anonymized incident summary │ ├── ticketing.py GitHub Issues (dry-run by default) │ └── pipeline.py Chains all of the above; logs the reasoning trail ├── benchmark/ ~30-incident labeled corpus + precision/recall report │ ├── scenarios.py │ ├── run_benchmark.py │ └── tests/ ├── backend/ Flask API wrapping the detection engine + agent outputs │ ├── app.py │ └── data_engine.py ├── frontend/ Dashboard (vanilla HTML/CSS/JS, Chart.js — vendored, no CDN) │ ├── index.html │ ├── styles.css │ └── app.js ├── f5-policy-artifacts/ Real F5 config mapped to each finding │ ├── agentic_api_waf_policy.as3.json │ ├── mcp_traffic_irule.tcl │ └── README.md ├── docker-compose.yml backend + frontend + one-shot mcp-lab job └── .github/workflows/ci.yml Runs the pytest suites on every push ``` ## 运行仪表盘（推荐全栈运行） 需要 Python 3.9+。 ``` cd backend pip install -r requirements.txt python3 app.py ``` 然后在浏览器中打开 **http://localhost:5050**。 您将看到： - **实时流量 feed** — `tail -f` 风格的模拟 MCP/agent API 事件流，按严重程度进行颜色编码 - **按严重程度 / 规则划分的检测结果** — 由 `/api/summary` 驱动的环形图和柱状图 - **检测结果表** — 支持过滤，点击任意行展开即可查看 OWASP 映射、F5 控制措施、**工单状态标签**，以及（如果 已运行 `agents/pipeline.py`）完整的 **Agent 推理轨迹** — 分流 → 根因分析 → 补救措施 → 工单 - **Agent 风险画像** — 根据发现数量得出的单 Agent 风险评分 - **检测基准测试**面板 — 显示上次运行 `benchmark/run_benchmark.py` 后 每条规则的精确率/召回率/误报率，以及多次运行的召回率趋势 迷你图 - **重新运行模拟** — 实时重新生成流量并重新评分，无需 重新加载页面 后端直接为前端提供服务（同源，无需 CORS），并 复用 `poc/waf_detection_engine.py` 中的确切检测逻辑 —— 下面的 每一层（真实 MCP 流量、Agent 流水线、基准测试）都运行 **相同且未修改的规则引擎**；没有任何东西替代它。 ## 仅运行 POC（无 UI） ``` cd poc python3 run_demo.py cat sample_output/detection_report.md ``` ## 运行真实 MCP 协议实验室 针对真实的 MCP 服务器驱动真实的 MCP JSON-RPC 流量（官方 `mcp` Python SDK，stdio 传输），然后针对生成的日志运行完全相同的检测 规则 —— 证明检测能力并非 合成生成器的产物。 ``` pip install mcp cd mcp_layer python3 run_lab.py cat sample_output/mcp_detection_report.md ``` ## 运行多 Agent 分析流水线

针对每一个 CRITICAL/HIGH 级别的发现，将四个 Claude Agent 串联起来：**分流** （严重性/优先级评估 + 误报过滤） → **根因分析**（为何 发生，并附带置信度水平） → **补救措施**（提议的 F5 AS3/iRule 差异） → **报告生成**（为整个批次生成一份匿名的 事件摘要）。记录每个 Agent 的完整响应 —— 包括其 思考/推理文本 —— 以便仪表盘能够针对每个发现展示“系统为何 标记此项”的轨迹。 需要您的环境中配置了 `ANTHROPIC_API_KEY`。 ``` pip install -r agents/requirements.txt export ANTHROPIC_API_KEY=sk-ant-... # never commit this python3 agents/pipeline.py ``` 生成 `agents/sample_output/reasoning_trail.json`（由仪表盘的 Agent 推理面板和工单状态列读取）以及 `agents/sample_output/incident_report.md`。 模型默认为 `claude-sonnet-5`；可使用 `AGENT_MODEL` 覆盖。 ### 创建工单 `agents/ticketing.py` 会为每一个非误报的 CRITICAL/HIGH 级别发现创建一个 GitHub Issue，并附带补救 Agent 提议的修复方案。 **默认进行空运行 (Dry-run)** — 除非您主动开启，否则不会调用 GitHub API： ``` export TICKET_DRY_RUN=false export GITHUB_TOKEN=ghp_... export GITHUB_REPO=your-org/your-repo python3 agents/pipeline.py ``` ## 运行测试 ``` # 原始 5 场景 POC 套件（召回率 + 误报防护） cd poc && pip install -r requirements-dev.txt && python3 -m pytest tests/ -v # 扩展的约 30 事件 benchmark 套件（100% 召回率 / 0 FP 门禁） python3 -m pytest benchmark/tests -v # 完整的 precision/recall/false-positive 报告（按规则），外加 OWASP 覆盖盲区 python3 benchmark/run_benchmark.py cat benchmark/sample_output/benchmark_report.md ``` CI (`.github/workflows/ci.yml`) 会在每次 push 时运行两个 pytest 套件。 `agents/` 流水线不在 CI 中，因为它需要提交 API 密钥 — 请改用真实的密钥手动对其进行冒烟测试。 ## 使用 Docker Compose 运行 ``` docker compose up backend frontend # 按需执行的单次真实 MCP 协议实验室任务： docker compose --profile lab up mcp-lab ``` `backend` 在 `:5050` 提供仪表盘服务；`frontend` 是一个独立的 nginx 静态主机，在 `:8080` 提供相同的 UI（后端也直接提供服务 — 这是为了适应“将前端作为独立服务”的部署形态）。 在执行 `docker compose up` 之前，如果在 容器内部您想要运行 Agent 流水线 / 真实的工单创建功能，请在您的 shell 或本地的 `.env`（未提交）文件中设置 `ANTHROPIC_API_KEY`、`TICKET_DRY_RUN`、`GITHUB_TOKEN`、`GITHUB_REPO`。 ## API 参考 | Endpoint | 方法 | 描述 | |---|---|---| | `/api/health` | GET | 存活检查 | | `/api/summary` | GET | 按严重程度/规则统计，Agent 数量 | | `/api/findings` | GET | 所有检测结果；可选的 `?severity=` `?rule=` 过滤器 | | `/api/traffic` | GET | 原始流量事件；可选的 `?limit=` | | `/api/agents` | GET | 每个 Agent 的事件/发现数量 + 风险评分 | | `/api/simulate` | POST | 重新生成流量并重新运行检测 | | `/api/reasoning-trail` | GET | 上次 `agents/pipeline.py` 运行中针对每个发现的分流/根因分析/补救措施/工单轨迹 | | `/api/benchmark` | GET | 最新的按规则划分的精确率/召回率/误报结果 | | `/api/benchmark-history` | GET | 每次基准测试运行的整体召回率（趋势数据） | ## 延伸阅读 | 文档 | 内容介绍 | |---|---| | [`WHITEPAPER.md`](WHITEPAPER.md) | 旗舰级文章 — 包含问题描述、方法论、验证结果和客观的差距列表，并以本仓库的实际输出作为证据 | | [`PROJECT_CHARTER.md`](PROJECT_CHARTER.md) | 范围、阶段交付状态、成功指标 | | [`ARCHITECTURE.md`](ARCHITECTURE.md) | 组件级设计和流量流向 | | [`f5-policy-artifacts/README.md`](f5-policy-artifacts/README.md) | 每条检测规则如何映射到真实的 AS3/iRule 控制措施，以及已知的部署差距 | | [`CONTRIBUTING.md`](CONTRIBUTING.md) | 项目布局、设置及变更的基本规则 | | [`LICENSE`](LICENSE) | MIT |

标签：AI代理, AMSI绕过, API安全, F5, JSON输出, MCP, WAAP, 威胁检测, 安全规则引擎, 版权保护, 自动化运维, 逆向工具