如何定制OpenHack专家范围?自定义Markdown安全专家Playbook实战教程

原创2026-10-29 09:47:101,741 阅读

如何定制OpenHack专家范围?自定义Markdown安全专家Playbook实战教程

OpenHack 是一个轻量的、基于文件的白盒安全审查工作区,它用一组 Markdown 写的"安全专家"来分析源码中的漏洞。本文将带你快速上手 OpenHack 专家范围(Expert Scope)的定制方法:如何用 --all-agents 或 --expert 参数圈定审查方向,以及如何编写自己的 Markdown 安全专家 Playbook,让白盒安全审查更聚焦、更省成本。

OpenHack 白盒安全审查:在编码助手中发起源码安全测试

为什么需要定制专家范围?

OpenHack 内置了 12 个安全专家,覆盖 OWASP Top 10 与 MITRE CWE 的常见根因家族,例如注入、访问控制失效、加密失败等。所有专家都定义在 agents/experts/ 目录下,每个专家就是一个 Markdown 文件:

Expert ID 对应标准
broken-access-control A01:2025 - Broken Access Control
injection A05:2025 - Injection
cryptographic-failures A04:2025 - Cryptographic Failures
path-traversal-unrestricted-upload CWE-22 / CWE-434
unrestricted-resource-consumption API4:2023 / CWE-770
… 共 12 个专家,完整清单见 README.md

全量审查覆盖面广,但审查面也宽、路由出的场景多。如果你只关心注入类和上传类问题,把专家范围收窄到对应专家,能显著减少场景队列和人工审批的往返次数。 这就是定制专家范围的价值:

  • 🎯 聚焦:路由 Agent 只会为选中的专家生成场景
  • 💸 省成本:少选专家 = 少跑场景 = 少消耗模型调用
  • 📐 可复用:专家定义就是 Markdown 文件,可以按团队安全标准定制

三步圈定专家范围(最小示例)

专家范围在 recon(侦察)阶段之前选定,并通过命令行写入运行配置。安装 CLI 后,只需三步:

# 1. 从源码仓库初始化一次 run
openhack init-run demo https://example.com/app.git --run-id demo-001

# 2a. 方式一:使用全部 12 个专家
openhack run-recon demo demo-001 --all-agents

# 2b. 方式二:只选 1~N 个专家(--expert 可重复)
openhack run-recon demo demo-001 \
  --expert injection \
  --expert path-traversal-unrestricted-upload

选定后,OpenHack 会把范围写入 runs/<target>/<run-id>/run-config.yaml 中的 expert_scope 块:

expert_scope:
  mode: "selected"
  experts:
    - "injection"
    - "path-traversal-unrestricted-upload"

这个选择会约束后续所有环节:覆盖率校验、router prompt 和 backlog 记录都只面向选中的专家。详细的命令清单见 docs/QUICKSTART.md 和 docs/OPERATING_MODEL.md。

⚠️ 小贴士:如果传入不存在的专家 ID,命令会直接报错 Unknown expert id(s) 并列出所有可用选项,拼写错误不会静默通过。

深入:专家 Playbook 的 Markdown 结构

每个专家文件 = YAML frontmatter(元数据) + Markdown 正文(Playbook)。以 agents/experts/injection.md 为例:

1)YAML frontmatter:让 OpenHack 认识你

frontmatter 声明专家的身份和"路由信号",由 src/openhack/registry.py 自动解析成专家注册表:

字段 作用
id 专家唯一 ID,即 --expert 参数的取值
title / category 展示标题与分类
standard_refs 对齐的 OWASP/CWE 标准编号
tags 检索标签
routing_signals 路由信号关键词(如 knex.raw、shell_exec、v-html),侦察证据命中这些词时,该专家会被视为相关候选

routing_signals 写得越贴合目标技术栈(框架名、库名、危险函数名),路由越精准。

2)Markdown 正文:专家如何审查

正文是写给 Agent 的操作手册,推荐包含这些章节(与内置专家保持一致即可):

  • Mission:一句话职责边界
  • Route When:什么情况下该把这个场景交给本专家
  • Expert Playbook:标准审查步骤
  • Edge Cases To Hunt:常见隐蔽坑点
  • Prove Or Reject:什么证据能证明 / 排除漏洞
  • False-Positive Traps:容易误报的场景
  • Handoffs:跨专家移交(发现线索时应移交给哪个专家)

实战:新增一个自定义专家

假设团队想单独审查"对象存储权限"问题,可以新增 agents/experts/object-storage-access.md:

---
id: object-storage-access
kind: expert
phase: scenario
title: "Custom - Object Storage Access Control"
category: access-control
standard_refs:
  - OWASP A01:2025
  - CWE-284
routing_signals:
  - s3
  - gcs
  - bucket
  - presigned
  - object-url
---

正文按上面的章节模板写清审查手册。由于注册表是扫描 agents/experts/*.md 的 frontmatter 动态生成的,新文件保存后即自动生效,无需改任何 Python 代码。

然后在 run 中选用它:

openhack run-recon demo demo-001 \
  --expert injection \
  --expert object-storage-access

查看某次 run 当前范围,可以用 openhack summarize-run demo demo-001,输出中会带 expert_scope=... 摘要(实现见 src/openhack/expert_scope.py 中的 scope_summary)。

已选范围不满意?重跑 recon 即可

专家范围写在 run-config.yaml 里,recon 之前随时可改:重新执行 run-recon 并传入新的 --expert / --all-agents 参数,旧的作用域块会被自动替换,侦察输出按新范围重新生成。注意:

  • 范围变更要在 create-scenarios 之前完成,否则 router 仍按旧范围生成场景
  • 换范围后建议重新 record-scenario-backlog,让 backlog 与新专家集对齐

常见问题(FAQ)

Q:--expert 和 --all-agents 能同时用吗? --all-agents 优先,等价于选中全部专家(mode: "all")。

Q:选 2 个专家和选 12 个专家,差别到底在哪? 差别在"宽度":recon 产出的路由单元会分别扇出到选中的专家上,专家越少,scenarios/backlog/ 里的场景队列越短,后续 record-scenario-result 和 finding triage 的工作量也越小。

Q:自定义专家的 id 有什么要求? 只需在 agents/experts/ 下唯一即可,建议用英文短横线小写(如 object-storage-access),与目录内其他专家 ID 保持风格一致。

小结

OpenHack 的专家范围定制本质上就是两件事:用命令行圈范围、用 Markdown 写手册。

  1. 运行 run-recon 时用 --all-agents 或重复的 --expert 圈定审查方向
  2. 在 agents/experts/ 下新增/修改带 frontmatter 的 Markdown 文件,定义你自己的安全专家 Playbook
  3. 用 summarize-run / validate-run 确认范围与流程符合预期

把安全审查的方法论沉淀成 Markdown 文件,正是 OpenHack 这类文件驱动型工作区最优雅的地方——你的团队经验,从此可以直接"路由"给 Agent。

登录后查看全文
OpenHack