ruflo Security Audit Skill 实战指南：安全扫描、CVE 修复与 STRIDE 威胁建模-港品优选

ruflo Security Audit Skill 实战指南：安全扫描、CVE 修复与 STRIDE 威胁建模

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

本文以 ruflo 仓库中.agents/skills/security-audit/SKILL.md文档为主体，完整讲解该安全审计 Skill 的触发条件、全部扫描命令、配套 Shell 脚本与最佳实践，并结合 CLI 真实实现源码 security.ts 与配套测试用例，剖析扫描管线的三阶段设计、fail-closed 参数校验和结果持久化机制。读完后，你可以直接在项目中使用该 Skill 完成输入校验、路径穿越、SQL 注入、XSS、硬编码密钥与依赖 CVE 的全面检查，并理解每条命令背后的实现原理。

Skill 定位：何时触发、何时跳过

SKILL.md 将 security-audit 定义为“综合安全扫描与漏洞检测”能力，覆盖输入验证（input validation）、路径穿越防护（path traversal prevention）、CVE 检测和安全编码模式强制检查。其 Frontmatter 明确给出了两类边界条件：

触发场景（When to Trigger）——出现以下任一类变更时，Agent 应激活该 Skill：

认证实现（authentication implementation）
授权逻辑（authorization logic）
支付处理（payment processing）
用户数据处理（user data handling）
新建 API 端点（API endpoint creation）
文件上传处理（file upload handling）
数据库查询（database queries）
外部 API 集成（external API integration）

跳过场景（When to Skip）——以下低风险变更无需运行安全扫描：

对公开数据的只读操作
内部开发工具
静态文档
样式（styling）变更

这种“按变更类型路由”的设计保证了安全扫描只出现在真正引入攻击面的代码路径上，避免在纯文档或样式提交中制造噪音。

命令全集：从全量扫描到单点检查

SKILL.md 按功能划分了 8 组命令，以下完整继承原文档的命令与示例：

1. 全量安全扫描（Full Security Scan）

对代码库执行综合安全分析：

npx @claude-flow/cli security scan --depth full

带输出报告的完整示例：

npx @claude-flow/cli security scan --depth full --output security-report.json

2. 输入验证检查（Input Validation Check）

检查输入验证问题，可配合--path限定扫描范围（如./src/api）：

npx @claude-flow/cli security scan --check input-validation

npx @claude-flow/cli security scan --check input-validation --path ./src/api

3. 路径穿越检查（Path Traversal Check）

npx @claude-flow/cli security scan --check path-traversal

4. SQL 注入检查（SQL Injection Check）

npx @claude-flow/cli security scan --check sql-injection

5. XSS 检查（XSS Check）

npx @claude-flow/cli security scan --check xss

6. 依赖 CVE 扫描（CVE Scan）

扫描依赖树中的已知 CVE，可用--severity high过滤高危项：

npx @claude-flow/cli security cve --scan

npx @claude-flow/cli security cve --scan --severity high

7. 安全审计报告（Security Audit Report）

生成完整审计报告，支持指定输出格式（如 markdown）与输出文件：

npx @claude-flow/cli security audit --report

npx @claude-flow/cli security audit --report --format markdown --output SECURITY.md

8. 威胁建模（Threat Modeling）

npx @claude-flow/cli security threats --analyze

9. 硬编码密钥校验（Validate Secrets）

npx @claude-flow/cli security validate --check secrets

命令参数与源码实现的对照

上述命令来自 SKILL.md 的文档约定；而 CLI 的实际选项定义在 security.ts 中，做源码级核对时需要注意以下几点事实：

security scan实际声明的选项为--target/-t（目标路径，默认.）、--depth/-d（quick | standard | deep，默认standard）、--type（code | deps | all，默认all）、--output/-o、--fix/-f（可自动修复时自动修复）。
文档中使用的--depth full在源码中是已废弃取值：源码通过DEPRECATED_SCAN_DEPTHS = { full: 'deep' }（security.ts#L40）把full归一化为deep并打印警告。源码注释解释了原因——CLI 自己的状态栏提示、发布说明和若干 agent 定义都告诉用户执行security scan --depth full，硬拒绝会破坏所有既有调用方，因此保留别名并告警，待这些“发射源”老化后移除。
未识别的枚举值采用fail-closed（失败即关闭）策略：早期版本中未知的--depth会静默落入最浅的遍历（--depth full反而比默认standard扫得更浅），未知的--type会跳过所有阶段却打印 “No security issues found!” 并以退出码 0 结束——拼写错误与“干净结果”无法区分。现在这些输入在任何扫描发生前就会被显式拒绝（security.ts#L77-L113）。
--type container在帮助文本中一直被宣传，但从未有对应实现阶段，源码会显式拒绝它并给出“尚未实现”的专门提示（security.ts#L42-L47）。
--target必须存在且必须是目录，否则直接报错退出，防止“扫了个不存在的路径 → 零发现 → 持久化一份 CLEAN 报告”的 fail-open 链路（security.ts#L115-L129）。
security cve实际选项为--check/-c（按 CVE 编号过滤）、--list/-l、--severity/-s；security secrets是独立子命令，选项为--action/-a、--path/-p、--ignore/-i。文档中的security cve --scan、security validate --check secrets等写法应理解为“扫描依赖 CVE”“校验密钥”的语义化描述，落地时以源码中的选项定义为准。

扫描管线源码剖析：三个阶段与深度预算

security scan的核心实现（security.ts#L141-L297）由三个阶段组成，理解它对判断“为什么扫到了/没扫到”非常关键。

深度预算表

目录递归深度按扫描深度分级，以“全量记录”而非链式三元表达式实现，新增深度级别会直接变成编译错误，而不是静默变浅（security.ts#L49-L54）：

阶段	quick	standard（默认）	deep
密钥扫描深度`SECRET_SCAN_DEPTH`	3	5	10
代码模式扫描深度`CODE_SCAN_DEPTH`	0（该阶段被门控跳过）	5	10

递归函数使用正向断言if (!(depthLimit > 0)) return;而不是<= 0——因为undefined和NaN都无法通过正向断言，任何非法预算都会停止递归而非禁用限深器（security.ts#L209-L212）。

阶段一：依赖审计（type 为`all`或`deps`时执行）

在目标目录下执行npm audit --json（10MB 输出缓冲），解析audit.vulnerabilities，按critical / high / moderate|medium / low四个级别计数，并把每条漏洞（含via[0].title截断到 35 字符）记入 findings，位置标注为package.json:<包名>（security.ts#L146-L189）。由于npm audit在发现漏洞时以非零码退出但 stdout 仍有 JSON，实现中对execSync的异常做了显式捕获并复用 stdout。

阶段二：硬编码密钥扫描（type 为`all`或`code`时执行）

对ts/js/json/env/yml/yaml扩展名的文件（排除.d.ts，跳过隐藏目录、node_modules、dist）逐行匹配 5 组正则（security.ts#L194-L207）：

正则（节选）	判定类型
`(?<![a-zA-Z0-9_])(?:sk-\\|sk_live_\\|sk_test_)[a-zA-Z0-9]{10,}(?![a-zA-Z0-9_])`	API Key（Stripe/OpenAI）
`['"]AKIA[A-Z0-9]{16}['"]`	AWS Access Key
`['"]ghp_[a-zA-Z0-9]{36}['"]`	GitHub Token
`['"]xox[baprs]-[a-zA-Z0-9-]+['"]`	Slack Token
`password\s[:=]\s['"][^'"]{8,}['"]`（忽略大小写）	Hardcoded Password

其中 API Key 正则的写法带有明确的修复历史：旧版要求引号紧邻前缀且密钥长度 ≥20，会漏掉sk-1234567890abcdef这类 16 位短 key，也漏掉Authorization: "Bearer sk_live_..."这种引号贴着 "Bearer" 的常见形态；改用环视边界（lookaround）后按独立 token 匹配（源码注释标注为 #2931 修复，对应测试 security-scan-secret-regex-2931.test.ts）。所有命中均计为 HIGH 级 “Hardcoded Secret” finding，位置精确到相对路径:行号。

阶段三：代码安全模式分析（depth 不为`quick`时执行）

对ts/js/tsx/jsx文件匹配 5 组代码风险模式（security.ts#L251-L257）：

模式（节选）	类型	级别	说明
`eval\s*\(`	Eval Usage	medium	eval() 可执行任意代码
`innerHTML\s*=`	innerHTML	medium	innerHTML 的 XSS 风险
`dangerouslySetInnerHTML`	React XSS	medium	React XSS 风险
`child_process.*exec[^S]`	Command Injection	high	可能的命令注入
`\$\{.\}.sql\\|sql.*\$\{`（忽略大小写）	SQL Injection	high	可能的 SQL 注入

这与 SKILL.md 中--check input-validation / path-traversal / sql-injection / xss单点检查项在语义上对应——扫描器把这几类风险编码为可复用的正则目录。

结果输出、持久化与自动修复

终端以表格输出前 20 条 findings（超出部分显示 “... and N more issues”），再输出含 Target/Depth/Type 与四级计数的 Scan Summary 汇总框（security.ts#L301-L329）。
扫描结果会持久化到<target>/.claude/security-scans/scan-${type}-${depth}.json，文件名由扫描配置决定、重复执行时覆盖而非累积过期报告；状态栏的getSecurityStatus（funnel/local-signals.ts）正是读取该目录反映真实扫描状态。写入是 best-effort：失败不会影响扫描本身（security.ts#L331-L358），对应测试 security-scan-persistence.test.ts。
指定--fix且存在 critical 或 high 发现时，自动在目标目录执行npm audit fix（security.ts#L360-L373）。
返回值语义：只有“零发现”或“无 critical 且无 high”时success为真，为 CI 门禁提供退出码语义。

CVE 子命令：基于 npm audit 的漏洞过滤

security cve不再是存根（源码注释标注 #2403 起），它委托给npm audit --json（30 秒超时）作为数据源，与security scan同源，再叠加两层过滤（security.ts#L397-L482）：

--check CVE-XXXX：用正则CVE-\d{4}-\d{4,7}从漏洞的 title/url 文本中提取全部 CVE 编号，按编号大小写不敏感过滤；
--severity：按 severity 过滤，并做了medium/moderate的别名归一（npm 输出用moderate）。

输出为 SEVERITY / PACKAGE / CVE IDs / TITLE 四列对齐表格，并在无命中时明确提示数据源为npm audit --json（GitHub Advisory DB）。若项目目录没有package.json（JSON 解析失败），命令打印警告并以退出码 2 结束。SKILL.md 中security cve --scan --severity high的“按高危过滤”意图，即对应这里的--severity high能力。

威胁建模子命令：STRIDE 框架落地

SKILL.md 的security threats --analyze对应源码中的threats子命令（security.ts#L486-L731），它把 STRIDE 六类威胁编码为可执行的检测规则，--model支持stride | dread | pasta（默认 stride），--scope限定分析范围，--export json可导出发现清单：

扫描约束：最多 500 个文件（MAX_FILES），跳过node_modules/dist/.git与隐藏目录，单文件超过 1MB 直接跳过；
STRIDE 模式目录（security.ts#L521-L550）：
- Spoofing：无认证中间件的 HTTP 端点（如app.get('/path', (req...）；
- Tampering：eval()、execSync()、模板字符串拼接的exec()、new Function()等代码注入向量（high）；
- Info Disclosure：硬编码凭据（high）、AWS Key（critical）、GitHub token（high）、PEM 私钥头（critical）、非 localhost 的http://明文 URL（medium）；
- DoS：检测到 Express/Fastify 时提示验证限流配置（low）；
- Elevation：来自请求的JSON.parse（medium）、__proto__访问（high，原型链污染）、Object.assign({}, req...)（medium）。
git 仓库专项检查：checkEnvInGit()通过git ls-files --cached检测被 git 跟踪的.env文件，命中即记为 CRITICAL（security.ts#L552-L566）。
缺失中间件检查：对引用了 express/fastify 的服务文件，检查是否缺少 helmet/lusca 安全头（MEDIUM）、CORS 中间件（LOW）、限流中间件（MEDIUM）（security.ts#L614-L648）。
输出包含按 STRIDE 类别的汇总表，并始终附带 STRIDE 参考框架表（每类威胁的评估问题与缓解示例，如 Spoofing → 强认证/mTLS、Repudiation → 审计日志/签名提交）。

配套脚本：security-scan.sh 与 cve-remediate.sh

SKILL.md 在 Scripts 一节声明了两个脚本（文档中路径写作.agents/scripts/），在仓库中的实际位置为.agents/skills/security-audit/scripts/目录：

脚本	实际路径	职责
`security-scan`	security-scan.sh	顺序执行完整安全扫描流水线
`cve-remediate`	cve-remediate.sh	自动修复已知 CVE

security-scan.sh采用set -e快速失败语义，依次串联六个阶段（与上文 scan 的阶段划分一一对应）：

#!/bin/bash # Security Audit - Full Scan Script set -e echo "Running full security scan..." npx @claude-flow/cli security scan --check input-validation # 输入验证 npx @claude-flow/cli security scan --check path-traversal # 路径穿越 npx @claude-flow/cli security scan --check sql-injection # SQL 注入 npx @claude-flow/cli security scan --check xss # XSS npx @claude-flow/cli security validate --check secrets # 硬编码密钥 npx @claude-flow/cli security cve --scan # CVE 扫描 echo "Security scan complete"

cve-remediate.sh则是“扫描 → 修复 → 复扫”闭环：

#!/bin/bash # Security Audit - CVE Remediation Script set -e npx @claude-flow/cli security cve --scan --severity high # 先定位高危 CVE npm audit fix # 自动修复 npx @claude-flow/cli security cve --scan # 复扫确认 echo "CVE remediation complete"

这个“修复后复扫”的模式与 CLI 内--fix后的提示（“Applied available fixes (run scan again to verify)”）思路一致：自动化修复只承诺尽力而为，验证必须重新跑一遍扫描。

测试证据：fail-closed 语义如何被锁定

security scan的枚举校验不是口头承诺，而是由专门回归测试锁定的（security-scan-enum-validation.test.ts）。该测试文件头注释概括了修复背景：“security scanused to fail open on an unrecognised --depth, --type or ...”，关键断言包括：

--depth bogus-value必须输出Invalid --depth 'bogus-value'并退出，而不是扫得更浅；
--type bogus-type与大小写异常的--type CODE均被拒绝（枚举比较大小写不敏感地命中“未实现/非法”分支）；
--type container/--type Container得到专门的“尚未实现”提示；
报告文件名由scan-${type}-${depth}.json构造，测试验证了--type ../../../escaped之类的路径穿越值不会逃出扫描报告目录；
空字符串--depth ''被当作未提供，回落到文档声明的默认值。

另有 security-scan-persistence.test.ts 覆盖扫描结果持久化路径，security-scan-secret-regex-2931.test.ts 覆盖 API Key 正则的短 key 与 Bearer 形态修复。

最佳实践（SKILL.md 原文四条）

文档末尾的 Best Practices 给出四条执行纪律，完整保留如下：

开始前先检查 memory 中已有的模式（Check memory for existing patterns before starting）；
协调时使用分层拓扑（Use hierarchical topology for coordination）;
完成后存储成功的模式（Store successful patterns after completion）；
记录任何新学到的知识（Document any new learnings）。

这四条把安全扫描从“一次性命令”提升为“可积累的审计经验”：同类项目的发现与修复路径会沉淀进 Agent 记忆，下一次审计可直接复用。

参考文档说明

SKILL.md 的 References 一节点名两份文档：Security Checklist（docs/security-checklist.md）与 OWASP Guide（docs/owasp-top10.md），分别用作安全评审清单与 OWASP Top 10 缓解指南。在当前仓库快照中未检索到这两个文件，因此本文不做链接引用；若你在完整 checkout 中看到它们，可直接配合上文命令使用。仓库根目录另有一份 SECURITY.md，可作为项目安全策略的补充阅读。

上手方式与适用前提

运行环境：命令均以npx @claude-flow/cli security ...形式给出，需要已安装 Node.js 环境；CLI 的源码位于 v3/@claude-flow/cli 目录。依赖类检查（阶段一、CVE 子命令）要求目标目录是带package.json的 npm 项目，且npm audit可访问其 advisory 数据源。
典型工作流：
1. 涉及认证/授权/支付/上传/数据库查询等变更时，先跑npx @claude-flow/cli security scan --depth full（源码会将其归一化为 deep 并提示改用--depth deep）；
2. 依赖问题用security cve按 severity/CVE 编号过滤，必要时走cve-remediate.sh的“修复-复扫”闭环；
3. 面向架构评审时运行security threats，拿到按 STRIDE 分类的发现与参考框架，可用--export json归档；
4. 扫描报告会自动落在<target>/.claude/security-scans/下，可被状态栏与下游流程消费，无需手工整理。
适用限制：代码阶段模式扫描受深度预算约束（quick 下阶段三完全跳过，deep 才能递归 10 层）；威胁建模与密钥子命令各自存在 500 文件的扫描上限与 1MB 单文件大小上限，超大仓库应配合--target/--scope/--path分片扫描。正则型扫描属于启发式检查，源码注释亦多处将其定位为“提示复查”（如 Express 检测仅提示“verify rate-limiting is configured”），不能替代人工安全评审。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析