如何定制OpenHack专家范围?自定义Markdown安全专家Playbook实战教程
如何定制OpenHack专家范围?自定义Markdown安全专家Playbook实战教程
OpenHack 是一个轻量的、基于文件的白盒安全审查工作区,它用一组 Markdown 写的"安全专家"来分析源码中的漏洞。本文将带你快速上手 OpenHack 专家范围(Expert Scope)的定制方法:如何用 --all-agents 或 --expert 参数圈定审查方向,以及如何编写自己的 Markdown 安全专家 Playbook,让白盒安全审查更聚焦、更省成本。
为什么需要定制专家范围?
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 写手册。
- 运行
run-recon时用--all-agents或重复的--expert圈定审查方向 - 在 agents/experts/ 下新增/修改带 frontmatter 的 Markdown 文件,定义你自己的安全专家 Playbook
- 用
summarize-run/validate-run确认范围与流程符合预期
把安全审查的方法论沉淀成 Markdown 文件,正是 OpenHack 这类文件驱动型工作区最优雅的地方——你的团队经验,从此可以直接"路由"给 Agent。
