numasec Runbook 实战教程:appsec-web-triage 如何终结 AI 的随机工具调用

原创2026-10-27 09:30:011,108 阅读

numasec Runbook 实战教程:appsec-web-triage 如何终结 AI 的随机工具调用

numasec 是一款运行在终端里的开源 AI 安全智能体(The AI Agent for Cyber Security)。它通过结构化的 Runbook 工作流驱动 AI 执行安全任务,其中的 appsec-web-triage 是一个"证据优先"的 Web 应用安全分诊 runbook:先检查本地工具、再爬取路由、提取 JS 端点、最后运行语义化 DAST 探测,彻底告别 AI 大模型"随机调用工具"的混乱行为。本教程带你从零跑通这条工作流。

numasec 终端 AI 安全智能体主界面

为什么 AI 安全 Agent 会"乱调工具"?

把一堆工具(HTTP 请求、扫描器、Shell、浏览器)直接交给大模型,最常见的结果是:

  • 🎲 随机调用:模型不知道先做什么、后做什么,一会儿爬一下站点,一会儿又去扫端口;
  • 🔁 重复劳动:同一个 runbook 反复触发,工具结果互相覆盖;
  • 🗑 上下文丢失:发现散落在聊天记录里,事后无法回溯、无法出报告。

numasec 的解法很简单:用 Runbook 把"领域知识"固化成一条确定的执行轨迹(trace),模型只负责按序执行,而不是自由发挥。

numasec 运行 AppSec 安全操作的工作流演示

快速上手:安装 numasec 并运行 appsec-web-triage

numasec 支持 npm / Bun / Docker 多种安装方式,最快的方式是:

npm install -g numasec
numasec

然后在你要测试的工作区目录中启动(注意:只能用于自有系统、实验室或已获授权的目标)。在 TUI 中依次输入:

/doctor
/mode appsec
/runbook run appsec-web-triage http://localhost:3000

💡 建议先准备一个本地靶场(如 Juice Shop),把 target 换成你的本地地址即可。/doctor 会先检查本机 nmap、sqlmap、nuclei 等工具的就绪状态,/mode appsec 切换到应用安全 Agent。

解剖 appsec-web-triage:一个 runbook 的 5 个步骤

appsec-web-triage 的完整定义在 appsec-web-triage.ts 中,它声明了 1 个必选参数 target(HTTP(S) 根 URL)和 5 个顺序步骤:

步骤 工具 作用
1. 检查本地工具就绪度 doctor 探测本机二进制/运行时,缺失能力会"诚实降级"而不是硬跑
2. 锚定 AppSec 方法论 knowledge 拉取 OWASP WSTG(SQLi / XSS / JWT / IDOR / CORS)方法论上下文
3. 爬取目标路由 scanner(crawl 模式) 最多 80 个 URL、2 层深度,建立应用 URL 与表单清单
4. 提取 JS 端点与敏感值 scanner(js 模式) 从前端 JS 中挖掘 API 端点、SPA 路由、疑似密钥
5. 语义化 DAST 候选探测 appsec_probe 针对已观察到的面运行 sqli / xss / broken auth / idor / weak CORS 探测

关键设计:第 5 步只探测"前几步已经观察到的面"。appsec_probe 不会凭空猜测 /admin、/wp-login.php 这类常见路径——如果操作中没有观察到合适的路由,该检查会如实降级,而不是编造发现(详见 appsec-probe.txt)。这就是"证据优先"(evidence-first)的含义。

numasec 终端中 runbook 逐步执行与 findings 发现管理面板

执行契约:Runbook 如何终结随机工具调用

runbook 真正"接管"流程的地方在 runner.ts:

  1. 参数校验:缺必选参数直接报 PlayArgError,不会带着残缺参数硬跑;

  2. 模板替换:{{target}} 等占位符被解析成实际参数值;

  3. 能力门控:带 requires 的步骤会自动探测环境,缺失时进入 Skipped 列表并给出原因;

  4. 返回权威轨迹:输出的执行契约明确要求——

    每条助手消息只执行一个步骤;等待结果后再执行下一步;步骤未跑完不得提前停止;不得重复触发 runbook。

这套规则同样写进了 Agent 提示词 appsec.txt 和斜杠命令模板 runbook.txt:拿到 trace 后,"执行它,而不是重新解释它"。

numasec findings 发现面板:状态、证据、replay 与操作侧栏

从探测到发现:证据、Finding 与报告

runbook 跑完不是结束。numasec 把每一次工具输出落到操作(Operation)中:

  • 📦 证据先行:探测的原始请求/响应包存入 evidence/,候选发现以 candidate 状态关联证据;
  • 🔄 发现生命周期:candidate → observed → verified → reportable,被排除的标记 rejected,过时的标记 stale。报告绝不因为"模型语气自信"就过度声明;
  • 📤 可交接:/share 一键导出脱敏的操作包,report 从真实操作状态生成交付物。

操作流程与目录结构(ledger / evidence / replay / deliverable)在官方文档 docs/OPERATIONS.md 中有完整说明,工具参考见 docs/TOOLS.md。

numasec operations 操作选择器:命名、恢复与切换安全操作

延伸:其他内置 Runbook 与相关模块

appsec-web-triage 只是 runbook 注册表(registry.ts)中的 12 个内置之一。用 /runbook list 可查看全部及就绪状态(ready / degraded / unavailable),常用几个:

  • web-surface:Web 表面清点,适合渗透起步;
  • appsec-triage:面向代码仓库的静态分诊;
  • api-surface / auth-surface:API 与认证面专项。

runbook 的底层工具实现位于 runbook.ts,它会把执行计划、就绪事实持久化到操作内核中,因此关掉终端再回来,工作仍然可以从上次的位置继续。

小结

  • ✅ Runbook = 把安全领域知识固化成确定轨迹,AI 只按序执行,不再随机调用工具;
  • ✅ appsec-web-triage 五步走:doctor → knowledge → crawl → js → appsec_probe,全程证据优先;
  • ✅ 执行契约 + 能力门控,让缺失工具"诚实降级"而不是硬造结果;
  • ✅ 发现带状态、带证据、可 replay,最终从操作状态生成报告。

如果你只记一条命令,那就是:

/runbook run appsec-web-triage http://localhost:3000
登录后查看全文
numasec