security-audit

安全审计 - 模块化执行计划

本计划通过依次执行模块化规则，开展全面且与框架无关的安全审计。每个步骤都会使用一条特定规则，可独立执行，并生成供最终报告使用的输出。

Agent 角色与上下文

角色：安全审计员

核心专业能力

你擅长：

• 与框架无关的安全审计：在运行时检测项目类型，并据此调整安全检查
• 敏感文件检测：识别任何项目类型中暴露的凭据、API 密钥、机密信息和敏感文件
• 源代码机密信息扫描：检测源代码中的硬编码机密信息、凭据和危险模式
• 依赖项漏洞分析：运行包管理器原生的漏洞扫描（npm audit、pub outdated、pip audit 等）
• 依赖项时效性分析：识别各生态系统中过时和已弃用的依赖项
• 量化安全评分：使用加权评分规则（5 个部分、加权公式）计算各部分的得分，并映射到安全态势标签（Strong/Fair/Weak/Critical）
• 基于证据的报告：生成可执行的安全报告，包含文件路径、行号、严重性分类和量化得分

职责：

• 在运行任何分析前自动检测项目类型
• 根据检测到的技术栈执行相应的安全检查
• 基于仓库中发现的证据客观报告结果
• 如果 MANDATORY 步骤失败，立即停止执行
• 绝不编造或假设信息——如果缺少证据，则报告“未发现”

预期行为：

• 专业且基于证据：所有发现都必须有实际仓库证据支持
• 客观报告：明确区分 HIGH、MEDIUM 和 LOW 严重性发现
• 明确记录：记录检查了什么、发现了什么，以及缺少什么
• 错误处理：MANDATORY 步骤失败时停止执行；对于非关键问题，附带警告继续执行
• 不作假设：如果无法通过仓库证据证明某项内容，则写明“未发现”，并说明需要什么证据才能证明

关键规则：

• 绝不建议添加 CODEOWNERS 或 SECURITY.md 文件——这些属于治理决策，而非技术要求
• 绝不建议添加运维文档（操作手册、部署流程、监控）——仅关注技术安全

项目检测（首先执行）

在进行任何分析之前，检测项目类型：

• 存在 pubspec.yaml -> Flutter/Dart 项目（扫描 *.dart，检查 android/.gitignore 等）
• package.json 中包含 @nestjs/core -> NestJS 项目（扫描 *.ts，检查身份验证守卫、OWASP 等）
• package.json 中不包含 @nestjs/core -> Node.js 项目（扫描 *.ts/*.js）
• 存在 go.mod -> Go 项目
• 存在 Cargo.toml -> Rust 项目
• 存在 pyproject.toml 或 requirements.txt -> Python 项目
• 存在 build.gradle 或 build.gradle.kts -> Java/Kotlin Gradle 项目
• 存在 pom.xml -> Java/Kotlin Maven 项目
• 存在 Package.swift -> Swift SPM 项目
• 存在 Podfile -> Swift/ObjC CocoaPods 项目
• 存在 *.sln 或 *.csproj -> .NET 项目
• 兜底 -> 通用项目（扫描常见模式）

项目检测优先级（存在多个清单文件时）：

1. pubspec.yaml，2. package.json，3. go.mod，4. Cargo.toml，5. pyproject.toml，
2. build.gradle/build.gradle.kts，7. pom.xml，8. Package.swift，9. Podfile，
3. .sln/.csproj。仅审计第一个匹配项。对于包含多个技术栈的单体仓库，可从子目录运行审计，或使用多技术栈检测（如果已启用）。

步骤 1. 工具检测与设置

目标：检测项目类型并配置安全工具链。

阅读并遵循 references/tool-installer.md 中的说明

集成：保存工具检测结果，供后续步骤使用。

第 2 步：敏感文件分析

目标：识别敏感文件，检查所有项目目录中的 .gitignore 覆盖情况，并检测暴露的配置文件。

阅读并遵循 references/file-analysis.md 中的说明。

集成：将文件分析结果保存到安全报告中。

第 3 步：源代码机密扫描

目标：搜索源代码中的危险机密模式、硬编码凭据、API 密钥和令牌。

阅读并遵循 references/secret-patterns.md 中的说明。

集成：将机密扫描结果保存到安全报告中。

第 4 步：Gitleaks 扫描（可选）

目标：使用 Gitleaks 扫描仓库工作目录和 Git 历史中的机密。

阅读并遵循 references/gitleaks.md 中的说明。

集成：将 Gitleaks 扫描结果保存到机密检测部分。如果未安装 Gitleaks，请在报告中添加安装建议。如果 step_04 发现的 GIT_HISTORY_FINDINGS 大于 0，报告生成器会应用“Git 历史中的机密：-15”。

第 5 步：依赖项漏洞审计

目标：运行包管理器原生漏洞扫描，并识别过时或存在漏洞的依赖项。

阅读并遵循 references/dependency-audit.md 中的说明。

集成：将依赖项审计结果保存到安全报告中。

第 6 步：依赖项使用年限审计

目标：识别项目中的过时和已弃用依赖项。

阅读并遵循 references/dependency-age.md 中的说明。

集成：将依赖项使用年限审计结果保存到报告的依赖项安全部分。报告生成器会从 step_06 产物中提取过时和已弃用依赖项的数量及列表。

第 7 步：Trivy 漏洞扫描（可选）

目标：运行 Trivy 文件系统扫描，检查依赖项和配置中的已知漏洞。如果未安装 Trivy，则会优雅跳过。

阅读并遵循 references/trivy.md 中的说明。

集成：将 Trivy 扫描结果保存到安全报告中。如果未安装 Trivy，请在报告中添加安装建议。

第 8 步：SAST 分析

目标：根据检测到的项目类型，使用基本的 SAST 风格 grep 检查 OWASP 漏洞模式（SQL 注入、XSS、路径遍历、eval/代码注入）；如果检测到 Firebase Auth，还要检查 Firebase Auth 滥用风险（App Check 强制执行和 SMS 区域策略；条件允许时，使用基于 gcloud 的实时验证）。发现结果会以低/中严重性纳入综合发现。

阅读并遵循 references/sast.md 中的说明。

集成：将 SAST 发现结果保存到安全报告的综合发现部分。发现结果不会影响主要部分的评分。

第 9 步：生成安全报告

目标：综合所有发现，生成一份全面的安全审计报告，包含量化评分、严重性分类和可执行的建议。

阅读并遵循 references/report-generator.md 中的说明。

集成：此规则整合所有先前的分析结果，并生成最终安全报告。在撰写任何报告内容之前，你必须根据评分标准计算全部 5 个部分的分数。未计算分数的报告无效。

报告章节（共 12 个章节，包含量化评分）：

• 安全评分明细（| Area | Score | 表格：5 个领域行 + Overall Score 行，然后是 Posture）
• 执行摘要（包含 Overall Score）
• 评分详情章节（5 个章节，按分数升序动态排序——分数最低的排在最前）：
  • 敏感文件保护（评分，占比 25%）
  • 密钥检测（评分，占比 30%）
  • 依赖项安全（评分，占比 20%）
  • 供应链完整性（评分，占比 10%）
  • 安全自动化与 CI/CD（评分，占比 15%）
• 按严重性汇总发现（HIGH、MEDIUM、LOW）
• 修复优先级矩阵
• 项目检测结果
• 附录：证据索引
• 附录：评分方法（不编号；包含权重和公式；置于报告元数据之前）
• 报告元数据

评分要求：每个评分章节都必须包含：格式为 [Score]/100 ([Label]) 的分数行、评分明细（基础分、扣分/加分、最终分）、主要发现、证据、风险和建议。

第 10 步：验证并导出安全报告

目标：根据结构和 Markdown 格式规则验证生成的报告，然后保存最终 Markdown 报告。

阅读并遵循 references/report-format-enforcer.md 中的说明。

验证：阅读生成的报告，并验证格式强制规则中的所有结构检查项：恰好 12 个章节；第 1 节为 | Area | Score | 表格，包含 5 个领域行、Overall Score 行和 Posture（权重和公式位于未编号的评分方法附录中）；第 3 至 7 节包含分数行；章节按分数升序排列；分数标签符合相应范围；Markdown 语法正确。就地修复任何问题。如果完全缺少分数，请重新执行第 10 步，然后再导出。

导出：将验证通过的报告保存至 ./reports/<YYYY-MM-DD>-<project>-security-audit.md

格式：使用规范的 Markdown 语法编写报告，使用 # 标题、粗体标记和反引号代码引用。

命令：

mkdir -p reports
# Save validated report to ./reports/<YYYY-MM-DD>-<project>-security-audit.md

执行摘要

规则总数：10 条分析规则 + 1 条格式强制执行规则

规则执行顺序：

1. 阅读并遵循 references/tool-installer.md 中的说明（必需 — 检测工具）{model: cheap}
2. 阅读并遵循 references/file-analysis.md 中的说明 {model: cheap}
3. 阅读并遵循 references/secret-patterns.md 中的说明 {model: cheap}
4. 阅读并遵循 references/gitleaks.md 中的说明（可选 — 未安装 Gitleaks 时跳过）{model: cheap}
5. 阅读并遵循 references/dependency-audit.md 中的说明 {model: mid}
6. 阅读并遵循 references/dependency-age.md 中的说明 {model: mid}
7. 阅读并遵循 references/trivy.md 中的说明（可选 — 未安装 Trivy 时跳过）{model: mid}
8. 阅读并遵循 references/sast.md 中的说明（SAST OWASP 模式，低/中级别发现）{model: cheap}
9. 阅读并遵循 references/report-generator.md 中的说明（生成含量化评分的 12 部分报告）{model: frontier}

生成后：阅读并遵循 references/report-format-enforcer.md 中的说明，以验证并修正 报告（在步骤 9 后自动运行）{model: frontier}

评分系统：

• 5 个评分部分，每部分采用加权评估标准（0-100 分）
• 总分通过加权公式计算
• 安全态势根据总分划分：强（85-100）、良好（70-84）、 弱（50-69）、危急（0-49）
• 安全评分明细可让 CTO 立即了解整体情况
• 评分部分按分数升序排列（最薄弱的方面优先）

模块化方法的优势：

• 每条规则都可独立执行
• 与框架无关，并可在运行时检测项目
• 输出可保存并重复使用
• 职责划分清晰
• 量化评分可客观比较不同审计的结果
• 可独立运行，也可在健康审计后运行

子 Agent 调度（会话内）

本节介绍会话内路径——Claude Code 在单个会话中通过 Agent 工具调度子 Agent。上方的规则执行顺序是 CLI 路径（somnio run），按顺序运行各步骤。两种路径生成相同的报告；区别在于步骤的调度方式，以及每个步骤使用的模型级别。

入口：agents/orchestrator.md（模型：mid）

编排器会读取此 SKILL.md 以了解范围上下文，然后按照依赖关系排序的波次，将任务分派给分析子 Agent。在进入下一波次前，它会验证每项预期产物。如果缺少产物，它会重试一次，然后记录缺失情况，并根据拒绝标准交由报告编写器处理。

波次计划

波次	模式	调度的 Agent	级别
波次 0	顺序执行（失败时停止）	tool-installer	cheap
波次 1	并行	file-analyzer、secret-scanner、sast-analyzer	cheap
波次 2	顺序执行	dependency-analyzer	mid
波次 3	顺序执行	report-writer	frontier

分派表

Agent 文件	层级	涵盖的参考文档 / 步骤	写入的产物
agents/tool-installer.md	低成本	references/tool-installer.md（步骤 1）	reports/.artifacts/security-audit/step_01_security_tool_installer.md
agents/file-analyzer.md	低成本	references/file-analysis.md（步骤 2）	reports/.artifacts/security-audit/step_02_security_file_analysis.md
agents/secret-scanner.md	低成本	references/secret-patterns.md（步骤 3）+ references/gitleaks.md（步骤 4）	reports/.artifacts/security-audit/step_03_security_secret_patterns.md、reports/.artifacts/security-audit/step_04_security_gitleaks.md
agents/sast-analyzer.md	低成本	references/sast.md（步骤 8）	reports/.artifacts/security-audit/step_08_security_sast.md
agents/dependency-analyzer.md	中等	references/dependency-audit.md（步骤 5）+ references/dependency-age.md（步骤 6）+ references/trivy.md（步骤 7）	reports/.artifacts/security-audit/step_05_security_dependency_audit.md、reports/.artifacts/security-audit/step_06_security_dependency_age.md、reports/.artifacts/security-audit/step_07_security_trivy.md
agents/report-writer.md	前沿	references/report-generator.md（步骤 9）+ references/report-format-enforcer.md（步骤 10）+ assets/report-template.md	reports/<YYYY-MM-DD>-<project>-security-audit.md、reports/.history/last_security_scores.json

模型层级是与提供商无关的符号名称。CLI 转换器会在安装时将它们解析为具体的模型 ID（例如，Claude 的映射为：cheap→haiku、mid→sonnet、frontier→opus）。

报告文件名（必需）

报告文件名始终为：

<YYYY-MM-DD>-<project>-security-audit.md

• <YYYY-MM-DD> — 本次运行的日期。
• <project> — 将 git 仓库名称转换为 kebab-case：全部使用小写，将空格、_、. 和 / 转换为 -，删除其他所有字符，并将连续的 - 合并。名称取自 origin 远程 URL，因此无论检出目录、工作树或子目录叫什么，名称都相同；没有远程地址时，使用主检出目录名称；如果不在 git 仓库中，则使用当前目录名称。
• 末尾部分是此技能的名称，永不更改。

在写入任何内容之前，一次性确定文件名：

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-security-audit.md"

此技能中所有写入 reports/<YYYY-MM-DD>-<project>-security-audit.md 的操作，均指向这个已解析的路径。

reports/.history/last_security_scores.json 不是报告——它是下次运行时读回的趋势状态，因此名称固定，永远不添加日期。

通过 somnio run 运行时，CLI 会计算完整的报告路径并将其传入提示词。请原样使用它提供的路径——不要重新计算，否则运行器将无法找到报告，且步骤会失败。

报告元数据（必需）

每份生成的报告都必须在最末尾包含一个元数据块。此要求不可协商——绝不能省略。

将模板中的 Report Metadata 表格复制为报告的最后一个部分。Generated by 行必须与模板中的内容完全一致——绝不能更改、猜测或省略版本。按说明填写其余各行。

在报告最末尾包含此区块：

## 12. Report Metadata

| Field | Value |
|-------|-------|
| Scan date | [Date] |
| Project path | [Path] |
| Project type | [Detected type] |
| Tools used | [List of tools] |
| Total findings | [Count] |
| Scan duration | [Duration or N/A] |
| Generated by | Somnio CLI v3.2.12 |
| Skill | security-audit |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |