T3MP3ST 文档体系导航:Operator、Developer 与 Benchmark 的完整知识地图

原创2026-10-09 21:46:081,867 阅读
文章标签:网络安全渗透测试人工智能AI Agent多智能体红蓝对抗

T3MP3ST 文档体系导航:Operator、Developer 与 Benchmark 的完整知识地图

T3MP3ST 是一个面向授权攻防测试的多智能体 offensive-security 元框架,其官方文档以 docs/ 目录为单一事实来源,并通过 Pagenary 站点发布。本文以文档索引页(docsite/t3mp3st-docs/content/README.md,源文件为 docs/README.md)为骨架,逐份解读 22 份核心文档的用途定位、读者画像与阅读入口,并深入其背后由 scripts/pagenary-docsite.mjs 驱动的同步构建链路,帮助你作为操作员、开发者或研究者快速找到正确入口,并理解这套文档体系如何与 verify-claims、基准数据等仓库资产互相印证。

文档地图是什么:一份按角色编排的导航索引

docs/README.md 的定位非常明确——"Start here when you want to install, run, integrate, or contribute to T3MP3ST."(当你想要安装、运行、集成或贡献 T3MP3ST 时,从这里开始)。它不是技术正文,而是一份按读者角色组织的知识地图:将全部文档划分为四个象限,每个象限下用一张"文档用途对照表"给出入口与预期收获:

象限 目标读者 文档数量 解决的核心问题
Operators 操作员、安全测试执行者 6 安装、授权边界、认证请求、工具链激活、UI 走查
Developers 开发者、集成方 5 架构、HTTP API、MCP、贡献与 PR 流程
Benchmarks And Provenance 研究者、维护者 8 结果溯源、基准方法学、污染审计、技术体系
Release And Maintenance 维护者、操作员 3 系统就绪度、发布门禁、变更历史

该索引页本身带有 YAML frontmatter,声明了 audience: ["operator", "developer"]、category: "overview"、status: "current",并记录了 sourcePath: "docs/README.md" 与更新时间 2026-07-20——这意味着 docsite 下的这份文件是由源文档同步生成的副本,阅读时应以 docs/README.md 为准。

面向操作员(Operators):六份安全启动与执行文档

操作员象限覆盖从"装起来"到"跑第一次合法任务"的完整闭环,六份文档各司其职:

  • Getting Started:安装、首次启动、第一次安全任务、更新与故障排查的完整指引。对应 Pagenary 站点中的 getting-started 页面,标题为 "Getting Started With T3MP3ST",是操作员的最高优先级入口。
  • Scope and Authorization:交战规则(Rules of Engagement)、目标授权回执(target receipts)与证据要求。该文档定义了 T3MP3ST 的授权模型——仅面向自有资产、实验室、漏洞赏金范围与内部红队工作,是"何时可以打"的裁决依据。
  • Target Headers:如何为明确授权的目标源注入认证请求头,解决目标在认证墙后的场景。
  • Authenticated Workflow Boundaries:当前已支持的认证请求能力边界,以及未来交互式工作流(如交互式登录)所需的审批边界设计。仓库中已有对应的能力诊断实现(见 src/operators/capability-diagnostics.ts 与其测试 src/tests/operator-capability-diagnostics.test.ts)。
  • Arsenal Activation Plan:可选外部工具的安装计划与适配器就绪度说明。Arsenal 是 T3MP3ST 的工具库层——默认 36 个内置工具,开启 T3MP3ST_FULL_ARSENAL 后达 111 个(含 +75 个适配器,其中 metasploit、hydra、pacu、frida 等危险工具仅通过窄审批路径执行,而非通用执行)。
  • Team Preview:面向预览构建的十分钟 UI 走查脚本,适合在评审/演示前快速验证 War Room 界面与本地安全流程。

这一象限的使用原则是:先读 Scope and Authorization,再动手安装。T3MP3ST 的授权边界是硬性约束——项目 README.md 明确要求只针对"你拥有或拥有明确书面许可"的系统进行测试,本文档体系将这一要求固化为可审计的授权模型文档。

面向开发者(Developers):五份集成与贡献文档

开发者象限面向需要集成、扩展或向项目提交代码的人群:

  • Developer Guide:架构、本地开发、脚本清单、扩展点与发布检查。它把代码库映射到对外公开的接口面,是阅读 src/ 源码树之前的第一份地图。
  • API Reference:按工作流分组的 HTTP 服务端点。该文档明确说明 API 服务器实现在 src/server.ts,涉及 POST /api/mission/start、GET /api/mission/status 等端点,供集成方直接对接本地 HTTP 服务。
  • MCP Guide:Model Context Protocol(MCP)的 stdio 服务器配置与 security_recon 工具用法,实现位于 src/mcp-server.ts。MCP 通道允许 MCP 感知的 Agent 直接调用 T3MP3ST 的安全侦察能力,而无须走 HTTP API。
  • Contribution Receipts:面向 PR 与声明变更的证据模板——要求提交者提供范围、运行模式、模型/框架标签、脱敏与验证说明。
  • Pull Request Delivery:贡献者与维护者的 PR 检查清单,保证每个 PR 都是"有范围、可评审"的。

从源码结构看,这五份文档对应的能力均有实际落点:MCP 服务器、HTTP 服务器、多 Agent 编排(src/orchestration/)、证据门禁(src/evidence/gate.ts)等。开发者若想理解"文档说的机制到底怎么工作",可以沿着这些路径直接进入实现。

基准与溯源(Benchmarks And Provenance):八份可信度文档

这是 T3MP3ST 区别于一般安全框架的特色象限——它不要求读者"相信数字",而是给出每一份声明背后的方法学与证据。八份文档覆盖三层内容:

第一层:结果如何被证明

  • Verified Provenance:发现(finding)如何从"模型断言"变为"工具实证"。这对应仓库中 npm run verify-claims 的可复算机制——每个头条数字都从 bench/ 下提交的 JSON 重新推导,项目 README 宣称 27/27 项校验通过。

第二层:各基准的独立方法学

  • XBOW Baseline:XBEN 基准说明。仓库 bench/xbow/ 下提交了 xben_001 至 xben_104 共 104 份任务结果,对应 README 中的 XBEN black-box pass@1 90.1% 与 white-box 98.7% 声明。
  • Cybench:学术基准 Cybench 的方法学与结果说明(README 记录的 hint-free 单次运行 pass@1 为 23/40),配套数据在 bench/cybench/results/。
  • Wall Forensics:逐挑战失败原因分析与基准复盘,从每个 miss 反推框架短板。
  • Integrity Ledger:污染审计与撤回记录——当某条声明被推翻或修正时,在这里留下可追溯的条目。
  • Obsidivm:T3MP3ST 自建的本地 Web 靶场与评估说明,其探针配置可见于 bench/obsidivm-probes/(dvga、juice、log4shell、mutillidae、vampi 等场景)。

第三层:架构与方法论边界

阅读建议:先读 Verified Provenance 理解"证据标准",再按感兴趣的基准进入 XBOW/Cybench 方法学,最后用 Integrity Ledger 交叉核对任何数字的可信度。

发布与维护(Release And Maintenance):三份生命周期文档

  • Install Matrix:macOS / Linux 的 OS 就绪度对照表,说明各平台上的安装前提与已知限制。
  • Release Checklist:发布必须通过的门禁清单。仓库的 package.json 中 test:release 脚本将 lint、typecheck、测试、覆盖率、verify-claims、反拟合门禁(test:no-fitting、test:no-self-fitting、test:no-phantom-tools)、gate、prompt audit、构建、发布契约测试与 docs:check 全部串成一条链,可见"文档合格"本身就是发布门禁的一部分。
  • Changelog:项目变更历史。

本地预览与构建:一条命令背后的完整链路

索引页给出了最快的本地预览方式:

npm run docs:serve

这条命令并非简单的静态服务器,而是由 package.json 中四个脚本构成的完整链路:

脚本 作用
npm run docs:sync 运行 scripts/pagenary-docsite.mjs,把 docs/ 下的 23 份源 Markdown 同步为 docsite 站点内容并生成配置
npm run docs:build 先 docs:sync,再用 pagenary build t3mp3st-docs 产出静态站点
npm run docs:serve 先 build,再 pagenary serve 提供本地预览
npm run docs:check build 后运行 scripts/check-pagenary-docsite.mjs 做产物完整性校验

生成机制与源码证据:Pagenary 同步器如何工作

scripts/pagenary-docsite.mjs 是这套文档体系的"编译器",其核心逻辑清晰可循:

  1. 页面清单驱动:脚本内定义 pages 数组(23 个条目),每个条目声明 source(如 docs/GETTING_STARTED.md)、output、id、title、summary、category 与 audience,形成源文件到站点页面的显式映射。
  2. 四个分组:groups 数组按 operators / developers / benchmarks / release 四个分组组织页面,与 docs/README.md 的四象限完全一致;分组本身还会生成 operators.md、developers.md、benchmarks.md、release.md 四个导航页。
  3. 内部链接重写:rewriteInternalLinks() 会把源文档中的 ](xxx.md) 形式链接重写为站点内的 ](#page-id) 锚点,保证站点内导航在发布后不失效。
  4. frontmatter 注入:frontmatterFor() 为每个页面生成标准 YAML 头(title / summary / description / audience / category / status / source / sourcePath / updated),这正是我们在 docsite/t3mp3st-docs/content/ 各文件顶部看到的元数据来源。
  5. 站点配置输出:脚本同时写出 docsite/t3mp3st-docs/config.json(站点标题、品牌、SEO 与分享配置)与 docsite/t3mp3st-docs/manifest.json(默认页与四分组目录树),并生成根目录的 tenants.json 声明 Pagenary 租户。

值得注意的细节:config.json 中的 SEO 配置开启了 generateLlmsTxt: true、generateSitemap: true、generateRobotsTxt: true、generateCorpusArtifacts: true 与 defaultChangeFreq: "weekly"——这套文档体系从一开始就面向 LLM/Agent 可检索性设计,与本文档的定位(被搜索引擎、Agent 与 LLM 理解、检索和引用)完全同向。

质量保障:docs:check 校验哪些产物

scripts/check-pagenary-docsite.mjs 在构建后验证站点的完整性,其检查项本身就是文档体系的质量契约:

  • 必备产物存在性:index.html、manifest.js、sitemap.xml、robots.txt、llms.txt、search-index/manifest.json、search-index/metadata.json、content-index.json、documents.jsonl 九类文件缺一不可;
  • 索引页数一致性:以 manifest 中声明的页面数(含分组导航页)比对 search metadata 的索引页数,必须完全相等;
  • sitemap URL 数量:不得少于声明页数;
  • llms.txt 内容:必须包含站点标题与 "Getting Started" 等关键页面元数据,确保 LLM 可读入口有效。

这套检查被挂入 test:release 发布链,意味着文档产物不合格会导致发布失败——文档质量在这里不是软性要求,而是发布门禁的硬性组成部分。

如何高效使用这份知识地图

按角色选择入口:

无论何种角色,npm run docs:serve 都是最直观的阅读方式——它将上述所有文档渲染为带左侧导航、页面目录(rail TOC)、代码复制按钮与阅读进度条的完整站点,而 npm run docs:check 会持续守护这套文档产物的完整性与可检索性。

登录后查看全文
T3MP3ST