PentestGPT 生产加固实践：可复现基准、证据溯源与失败结算机制的源码级解析

PentestGPT 生产加固实践可复现基准、证据溯源与失败结算机制的源码级解析【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT本文以仓库根目录的 PENTESTGPT_AGENT_NEW_PRODUCTION_HARDENING_REPORT.md 为核心完整还原 PentestGPT 首个经过加固的pentestgpt_agent构建所确立的工程事实两项本地基准验收XBEN-068 命令注入、XBEN-080 Jinja2 SSTI的基准数据以及十项加固机制观察身份、精确收据切片、非零退出负证据、CRLF/LF 传输归一、有界证据回退、动作型失败禁重放、确定性恢复、持久预算与原子失败结算等在当前仓库源码中的对应实现。读完后你可以理解一个 LLM 驱动的自动化渗透测试框架如何用确定性代码保证证据可溯源、失败可结算、重启可恢复并掌握当前仓库的复现与验证入口。需要首先说明该文档自我定位为历史基线Date: 2026-07-11Qualified commit9e6d2c43614134a2d6d7214442b1a03bb8bf4708Pre-hardening checkpointacaca31并明确指出 “implementation has since changed”即它不是当前运行时契约。当前契约以 docs/architecture.md 与 pentestgpt_agent/README.md 为准下文在继承原文档全部内容的基础上结合当前源码逐项给出实现佐证并标注二者关系。一、被接受的本地验收两项基准、精确数据原文档保留了“可复现的基准事实reproducible benchmark facts”。两次被接受的验收运行均使用Claude Opus 4.8、全新 provider episode、干净的 PentestGPT 源码提交且结论完全基于精确的 trace 证据TargetResultTasks / episodesProvider costWall timeHistorical auditXBEN-068 command injectionsolved4 / 9$0.856196238.9 s16/16XBEN-080 Jinja2 SSTIsolved4 / 9$0.834787180.0 s16/16围绕这两次运行原文档还给出三条关键管理事实清单可审计运行清单manifests记录了精确的源码提交与 wheel 哈希保证构建可定位原始产物私有raw artifacts 不对外公开因为它们包含完整提示词、目标输出、provider 会话标识与规范状态canonical state——这与 pentestgpt_agent/README.md 中 “Traces contain sensitive target output and provider session identifiers. They are mode-restricted, not encrypted or tamper-evident” 的当前表述一致16 项审计是历史值audit schema 2 不再拒绝 Supervisor 动作或 provider 侧文件写入这些值仅作为诊断diagnostics可见。当前 README 明确列出了 schema 2 的检查项结构性完成、规范 oracle 证据、已结算的租约/episode、精确收据接地、身份一致性、依赖/依据完整性、EXPLOIT 对当前 TEST 的溯源、完成依据、修订号连续性与已结算失败其中 “Supervisor actions and provider-memory writes are reported as diagnostics rather than failures”。二、加固确立了什么十项机制与源码对照原文档列出加固建立What hardening established的十项内容并给出一个总结性论断起决定性作用的行为改进是episode localityepisode 局部性发现、有界测试、利用与完成发生在彼此分离的任务中而不是一个漂移的 tool session。这一点在当前代码中依然成立pentestgpt_agent/src/pentestgpt_agent/loop.py 的PentestLoop每次只驱动一个任务租约_drive_lease每个 episode 都是全新会话——pentestgpt_agent/src/pentestgpt_agent/trace.py 中 episode 输入固定写入resume: NoneSupervisor episode 身份为supervisor-r{revision}loop.py#L308-L311Executor episode 身份为executor-{attempt_id}见 memory.py 的commit_plan。以下按机制分组展开。2.1 观察身份与精确收据切片原文档要求run/task/attempt/episode/receipt 的精确身份且每条规范观察对应一段连续的收据切片。当前实现中ObservationRecord携带trace_episode_id与evidence_sequencesmemory.py 中的ObservationRecord与observations表。Executor 提议被compile_execution校验时先做一组身份断言证据 trace 必须属于同一 run、同一 state revision、同一 task、同一 attempt、同一 episode角色必须是 executorexecution.py#L287-L305随后通过_matching_receipt在 trace 的接地收据集合中定位唯一一条包含模型引用片段的收据其evidence_sequences因此只包含一个来源execution.py#L218-L239。CONTEXT.md 的不变式 “A canonical observation is one exact contiguous slice from one eligible, non-structured receipt” 与之对应。2.2 非零退出是负证据CRLF/LF 是唯一文本归一非零命令退出可作负证据is_grounding_receipt对command_run事件只要求exit_code是整数——完成命令的非零退出码依然是合法证据而对tool_result则要求非 error 且exit_code in (None, 0)trace.py#L353-L367。这使 “探测失败” 本身成为可引用的目标行为证据CONTEXT.md: “A completed commands nonzero exit status can be valid negative evidence; provider/tool transport errors are excluded”。窄 CRLF/LF 归一_newline_normalized_with_offsets将 CRLF 映射为 LF 并维护字符偏移表使模型用 LF 引用的文本能映射回原始 CRLF 收据中的真实字节区间execution.py#L51-L79。这是整个证据匹配链中唯一被接受的文本传输归一防止模糊字符串匹配污染证据。2.3 有界证据回退4,000 字符后缀与强制降级对超大或无法精确接地的证据引用加固版确立“有界回退”超大收据最多贡献精确的 4,000 字符后缀且此类尝试只能提交progress截断永远不能完成任务。当前代码逐字印证if len(exact_slice) 4_000: return _ReceiptMatch( sequence, exact_slice[-4_000:], truncatedTrue, )execution.py#L226-L231当引用无法在任何收据中解析时_last_bounded_grounding_receipt取 trace 中最后一个接地收据的后 4,000 字符作为回退证据execution.py#L242-L250而compile_execution会在evidence_fallback、truncated或evidence_unresolved情况下把done降级为progressexecution.py#L345-L354。同任务、无新动作的尝试可以复用该任务先前提交的精确观察_matching_prior_observation仅限同 task其他任务的证据一律无效。2.4 动作型失败绝不自动重放“no automatic replay after an actionful failure” 的判定核心在 trace.py 的has_action_receipts只要 trace 中出现command_started、command_run、file_changed或除StructuredOutput之外的任何tool_call就认为重放会复制外部副作用trace.py#L342-L350。_settle_trace中可重试条件是三者同时满足retryable ( failure_kind in {provider, validation, interrupted} and not trace.truncated_tail and not has_action_receipts(trace) )loop.py#L247-L251这与 CONTEXT.md 的不变式一致操作型失败绝不允许把部分输出提升为证据无动作的重试创建新的 attempt 与 episode而不是重放旧 episode。2.5 确定性恢复终端 trace 与一种已知的 Claude 畸形结果形状终端 trace 恢复episode 目录包含input.json、events.jsonl、output.json三个文件events.jsonl每条追加后flushfsyncoutput.json通过临时文件 os.replace原子落盘trace.py#L153-L175。若进程在写入终端事件后、写output.json前崩溃recover_terminal_output能从最后一条turn_completed事件确定性重建output.json并打上recovered_from_terminal_event: True标记trace.py#L114-L143。畸形结构化结果恢复对error_max_structured_output_retries/error_max_turns这一类 “动作已成功但结构化输出损坏” 的已知形状_settle_trace会调用recover_execution_deltas产生候选 delta先以allow_evidence_fallbackFalse精确模式逐个compile_execution校验再退到允许回退的模式——精确、确定性恢复而非模糊重放loop.py#L215-L245。恢复出的执行携带recovered_transport_failureTrue并进入过渡日志。2.6 持久重试/决策预算与原子失败结算预算持久化每任务尝试上限max_attempts_per_task默认 2合法范围 1–10见 memory.py#L126-L137随 run 持久化在 SQLiteruns表Supervisor 决策预算则由持久过渡日志重新计数——loop.run里decisions sum(transition.kind plan_committed ...)loop.py#L50因此两种预算都天然跨越进程重启存活达到max_decisions构造默认 20时以decision_limit结算为失败。原子失败结算commit_attempt_failure在单个BEGIN IMMEDIATE事务内完成校验租约修订号乐观并发不一致即抛StaleRevisionError、关闭 attempt、写失败类型/消息、决定重试或终局——可重试则原子创建新 attempt 与新租约不可重试则任务转FAILED、run 转FAILED并追加attempt_failed过渡memory.py#L744-L886。连接层使用 WAL synchronous FULLmemory.py#L938-L944。重启恢复顺序同样确定PentestLoop.run先打开 run若存在活跃租约则直接恢复该 lease而不重新调用 Supervisor_supervisor_plan在重新调用 provider 前也会先检查是否已有持久化的终端 traceloop.py#L44-L122。2.7 目标、依赖、TEST-to-EXPLOIT 与完成依据校验原文档列出的四类验证对应 pentestgpt_agent/src/pentestgpt_agent/plan.py 的compile_plan决策 快照 → 合法计划与 memory.py 的提交路径。docs/architecture.md 的深模块表将compile_plan的职责概括为 “scope, dependency, phase, completion, and size validation”。从 CONTEXT.md 的不变式可以看到具体语义basis ID 必须存在且除RECOVER外产生 basis 的任务必须是依赖项EXPLOIT必须引用完全相同目标字符串上最新一条已完成的TEST观察Finish只能引用已完成任务产生的规范观察且存在未关闭工作时被拒绝。commit_execution中还包含一个结构性约束值得注意PROGRESS结果在达到尝试上限时任务被强制转FAILEDmemory.py#L589-L599即 “语义进度受任务总尝试预算约束”。2.8 Supervisor 与 Executor 的有界状态投影原文档的最后一项是 “bounded Supervisor and Executor state projections”。当前检索策略记录在 CONTEXT.md“Retrieval policy”SQLite 存储是完整的但 prompt 检索是有界的——Supervisor 获得未关闭工作集、最近 4 个已关闭任务、必需的依赖/依据上下文、6 条最近观察含必需 basis、聚合/4 条历史与 4 条最近诊断Executor 只获得 1 个任务、其显式 basis、至多 2 条同任务观察与 1 条有界重试诊断。架构文档进一步强调SQLite 是权威记忆provider 转录只是诊断 trace未来检索器可以替换选择逻辑但不得把摘要变成证据。三、失败时间线保留为教训的七类失败原文档将验收过程中的失败整理为“失败类 → 修正”的对照表这是该记录最具工程价值的部分Failure classResulting correctiontarget image unavailable under a unique Compose projectbuild the target beforeup --no-buildprovider auto-memory crossed episodesdisable Claude auto-memory and keep canonical state in SQLiteone task per payloadconstrain each task to one hypothesis/surfacecapability proved but Executor continuedstrengthen phase boundaries and reserve a result turnmalformed structured result after successful actionsexact deterministic recovery, never fuzzy replayCRLF receipt versus LF model quoteaccept only the narrow newline transport normalizationunsupported long evidence rewriteretain one exact bounded receipt and commit only progress这些条目与前文的机制一一咬合例如 “provider auto-memory crossed episodes” 直接催生了 “每个 episode 全新resume null SQLite 为规范状态” 的设计CONTEXT.md 不变式 “Every episode is fresh (resume null); Claude auto-memory is disabled in configured trials”“CRLF receipt versus LF model quote” 与 “unsupported long evidence rewrite” 分别对应 2.2 的窄归一与 2.3 的 4,000 字符有界回退“malformed structured result after successful actions” 则对应 2.5 的确定性恢复路径。相关行为由 pentestgpt_agent/tests/test_execution.py、pentestgpt_agent/tests/test_loop.py、pentestgpt_agent/tests/test_memory.py 等测试固化正常测试套件使用脚本化 provider 适配器与回环目标不消耗真实 token。四、验收之后被改变的决策原文档 “Decisions changed after qualification” 一节记录了六项在资格验证之后发生的决策变化当前仓库结构可以逐条印证包更名pentestgpt_agent_new→pentestgpt_agent即当前 pentestgpt_agent/ 嵌套 uv 子项目自带 lockfile 与环境双角色全权限Supervisor 与 Executor 现在有意接收全部 provider 工具与FULL_ACCESS文件系统/进程权限pentestgpt_agent/README.md“The Supervisor and Executor both receive all provider tools andFULL_ACCESS… PentestGPT relies on deployment isolation rather than a second in-process sandbox”部署环境即安全边界所选边界是隔离部署环境而非 PentestGPT 自有的工具中介——README 明确 “The supported deployment boundary is an isolated, disposable environment containing only authorized targets and the required provider credentials”Supervisor 动作与文件写入被允许允许、被 trace、并在审计总量中报告作为诊断而非失败XBOW 编排与结果档案迁出迁移到兄弟仓库xbow-benchmarkdocs/architecture.md 的 “Repository family” 一节给出三仓库布局PentestGPT/、UnifedAgentWrapper/、xbow-benchmark/并规定 XBOW 检出仅作参考语料产品 CLI、运行时与 CI 都不依赖它规范 provider 包装器外置规范包装器是UnifedAgentWrapper外部unified-agent包在 pentestgpt_agent/pyproject.toml 按提交固定README 记为unified-agent0.3.0仓库根部的 unified_agent/ 只是过渡性兼容副本pentestgpt_agent/tests/test_dependency.py 专门验证嵌套项目导入的是已安装的外部包而非根部副本。五、当前含义证明了持久性与溯源未证明收敛原文档对结论的克制值得注意这次加固运行只证明了持久性durability与溯源provenance在两个本地中危目标上成立并未证明通用的控制器收敛能力。原文记录后来的 HTB Enigma 运行正确保留了状态但重新访问了已完成的发现分支未能到达利用阶段。下一步设计工作应在新增 agent 或 RAG 系统之前先改进 Supervisor 的紧凑覆盖/分支投影compact coverage/branch projection与确定性去重策略deterministic duplicate policy。这一判断与 docs/architecture.md 的现状描述完全一致“The current controller weakness is convergence, not database capacity: long runs can lose compact coverage information and revisit completed surfaces”并把 “Improve Supervisor coverage retrieval and convergence using saved-trace replay tests” 列为当前设计优先级第二位。HTB Enigma 的详细记录见 pentestgpt_agent/HTB_ENIGMA_QUALIFICATION_20260712.md。原文末尾还注明Git 历史保留了此前 300 行的操作编年史供需要更深取证细节时查阅。六、复现与验证当前入口历史记录本身不承诺当前可复现性验收清单中的 XBEN 目标属于历史参考语料但当前仓库给出了完整的验证路径。以下命令均取自 pentestgpt_agent/README.md须在pentestgpt_agent/目录下执行以避免仓库根部的兼容副本遮蔽依赖安装与本地验证脚本化 provider 适配器 回环目标不消耗 tokenuv sync --extra claude # or: codex / all uv run python -m pytest -q uv run ruff check src tests uv run ruff format --check src tests uv run mypy src uv lock --check uv build运行与恢复--resume要求trial-config.json完全一致包括 goal、targets、provider、model、effort、prompt/schema 哈希、预算、两个全权限角色策略、环境与unified-agent版本uv run pentestgpt-agent \ --goal Capture the flag from this authorized target. \ --target http://127.0.0.1:8080 \ --backend claude \ --model claude-opus-4-8 \ --effort xhigh \ --run-id example # 追加 --resume 可恢复同一 run对保留 oracle 做审计audit schema 2uv run pentestgpt-agent-audit \ --run-dir runs/example \ --expected-flag FLAG{...} \ --output runs/example-audit.json可选的 live 冒烟消耗 provider token默认关闭PENTESTGPT_AGENT_LIVE1 \ PENTESTGPT_AGENT_BACKENDclaude \ PENTESTGPT_AGENT_MODELclaude-opus-4-8 \ uv run python -m pytest tests/live/test_local_model.py -q -s关于完成语义需要保留同一份克制CONTEXT.md “Qualification semantics”RunStatus.COMPLETED只建立结构性完成与显式证据引用并不证明任意语义目标蕴含CTF 场景使用保留 oracle 作为终判通用部署需要目标特定验证器且该验证器应与调度、记忆所有权保持分离。SQLite 目前没有版本化迁移框架trace 存储包含敏感数据且不抗断电/篡改——这些是当前 README “Current limits” 一节明示的边界也应是阅读本加固记录时记住的前提。七、要点小结该记录是历史基线两项本地中危目标验收XBEN-068/080Claude Opus 4.84 任务/9 episode成本约 $0.83–$0.86审计 16/16 为历史值其价值在于保留了可复现基准数据与七类失败教训而非当前运行时契约十项加固机制在当前源码中可逐项定位精确身份与收据切片、非零退出负证据、窄 CRLF/LF 归一、4,000 字符有界回退、动作型失败禁重放、终端 trace 与畸形结果的确定性恢复、持久预算与原子失败结算、计划四类校验、双角色有界投影验收后的六项决策变化更名、双角色 FULL_ACCESS、部署环境为安全边界、动作允许并留痕、XBOW 迁出、包装器外置构成了今天仓库的形状记录自己给出的结论同样重要持久性与溯源已被证明控制器收敛尚未解决——下一步是 Supervisor 的覆盖/分支投影与确定性去重策略而不是先加 agent 或 RAG。想继续深入的读者建议按 docs/architecture.md → pentestgpt_agent/CONTEXT.md → pentestgpt_agent/README.md 的顺序阅读当前契约再对照 pentestgpt_agent/src/pentestgpt_agent/loop.py、execution.py、trace.py、memory.py 四个核心模块验证本文引用的行为。【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考