pentest-engagement

渗透测试项目

通过 pentest-engagement 工作流端到端地编排范围明确的渗透测试。这是与以标志为导向的 htb-solve 相对应的广度完整、覆盖门控流程——使用相同的引擎（coordinator-loop，现已在循环中内置逐项交错验证发现），但由攻击类别覆盖矩阵驱动，而非标志，并内置了攻击面扩展和根因严重性评估。

适用场景

由范围定义的真实（非 CTF）项目——可以是：

• WEB — 由顶级域名／资产 URL 定义的 Web／API／云应用，或
• NETWORK — 用于扫描在线服务和漏洞的 IP／CIDR／范围列表（例如 1500 台主机）。

工作流会在 Setup 中自动检测模式（engagement_kind）：以 IP／CIDR 为主时使用 network；以顶级域名／应用 URL 为主时使用 web。HackTheBox／CTF 请改用 hackthebox（htb-solve）。

运行

WEB — 使用范围文件或直接输入：

Workflow('pentest-engagement', { scope_file: 'projects/pentest/<engagement>-scope.md' })
Workflow('pentest-engagement', { scope: { engagement_name, apex_domains:[], assets:[...], creds_env:[...], roe, business_tier } })

NETWORK — 直接输入 IP／CIDR 列表，或使用包含 IP／CIDR 的范围文件（接受每行一个 IP／CIDR 的纯文本列表）：

Workflow('pentest-engagement', { targets: ['10.0.0.0/24', '192.0.2.0/24', '198.51.100.7'] })
Workflow('pentest-engagement', { scope_file: 'projects/pentest/<engagement>-ips.txt', scan_profile: 'standard' })

通用选项：maxConcurrent（默认值 = 审慎设置，根据 CPU 核心数推导——约为核心数的一半，上限为 2–8；绝不会启动数百／数千个并行任务）、dryRun、max_experiments、business_tier、report（默认值为 true）。 网络选项：scan_profile light（有界扫描 1-1024 端口，并扫描精选的较少见端口，适用于大规模／快速扫描）／standard（对每台可达主机扫描完整端口范围 -p-，默认值；分两阶段执行 SYN 扫描，再对发现开放的端口执行 -sV，并受主机数量限制；支持消息总线，且能识别非 443 端口的 TLS）／full（-p- + 有界 UDP 扫描）；udp（扫描前 50 个 UDP 端口；light／standard 模式下关闭，full 模式下自动开启）；slice_size（每个扫描工作线程处理的主机数，自动设置为约 64 个 IP 列表条目／2 个 CIDR 密集条目）；deepen_top（对价值最高的 N 台主机进行深入扫描，默认值为 10，设为 0 可跳过）；geo_vantages（用于第二地理位置视角允许列表复测的 ≤2 个 gcp 区域；覆盖默认的 US+EU 设置）；auto_provision（默认值为 true；设为 false 仅检测并标记，不产生云端费用）。如果检测到源 IP／地理位置允许列表特征，工作流会自动配置第二个地理位置视角，并对被过滤的主机重新探测，然后再得出“无攻击面”的结论。

请按照 reference/scope-file-format.md 编写范围文件。凭据仅通过环境变量名称引用，并从仓库的 .env 文件中读取：使用 python3 tools/env-reader.py，绝不内联机密值。

阶段（工作流的执行内容）

1. 设置 — env-reader 凭据，解析范围，分类类型（web|network），读取 CPU 核心数 → 谨慎设置并行任务上限，OUTPUT_DIR = projects/pentest/<date>_<engagement>/，发送 STARTED Slack 消息（受门控）。
2. 扩展 （WEB，第 1 个修复项） — 必须对每个范围内的 apex 执行 CT 日志 / 被动 DNS / 源站发现（crt.sh、certspotter、subfinder，以及针对由 CDN/WAF 代理的主机进行源站发现）。范围 = 发现的攻击面，而非交接时提供的范围。构建逐资产工作清单，并为每个资产初始化覆盖矩阵。 扫描 （NETWORK，取代扩展） — 将 IP/CIDR 集合划分为符合机器承受能力的批次；每个切片启动一个 nmap 工作器（Agent 数量按切片扩展，约为几十个，绝不按 IP 数量扩展），运行相同的流水线：主机发现（可达性未知）→ 有界的常见 + 较少见端口/服务扫描 → CVE 检测（nmap --script vulners、nuclei，并通过 tools/nvd-lookup.py 补充每个 CVE-ID 的信息）→ 写入统一的逐 IP 目录树 hosts/<ip>/{recon,host.json,findings} + 合并后的 recon/inventory/。
3. 评估 （单一交错阶段——没有单独的后续验证流程） — WEB：每个资产交给 coordinator-loop（覆盖模式），在继续搜索前，立即让新的盲测 Agent 验证每个刚生成的候选项（严格执行逐项修复/丢弃循环）。NETWORK：coordinator-loop 对仅限 deepen_top 中价值最高的主机进行有界深入分析，并采用相同的逐项交错验证（其余内容均为统一工具扫描，不会针对每台主机启动 Agent）。**按 VALID 计算覆盖率：**只有 VALID/REPAIRED 发现、合理说明的 N/A 或确凿的阴性结果才算覆盖某个类别——若某类别的所有候选项都被拒绝/丢弃，则该类别仍为 pending，搜索会继续。
4. 关联分析 — 使用 attack-path-stitcher + risk-prioritiser 对所有已验证的发现进行关联分析 → 生成按优先级排序的组织级路线图。
5. 报告 （确定性生成——不由 Agent 撰写报告） — JS 将已解析的交战信息块 + 精确命令交给一个 finalize runner：tools/report_data_build.py 将带命名空间的中间发现 JSON 合并为规范的 report_data.json（唯一负责组装的组件），随后运行按格式分派的渲染器——transilience → 规范的 generate_report.py PDF 技能，custom → custom_report_cmd（或 Markdown 回退方案）。随后 JS 执行硬性门控：组装 report_data ∧（transilience：WROTE ∧ bytes>0 ∧ [assets: …/formats/transilience-report-style] 来源标记），重试一次 → BLOCKED。报告中只包含 VALID/REPAIRED 发现（完全剔除——validated/ 按设计仅包含已确认内容）；绝不包含 REJECTED（false-positives/）和未修复的 DROPPED（dropped/），也没有差距/保障章节。finalize runner 还会运行 network_coverage_map.py（扫描主机尾部）+ coverage_gate.py 检查整个交战范围，写入 reports/coverage-matrix.json，并在交付内容中加入确定性生成的 攻击模式覆盖情况章节（攻击面单元 × 攻击类别）。COMPLETE 是严格的 100% 门槛：必须成功组装并渲染报告，且覆盖门控报告 complete:true（每个适用单元格均已覆盖）——WEB 和 NETWORK 均适用（NETWORK 还要求扫描完成）。任何未测试的适用单元格都会导致 INCOMPLETE_coverage / BLOCKED。
6. 打包并交付 — 经验证的 <report_id>_deliverable.zip（reports/ input/ logs/ artifacts/）、简短的统计摘要（summary.md：Agent 数量、按严重性统计的发现数量、耗时；tokens/cost 显示为 unavailable — no runtime token counter），工作流返回 slack_offer: true。

运行后（工作流外部的主循环）：由于协调器不得调用 AskUserQuestion，发起调用的 Agent 会显示返回的 summary，并询问是否将 deliverable_zip 发布到 Slack；用户回答是时，执行 python3 tools/slack-send.py --channel "$PENTEST_SLACK_CHANNEL_ID"（仅在交战成功且状态为 COMPLETE 时开放）。 报告选项： report_format transilience（默认）| custom；custom_report_cmd（自定义渲染器，接收 report_data.json 路径和 reports/ 目录）；prior_report（先前的 PDF 或 report_data.json——其标题、行业和范围仅作为元数据，绝不会用于预先生成工作清单）+ version，用于生成封面版本号和“Supersedes”行。

确定性（如实说明）

决策层是冻结的纯 JavaScript computeVerdict（受一致性校验保护，由固定测试样例锁定），其操作数通过 NVD/KEV --cache-dir 快照（artifacts/nvd-cache/、artifacts/kev-snapshot.json）按每次委托冻结，对抗性仲裁人数提高到 3。输入完全相同时，判定结果可证明完全相同。但全新的实时运行具有高度可复现性，但并非 100%——LLM 采样会产生用于判定的布尔值和数字，实时目标的变化也会改变输入；这是固有的上限，我们会如实说明，而非掩饰。字节级完全一致的结果，只有在重放一组冻结证据时才有 100% 保证（Phase-2 重放缓存 artifacts/validation-cache/）——只有在这种情形下，“相同请求 → 相同结果”才是保证，而非仅仅很有可能。

边界

• 仅使用编排器——绝不内联运行协调器循环；覆盖范围和记录管理的规范需要由工作流边界保障。
• 缺少凭据不构成全局阻断——始终测试未认证的攻击面；只有不存在可访问资产的范围才会阻断。
• 默认授权对所属组织/租户执行可逆写入（先创建再删除不具破坏性）；禁止破坏性操作、DoS、暴力破解和越界租户操作（在 RoE 中设定）。

参考资料

• scope-file-format.md — 范围文件架构及完整示例
• coverage-matrix.md — 权威的攻击类别覆盖契约（完成门槛）
• principles.md — 范围即攻击面、可逆主动利用、优先使用真实工具、根因严重性
• pentest-report.md — Transilience 报告结构及 §7.1 根因严重性
• validator-role.md — engagement-validator 攻击类别覆盖检查（8）