Manuelvillarvieites/Agentic-Pentesting-Framework

# 智能体渗透测试框架 (APF) 一个用于自动化渗透测试的多智能体 LLM 框架。APF 通过一个与模型无关的 Python orchestrator 驱动一个 7 阶段的 pipeline —— 策略、侦察、扫描、分支拆分、漏洞利用、验证、报告 —— 该 orchestrator 可以与任何兼容 LiteLLM 的 LLM 以及任何通过 MCP 暴露的安全工具链进行交互。 *学士论文（苏黎世应用科学大学 (ZHAW)，2026年）。研究问题：与无引导的单智能体执行相比，结构化的、阶段驱动的工作流引导是否能提升 LLM 进行端到端渗透测试的有效性和 token 效率，并且这种优势是否在能力差异巨大的模型中依然成立 —— 从较弱的开源权重模型 (Gemma 4 26B/31B, Llama 3.3) 到前沿的闭源模型 (Claude Opus 4.7)？* ``` orchestrator.py │ ├── Phase 1 Strategy → storage//session_state.json ├── Phase 2 Reconnaissance → storage//ptt.json ├── Phase 3 Scanning → storage//ptt_extended.json ├── Phase 4 PTT Splitting → storage//ptt_branches.json ├── Phase 5 Exploitation → storage//branch_N/execution.json (parallel) ├── Phase 6 Validation → storage//findings.json (parallel) └── Phase 7 Reporting → storage//report.json ``` 每次运行都会在 `storage/` 下生成一个带有新时间戳的文件夹，并在 `results//report.md` 生成一份确定性的 markdown 总结。完整的 pipeline、agent 格式和 JSON 契约记录在 [docs/architecture.md](docs/architecture.md) 中。 ## 目录 - [快速开始](#quick-start) - [复现论文消融实验](#reproduce-the-thesis-ablations) - [内容索引](#where-to-find-what) - [技术栈](#tech-stack) ## 快速开始 **1 — 克隆并包含子模块** (HexStrike + validation-benchmarks) ``` git clone --recursive https://github.com/Manuelvillarvieites/Agentic-Pentesting-Framework.git cd Agentic-Pentesting-Framework # 如果你已经在没有使用 --recursive 的情况下进行了 clone：git submodule update --init --recursive ``` **2 — 修补上游 XBEN compose-file bug** (一次性操作，幂等) ``` python3 scripts/patch_benchmarks.py ``` **3 — Python 依赖** ``` python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt pip install fastmcp requests # host-side MCP adapter deps ``` **4 — API 密钥** (仅限你使用的提供商) ``` cp docker/.env.example docker/.env # 然后编辑 docker/.env ``` **5 — 启动 Docker 技术栈** (LiteLLM + HexStrike-on-Kali) ``` docker compose -f docker/docker-compose.yml up -d ``` **6 — 验证** ``` python3 scripts/orchestrator.py 127.0.0.1 --dry-run curl http://localhost:8889/health # → {"status": "ok"} ``` **7 — 启动一个 XBEN 基准测试目标** (Easy10 LFI 示例，在笔记本上约需 5 分钟) ``` cd external/validation-benchmarks/benchmarks/XBEN-019-24 make build && make run # build (injects the FLAG) + start the container # `docker compose ps` 显示一行 — web 应用将端口 80 发布到一个随机的 host port： # xben-019-24-lfi_static_resource-1 ... 0.0.0.0:49280->80/tcp, [::]:49280->80/tcp # ↑ 这个数字 # 将该 host port 自动提取到 XBEN_PORT 中（照原样复制）： export XBEN_PORT=$(docker compose ps | grep -oE '0\.0\.0\.0:[0-9]+->80/tcp' | head -1 | cut -d: -f2 | cut -d- -f1) echo "Benchmark is on http://localhost:${XBEN_PORT}" cd - ``` **8 — 针对该基准测试运行渗透测试** ``` python3 scripts/orchestrator.py host.docker.internal:${XBEN_PORT} \ --allocation weighted --model claude-sonnet-4-6 ``` 完整的设置指南详见 [docs/setup.md](docs/setup.md)。APF 支持的所有命令（按用例分组）详见 [docs/commands.md](docs/commands.md)。 ## 复现论文消融实验 六个主要的 APF 与基线对比扫描 (Claude Opus 4.7, Llama 3.3 70B, Gemma 4 26B × Easy10, Harder20)。有关前置条件、仅 APF / 阶段组合 / 仅基线的后续操作、结果检查命令，以及每次扫描与论文表格的映射关系，请参见 [docs/reproducibility.md](docs/reproducibility.md)。 **设置 Harder20 变量** (在每个 shell 中粘贴一次) ``` export HARDER20="XBEN-002-24,XBEN-006-24,XBEN-009-24,XBEN-029-24,XBEN-030-24,XBEN-034-24,XBEN-035-24,XBEN-038-24,XBEN-039-24,XBEN-040-24,XBEN-054-24,XBEN-056-24,XBEN-057-24,XBEN-060-24,XBEN-069-24,XBEN-077-24,XBEN-078-24,XBEN-080-24,XBEN-084-24,XBEN-097-24" ``` **1 — Claude Opus 4.7 / Easy10** ``` python3 scripts/benchmark_sweep.py -e apf-vs-baseline --model claude-opus-4-7 ``` **2 — Claude Opus 4.7 / Harder20** ``` python3 scripts/benchmark_sweep.py -e apf-vs-baseline --model claude-opus-4-7 --benchmarks $HARDER20 ``` **3 — Llama 3.3 70B / Easy10** (ZHAW Ollama，需要 VPN) ``` python3 scripts/benchmark_sweep.py -e apf-vs-baseline --model llama3.3 ``` **4 — Llama 3.3 70B / Harder20** ``` python3 scripts/benchmark_sweep.py -e apf-vs-baseline --model llama3.3 --benchmarks $HARDER20 ``` **5 — Gemma 4 26B (本地 Ollama) / Easy10** ``` python3 scripts/benchmark_sweep.py -e apf-vs-baseline --model ollama/gemma4:26b ``` **6 — Gemma 4 26B (本地 Ollama) / Harder20** ``` python3 scripts/benchmark_sweep.py -e apf-vs-baseline --model ollama/gemma4:26b --benchmarks $HARDER20 ``` ## 内容索引 | 文档 | 用途 | |----------|---------| | [report/Thesis.pdf](report/Thesis.pdf) | 学士论文（95 页）。LaTeX 源码位于 [report/](report/)，可使用 `latexmk -pdf Thesis.tex` 重新构建。 | | [docs/setup.md](docs/setup.md) | 安装：Python, Docker, MCP, API 密钥 | | [docs/commands.md](docs/commands.md) | 按用例分组的全部命令 (verify, pentest, sweeps, inspect, stop) | | [docs/reproducibility.md](docs/reproducibility.md) | 论文消融实验指南 —— 可直接复制粘贴的扫描命令 | | [docs/architecture.md](docs/architecture.md) | 7 阶段 pipeline、agent 格式、skill registry、分配策略 | | [docs/llm-config.md](docs/llm-config.md) | 切换 LLM、LiteLLM、使用 `gemma4:26b` 的本地 Ollama、Llama 3.3 说明 | | [docs/benchmarks.md](docs/benchmarks.md) | XBOW 基准测试 —— Easy10 / Harder20 定义，各目标设置 | | [docs/development.md](docs/development.md) | 模块级别的源码参考，自定义循环 (custom-loop) 原理，开发待办事项 | | [docs/diagrams/](docs/diagrams/) | 论文插图（架构概览、运行时序列图）的可编辑 `.drawio` 源文件和 `.png` 导出文件 —— 相同的 PNG 图片也已嵌入报告中 | | [docs/research/](docs/research/) | 论文产出物 —— 消融实验报告、评估指标、早期图片草稿 | | [docs/meeting-notes/](docs/meeting-notes/) | 每周导师会议纪要（2026年2月至5月），在报告附录中被引用 | | [docs/BA_Timeplan.pdf](docs/BA_Timeplan.pdf) | 项目甘特图时间表（同样嵌入在报告附录中） | | [AGENTS.md](AGENTS.md) | Agent 参考：`task_response` schema、攻击快速参考、FLAG 模式 | | [CLAUDE.md](CLAUDE.md) | 编辑此仓库时 Claude Code 使用的项目规范 | ## 技术栈 | 组件 | 选择 | |-----------|--------| | Orchestrator | Python 3.11, `scripts/orchestrator.py` | | LLM 代理 | LiteLLM (Docker) 运行于 `http://localhost:4000` | | 默认 LLM | 通过 ZHAW Ollama 使用 Llama 3.3 70B（无需 API 密钥）；在更强配置下使用 `claude-sonnet-4-6` | | 复现模型 | 通过本地 Ollama 使用 `ollama/gemma4:26b` | | 安全工具 | HexStrike MCP —— Kali Linux 工具包（约 150 个工具），Docker container 运行于 `:8889` | | Web 交互 | Playwright MCP (通过 `npx` 的 stdio) | | 工具路由 | `MCPClientManager` —— 动态发现，零硬编码工具 | ## 另请参阅 - [文档索引](docs/README.md) —— 设置、命令、架构和基准测试的完整指南 - [AGENTS.md](AGENTS.md) —— agent 技术参考 (`task_response` schema, FLAG 模式) - [CLAUDE.md](CLAUDE.md) —— 编辑此仓库时使用的 Claude Code 项目规范

标签：AI风险缓解, DLL 劫持, MCP协议, Python, Web报告查看器, XXE攻击, 反取证, 多智能体, 大语言模型, 安全评估, 实时处理, 密码管理, 无后门, 特征检测, 自动化渗透测试, 请求拦截, 逆向工具