Proteus · 千面 — 多模式渗透测试 Agent

测试基线只在《当前状态 · 测试》一处维护（带实测日期）；徽章只留自更新的 CI，不放会漂移的用例计数。

一个内核，千种面孔。 Proteus（普罗透斯）：希腊神话中的海上老人，可随心变换任意形态——多模式切换的完美隐喻。 千面：一个内核，适配千种作战场景。

预览

架构总览

30 秒演示（真实作战记录渲染：pentest-standard 侦察任务 + ctf-crypto 编码链解题，含权限闸门拦截与证据链收口）

仓库命名：proteus-agent（GitHub xiabai2008/proteus-agent，命名空间已核验可用，2026-09-17）

Related MCP server: pyntra

快速开始

0）环境准备：复制 .env.example 为 .env，填入 LLM 端点三键（PENTEST_LLM_BASE_URL / API_KEY / MODEL，OpenAI 兼容）与本机路径（PENTEST_WS / PENTEST_TOOLS / PENTEST_PY312 / PENTEST_G07_ROOT，不填则对应外部工具自动降级跳过）。安装依赖：pip install -r requirements.txt（核心只有 PyYAML + pytest；可选能力见 requirements-optional.txt，档位表见本节末《环境与能力档位》）。想在 PATH 上用 penagent 命令：pip install -e .（只支持可编辑安装——modes/ 与 prompts/ 在包外，是运行前提）。

入口一 · CLI（日常主用）

# 起一个授权本地靶子
python examples/target.py --port 8080

# 渗透模式侦察任务（真 LLM 决策 + 证据链 + 反幻觉）
python -m penagent run --mode pentest-standard --target http://127.0.0.1:8080 \
    --objective "识别开放端口、Web 技术栈、敏感路径与信息泄漏"

# CTF 模式解题（题面由 examples/eval_ctf_solve.py 生成到 data/eval-ctf/）
python -m penagent run --mode ctf-crypto --target data/eval-ctf/encoding-chain.txt \
    --objective "解出 flag"

# 任务后复盘 → 技能沉淀（越用越准的关键一步）
python -m penagent reflect <mission_id>

# 预置技能种子（web 侦察的两条经验；幂等，写进模式记忆分区）
python -m penagent skills --seed --mode pentest-standard

# 查看经验库 / 作战记录 / 证据链校验 / 技能盲区
python -m penagent skills && python -m penagent missions
python -m penagent verify && python -m penagent gaps

# DSH 宿主会话审计桥：宿主侧每次工具调用（含目标动作裁决）并入独立证据链
python -m penagent dsh-sync --data data
python -m penagent dsh-sync --data data --flush-open   # 会话结束后冲刷未配对调用

# 能力评测：跑一遍看评分卡（可落盘、可跨版本对比）
python examples/benchmark.py --suite all          # CTF 33 题 + 演示靶 + 真实靶场 + 07 套件
python examples/benchmark.py --suite lab          # 真实靶场基线（DVWA / Juice Shop / sw-secure-lab）
python examples/benchmark.py --suite agent-lab    # agent 自主侦察真实靶场（真 LLM，分钟级，须显式点名）
python examples/benchmark.py --suite dsh-session  # 判定 DSH 宿主会话（读宿主桥证据链，离线）
python examples/benchmark.py --compare data/benchmark/baseline.json

入口二 · Web 控制台（模式选择 / 实时步骤流 / 证据链视图）

python web/server.py            # 默认 http://127.0.0.1:8770

入口三 · 挂到 deepseek-harness（复用沙箱 / 审批 / AgentTeams）

# preset 已在 dsh/.agent-presets/proteus，按 docs/DSH宿主接入指南.md 安装后：
dsh  # 会话内直接用自然语言下任务，工具以 mcp__proteus__* 出现

入口四 · 作为 MCP Server 被任意 LLM 客户端调用（Claude Code / Codex / OpenCode…）

python -m penagent mcp --targets 127.0.0.1

模式清单见 modes/（pentest-standard / ctf-web / ctf-crypto），知识检索（seckb 知识库）与外部工具（RayScan / Chameleon）按 penagent/mcp_servers.json 声明自动接入。

环境与能力档位（开源上手，2026-10-18 实测）

核心近乎零依赖：pip install -r requirements.txt（PyYAML + pytest）就够跑通全量机制测试，CI（Windows 3.12 / 3.13）正是在这个口径下全绿。往下每一档都是能力加码，缺了会自动降级并明确提示（工具"未注册/不可用"、容器不可用即拒绝执行），不会静默跑错。

可选 pip 包清单与"不装会少什么"逐条写在 requirements-optional.txt（torch / unicorn / zstandard / pwntools，另含不在 PyPI 的 RsaCtfTool 安装方式）。需要 node 的只有宿主插件烟雾测试 4 条。

两处非仓库可复现的构建输入（诚实声明）：

• CyberChef 服务端镜像的构建上下文是上游 clone（gchq/CyberChef-server，置于 data/repos/），按 docker/mcp/README.md 自建——tools/build_mcp_images.py 不覆盖它；

• 07 靶场（warfare 仿真包）是私有项目：把 PENTEST_G07_ROOT 指向自己的副本，否则 4 条评测用例自动跳过。

干净机器上的测试口径：环境相关用例会按缺失的档位自动跳过——两类典型是三组：容器真跑（Docker 离线即 skip）、靶场真扫（靶机未起即 skip）、可选依赖（torch / unicorn / zstandard / pwntools / node 各一组）。当前条数以《当前状态 · 测试》那一行为准（单一事实来源），CI 口径与"本机全齐"口径的差值就是上面这些类。skip 不等于通过：Docker 一上线曾立刻抓出 3 条从未执行过的死缺陷（见 docs/修复待办清单.md R-44），建议至少把档位 ③ 装上再采信自己的 skip 面。

一、项目定位

支持多模式切换的渗透测试 Agent：同一套内核，通过 ModeProfile（模式档案）在常规渗透测试模式、CTF 比赛模式等场景之间机制性切换——工具白名单、参数冻结、权限档位、预算策略、成功判定器全部随模式生效。

主推架构（方案 C 为主线 + 方案 D 为宿主层）：

宿主层（双入口，能力同一套）
  入口一 · 自有 CLI / Python SDK（独立运行，可进 CI）
  入口二 · DSH agent-preset 插件（白拿沙箱 / 审批 / Web UI）
        │
模式层 · ModeProfile（一等公民，本次新建的核心）
  persona / capability / permission / budget / scope / verifier / skills / sandbox
        │
内核层 · XPentest（已 fork 入仓 `penagent/` 包）
  ReAct 决策循环 · 证据链反幻觉 · 记忆与技能进化
        │
工具层 · MCP 统一注册（新增能力不改内核）
  RayScan · Chameleon · poxiao · ruoyi-scan · LogicHunt · 本地 70+ 二进制
        │
环境层 · 隔离与边界（模式可覆盖）
  Docker/WSL2 · 目标白名单硬校验 · 网络出口策略

两条硬规则：

1. 模式约束必须在工具执行前机制性生效（如 safe 模式下 nuclei: null 直接禁用），不能只写在提示词里靠模型自觉。

2. 可插拔 Verifier（成功判定器）是 CTF 与渗透模式的分水岭：CTF 挂 flag_regex，渗透挂 evidence_chain。

二、为什么叫 Proteus · 千面

避开"破晓"（已被 poxiao 与 dawnforge-pentest 同时占用，本就存在撞名）。

三、路线决策（2026-09-17 定稿）

依据你自己定下的原则（《红队平台自建方案》）：手脚不依赖大脑也能跑——dsh 挂了，CLI 照常能用。

四、目录导航

proteus-agent/
├── AGENTS.md                                  AI 会话唯一事实来源（硬规则/环境约定/模式规范）
├── README.md                                  本文件（项目主页）
├── LICENSE / THIRD_PARTY.md                   许可与第三方组件清单（分发镜像前必读）
├── CONTRIBUTING.md / SECURITY.md              贡献指南 / 安全策略（含私密报告渠道）
├── requirements.txt / requirements-optional.txt   核心依赖 / 可选能力清单
├── pyproject.toml                             打包元数据（只支持可编辑安装 pip install -e .）
├── penagent/                                  内核包（fork 自 XPentest，独立成仓）
│   ├── agent.py / modes.py / policy_gate.py   ReAct 循环 + ModeProfile + 执行前闸门
│   ├── evidence.py / verifier.py              证据链反幻觉 + 可插拔判定器
│   ├── memory.py / reflect.py / gaps.py / ppo.py / rl.py   记忆分区与进化链路
│   ├── sandbox.py / registry.py / mcp.py / mcp_client.py   沙箱分档 + MCP 统一注册
│   ├── builtin_tools.py / external_tools.* / cft_tools.*   内置/外部/CTF 工具链
│   └── cli.py / envcfg.py                     CLI 入口 + ${VAR} 环境变量装载
├── modes/                                     模式档案（base / pentest-standard / ctf-web / ctf-crypto）
├── prompts/                                   模式人格提示词模板
├── dsh/                                       DSH agent-preset（proteus 挂载包 + 一键启动器）
├── web/                                       Web 控制台（真内核 / scripted 双驱动）
├── examples/                                  评测与演示脚本（mode_switch / ctf_solve / RL 进化 / 靶场）
├── tests/                                     pytest 全量（当前基线见《当前状态》）
├── tools/                                     文档与维护脚本（md2html / GIF 生成器 / 路径脱敏）
├── data/                                      运行时数据（作战记录 / 技能库 / 评测产物，gitignore）
└── docs/                                      调研、设计与实测记录（见下）

docs/ 关键文档：

历史关联资产（保持原位，不搬迁）：

五、当前状态（2026-09-19）

环境变量约定（可移植性）：本仓库入库文件不含任何本机绝对路径。配置 JSON 里写 ${VAR} 占位符，真实路径放在不入库的 .env（模板见 .env.example），由 penagent/envcfg.py 统一装载与展开：

未设置时对应工具自动"未注册/跳过"，不崩溃——CI（无本地工具与靶场）即按此降级运行。

三阶段已全部完成并通过真机验证：

测试（本仓库的单一基线数字——其它文档一律指向此处，不要再各写一份）：716 passed / 0 failed / 1 skipped（2026-10-18 实测，Docker 在线 + 本机工具链与靶场齐备；唯一 skip 是等 DVWA CSRF token 的 R-42 用例）。torch 保持可选依赖定位，屏蔽时 RL 链路用例按环境跳过；干净机器（CI 口径）的 skip 面与恢复办法见上文《环境与能力档位》。

三链路真机实测（记录见 docs/）：DSH 宿主（preset 发现 / stdio 拉起 / mcp-client 真实调用）· Web 真内核（LLM 决策 + SSE 步骤流 + 证据链 integrity）· RL 进化（步数 6.0→3.0，-50%；闭环评测 Q 层 -39% / PPO 层 -42%）。

安全姿态：PolicyGate 由 ToolRegistry 持有，目标白名单 + 高危授权在 ReAct / MCP / Web 全入口机制性生效；MCP 失败语义修正（isError）；ctf-* 模式的脚本执行强制沙箱档位，无容器环境拒绝而非裸跑。预算字段已全部机制性消费：scope.network_egress=false 闸门+沙箱双层拒绝出网工具、budget.model_tier 档位模型路由（recon/strong 分档）、budget.max_minutes 超时换策略收口（max_cost_usd 因网关不回 token 用量标注预留）。

安全评审：F-E2E-3 已收口——rsactf_attack 维持宿主直跑（离线数学攻击、无网络出口；专用镜像 proteus-sandbox 虽已内置 RsaCtfTool（R-15），但默认镜像不含它且需显式配置 PENTEST_DOCKER_IMAGE，Docker-free 环境提权后仍不可用），人工把关由 require_confirm 档位承担；结论与依据登记于 penagent/ctf_tools.json，契约用例 test_rsactf_attack_review_locks_host_direct_tier 锁定防止静默改档。

下一步：Web 控制台 ask 档人工确认通道实测（F-E2E-5）· SQLi/暴力破解等 require_confirm 审批闭环的实战覆盖 · 镜像内工具已补齐（R-15 第 4 轮：nuclei / ffuf / gobuster / pocsuite3 进镜像，模板与字典改走宿主目录只读挂载 + 按根重写，不再把数据打进镜像）· 记忆/技能进化长周期数据沉淀。

R-16 已于 2026-09-21 决策收口：pentest-standard 改 network_egress: true（渗透必须触达目标，边界由 target_allowlist 硬校验承担），闸门机制本身保留。详见 docs/修复待办清单.md。

参与贡献

• 贡献前请读 CONTRIBUTING.md：硬规则、测试口径（含"skip 不等于通过"）、 路径红线（tools/scrub_paths.py）与非 Windows 环境的配置改写步骤都在里面。 用 AI 辅助开发时，请让它先读 AGENTS.md——那是本仓库的唯一事实来源。

• 发现本仓库自身的安全问题走 SECURITY.md 的私密渠道，不要在公开 issue 里贴可利用细节。

• 第三方组件的来源与许可登记在 THIRD_PARTY.md；引入新组件请在那一并登记。

许可

本仓库自有代码按 MIT 发布（LICENSE，Copyright (c) 2026 xiabai2008）。第三方组件的来源、许可与分发注意见 THIRD_PARTY.md——其中镜像内包含 GPL-2.0 组件（sqlmap / pocsuite3 / unicorn / exploitdb），发布容器镜像前请先读该文件第四节。

安全声明：仅用于授权范围内的受控安全实验（自有靶机 / CTF 靶场 / 隔离容器）。目标白名单硬校验 + 高危操作审批 + 全动作证据链留痕是不可妥协的前提。严禁在未授权系统上运行。