把安全扫描器封装成可复用 Agent 技能

AI Agent 会调用命令，不代表它知道什么时候该调用、怎样解释结果。AttackSurfaceX 的维护者把自己的开源安全扫描器封装成一个 SKILL.md，重点放在四件事：先确认授权、写清工具边界、教会结果解读、避免重复报告。

这篇文章值得看的，是如何把工具的使用经验变成 Agent 能执行的规则。一个 Markdown 文件可以承载这些规则，但它能否真正约束执行、减少误报，还需要分清作者的实践与尚未验证的判断。

一个 SKILL.md，要教会 Agent 哪些事

AttackSurfaceX，简称 ASX，是采用 MIT 协议、要求 Python 3.11+ 的攻击面扫描器。作者强调它刻意采用非破坏性设计，并称工具无法发送会改变目标状态的请求。

把它包装成 skill，只新增了一个文件：skills/asx-security-scan/SKILL.md。文件由 YAML frontmatter 和操作说明组成，前者声明名称、描述，后者写明适用条件、安装方式、运行边界与结果解释。示例名称是 asx-security-scan。

作者观察到，Agent 不会像认真接手项目的开发者一样通读 README、逐个查参数。缺少明确说明时，它可能直接猜。因此，skill 不能只列 CLI 用法，还要交代工具为什么这样设计，以及哪些限制不能绕过。

安装命令本身很短，解决的是让运行环境具备扫描能力：

pipx install git+https://github.com/gevarru/AttackSurfaceX.git

要注意，这一行只负责安装；作者要求实际扫描始终从 -p safe 开始，不能把安装完成当作已经满足执行条件。

作者称，同一个文件可用于当前支持 skills 的本地编程 Agent、云端和桌面 Agent，skillsmp、skillsllm、lobehub 也分发这种格式。调用方式可能是斜杠命令，也可能是任务匹配描述后自动加载。原文没有列出具体产品版本和兼容性测试矩阵。

为什么授权和禁令要放在命令前面

作者把授权检查放在 skill 开头：目标必须属于用户，或者用户持有书面授权；没有权限就不扫描。随后明确禁止漏洞利用、模糊测试（fuzzing）和提高扫描速率。

这个顺序很实际。Agent 接到「帮我看看这个域名安全吗」时，首先需要判断能不能执行，然后才是选择参数。把授权要求塞进文末，容易让它在已经规划好扫描步骤后才遇到限制。

skill 应该同时说明执行条件和能力边界。

不过，两者的约束强度不同。作者所说的「工具无法发送改变状态的请求」，属于工具实现层面的限制；「不要提高速率」属于给 Agent 的行为指令。前者靠程序约束，后者仍依赖 Agent 正确遵循说明。原文没有提供验证这些约束的测试过程。

扫描结果不能直接变成风险结论

作者最有价值的经验，集中在结果解释上。

第一，LOW 通常是加固缺口，应该给出具体需要补充的响应头；INFO 则提供上下文。原文没有列出具体响应头，不能自行补成一份确定的修复清单。

第二，SPA 的兜底路由可能让所有路径都返回 200。仅看状态码，会把正常的页面回退误认成真实资源。作者要求观察返回内容的差异。对前端团队来说，这个例子很直观：开发服务器或线上路由配置返回了首页，不代表被探测的路径真的存在。

第三，地域过滤可能表现为 TLS 失败。作者在实际运行中遇到过所有端口均显示 closed、TLS 持续失败的情况，要求 Agent 提示目标可能过滤当前地区，而不是直接报告 CWE-326 弱加密问题。

最后，内置模块与插件可能报告同一个问题。作者称扫描器现在会结合标题的 Jaccard 相似度、相同 CWE 和相同目标合并重复发现。Jaccard 可以理解为比较两组内容的重合程度，但原文没有说明标题如何拆分、阈值如何设置。Agent 还要读取 duplicates_suppressed，避免把已抑制的重复项再次报告出来。

我的判断

我赞同把解读规则放进 skill。对扫描工具来说，命令执行成功只是中间状态，用户最终需要知道发现是否可信、应该处理什么。SPA 兜底和重复报告，都是比安装教程更值得保留的操作经验。

但地域过滤需要保留不确定性。仅凭一个网络位置看到端口关闭、TLS 失败，尚不足以确定原因就是地域限制。原文使用「看起来在过滤当前地区」这样的表述更合理，不该把它写成确定诊断。

与只提供 README 或 CLI 帮助相比，skill 更适合直接交代任务触发条件和判断流程；但它不能替代工具自身的权限控制、参数校验与测试。作者没有给出封装前后的误报率、执行成功率或跨 Agent 对照数据，因此「一个文件适配各类 Agent」目前应视为作者的实践陈述。

能拿来做什么

• 给现有 CLI 编写 skill 时，把授权条件、禁止动作和默认参数放在执行步骤前，并在工具代码中校验关键限制。
• 为前端项目整理扫描解释规则，明确 SPA 兜底返回 200 时需要检查内容差异，避免仅凭状态码判断资源存在。
• 让 AI 编程助手生成扫描报告前，先检查重复发现和 duplicates_suppressed，将同一问题合并后再给出修复建议。
• 把实际运行中确认过的误报案例写进 skill，同时保留判断前提；网络不可达时，应先报告观测结果与不确定性。