security-audit

安全审计技能

目的

以威胁模型为先，对代码库进行全面的安全审计，生成结构化报告，并根据影响 × 可利用性 × 暴露面为发现项排序，将其映射到 CWE 和 OWASP 类别；对于高危和严重发现项，还要提供具体的利用场景。按用户选择的格式（见下文“报告格式”）在项目根目录生成一份独立完整的报告文件：HTML 格式遵循 references/report-template-html.md，Markdown 格式遵循 references/report-template.md。

本技能专注于安全。对于一般代码质量审计（并发、死代码、反模式、性能、正确性、错误处理、测试），请使用同一插件中的同级 code-audit 技能。两种技能可在同一代码库上独立运行，也可按顺序运行。如果在本次审计中偶然发现非安全类代码质量问题，请简要记录，并建议运行 code-audit 技能，而不要在此深入分析。

工作投入

逐行阅读所有审计范围内的代码。不要略读、抽样，也不要依靠启发式方法跳过文件。本次审计的核心方法是源到汇数据流分析——从每个入口点追踪不可信输入，沿调用图一路追踪到每个危险汇，并在每一步评估验证、编码、授权和信任假设。单纯的模式匹配会漏掉真实漏洞；数据流追踪才能发现它们。如果审计范围过大，无法一次完成，请拆分任务并交由多个并行子 Agent 处理（分工策略见阶段 5）。

思维方式

像渗透测试人员一样审计代码：假设任何不可信输入都带有恶意；除非经过验证，否则假设任何检查都可被绕过；除非经过校验，否则假设任何边界都可能被跨越。纵深防御至关重要——当某一层失效时，下一层是什么？关注缺失的控制（本应存在却缺失的检查），而不只是已有的控制（存在但有误的检查）。现实中的大多数安全事件都源于控制缺失、类似批量赋值的过度提交、对象级授权失效，以及对用户可控字段的盲目信任，而非奇特的利用手法。

报告格式

审计会在项目根目录生成一个独立文件。格式决定文件扩展名以及第 6 阶段使用的模板。默认格式为 HTML，因为它支持内嵌 SVG 信任边界和数据流图、严重性 / CWE / OWASP 标签样式、每项服务下可折叠的 Source/Sink Map 条目，以及相关发现之间的锚点交叉引用——这些功能能显著提升长篇安全报告的可读性，而 Markdown 无法实现。

**在确定范围之前，先确定格式。** 这是硬性门槛——在本次运行的格式确定之前，不要开始确定范围、威胁建模、意图发现、源 / 汇映射、分析或任何其他工作。

首先，检查用户的启动消息中是否明确指定了格式。以下信号均可接受：

• HTML 信号：HTML、html、"as a webpage"、"browser-viewable"、"rendered report"。
• Markdown 信号：MD、md、Markdown、markdown、"plain text report"、"as Markdown"。

如果启动消息中包含明确的格式信号，则将其作为门槛问题的答案并继续——不要为了形式再次询问。在说明已确定的范围时，简要说明所选格式。

如果启动消息中未指定格式，则只询问以下问题（或意思相同的问题），并等待用户回答后再继续：

你希望使用哪种报告格式？HTML（默认，包含内嵌信任边界图、CWE/OWASP 标签和严重性徽章的独立文件）还是 MD（纯 Markdown）？

不要将此问题与任何其他输出合并。未询问前不要假定默认格式。每次运行此技能时都必须执行此门槛。

选定格式后，本次运行的其余部分都必须统一使用该格式：

格式	模板	文件名
HTML	references/report-template-html.md	SECURITY-AUDIT-REPORT-YYYY-MM-DD.html
MD	references/report-template.md	SECURITY-AUDIT-REPORT-YYYY-MM-DD.md

生成 HTML 报告时，应将 references/report-template-html.md 中记录的 HTML 专属功能视为可在能提供信息时使用的工具，而非装饰。仅将 Markdown 内容包裹在 HTML 标签中，却不使用这些功能，会违背选择 HTML 的初衷。

工作流

工作流分为六个阶段。第 1 阶段必须先于其他所有阶段；第 2 阶段和第 3 阶段可并行执行（两者之间没有数据依赖）；第 4 阶段依赖第 2 阶段；第 5 阶段和第 6 阶段依赖此前所有阶段。适当时鼓励在各阶段内部并行处理——第 3 阶段始终使用子 Agent（每个扫描器一个）；第 5 阶段使用子 Agent 划分大型范围。

阶段 1 — 确定范围

根据用户的提示确定审计范围。用户可能会指定：

• 整个代码库或工作目录。
• 一个或多个目录（例如，src/、services/api/）。
• 特定文件列表。
• 用自然语言描述的功能区域（例如，“身份验证流程”“文件上传端点”）。
• 文件中的特定函数、类或代码区域。将分析范围限制在指定代码及其直接依赖项。

默认排除生成的文件（锁文件、编译输出、供应商依赖项、压缩包）。对于提交了源代码的生成代码（protobuf 存根、OpenAPI 客户端、ORM 模型），检查是否有修改标记 — 如果文件包含手写内容，或已移除“DO NOT EDIT”标头，则将其纳入范围。第 5 阶段 B 阶段（跨信任边界数据流）仍会追踪流入排除代码的路径，以确定其是否提供预期的验证。

如果用户指定的路径不存在，请警告用户缺少这些路径，并继续处理其余路径。如果指定的路径都不存在，请停止并要求澄清。

如果提示信息不足以确定范围，请先提出一个澄清问题。边界不明确的审计会产生不可靠的结果。

如果用户要求重新审计，请在项目根目录中搜索 SECURITY-AUDIT-REPORT-*.md 和 SECURITY-AUDIT-REPORT-*.html。如果存在多份报告，请按文件修改时间选择最新的一份，无论其格式如何。默认使用与先前审计相同的范围。如果存在先前报告，请在新报告中注明哪些先前发现已解决、哪些仍然存在，以便用户查看差异。新报告的格式遵循本次运行的门控决策，无需与先前报告的格式一致。

向用户说明已确定的范围，并立即继续；只有在范围确实存在歧义时才暂停并等待确认。

阶段 2 — 对应用进行威胁建模

深入阅读代码之前，先构建一份威胁模型简报，为后续审计提供指导。缺少这一步，审计就会变成不加区分的清单扫描；完成这一步，审计才能优先关注真正适用于该应用的威胁。

威胁模型简报应确定：

• 应用类型 — Web API、服务端渲染的 Web 应用、单页应用、CLI、库、移动后端、桌面应用、嵌入式应用、IoT、浏览器扩展。
• 暴露范围 — 面向互联网（匿名流量）、公开但需身份验证、仅限内部（公司网络）、仅限 localhost、单租户、多租户（租户之间相互信任或相互敌对）。
• 敏感数据类别 — 个人身份信息、支付数据、身份验证凭据、会话令牌、健康记录、财务记录、IP／源代码、客户上传的文件。
• 信任边界 — 不可信数据进入的位置、发生权限转换的位置（匿名用户到已验证用户、用户到管理员、租户到租户）、数据跨进程或服务流转的位置。
• 身份验证模型 — 表单登录 + 会话 Cookie、JWT bearer、OAuth/OIDC、mTLS、API 密钥、签名 URL、无。此项决定 references/checklists/auth-and-session.md 中哪些部分适用。
• 授权模型 — RBAC、ABAC、基于所有权、按租户限定、无。此项决定审计必须验证哪些授权检查。
• 外部依赖和集成 — 数据库、缓存、队列、第三方 API、支付处理商、身份提供商；对每项注明信任假设。
• 部署环境 — 容器、无服务器、VM、本地部署；云服务提供商；CI/CD 平台。此项决定适用的 IaC 和 CI/CD 检查清单。
• 适用的检查清单 — 根据上述信号，确定在阶段 5 加载的 references/checklists/*.md 子集（例如，CLI 工具可跳过 XSS/CSRF；公共 API 应包含 API 安全检查）。
• 严重性调整说明 — 应提高或降低默认严重性的应用特定因素（例如，处理 PHI、存在敌对关系的多租户、WAF 后的缓解措施）。

可通过 README、package.json / pyproject.toml / go.mod、Dockerfile、docker-compose.yml、框架特征（Django 设置、Express 中间件、Spring 注解、Rails 路由）、入口文件和目录结构来识别上述信息。只有在无法从代码中明确判断应用类型或暴露范围时，才提出一个澄清问题；否则应推断并记录，以便报告读者进行修正。

威胁模型简报是一份简短的结构化文档（单个服务通常为 200–400 词）。对于包含多个不同服务或应用类型的单体仓库，应为每个服务分别编写一份简报，或编写一份合并简报并明确列出各类应用所面临的威胁；按服务分别编写的形式更易扩展。每次运行审计时都应重新生成简报，切勿在不同运行之间保留。

完整模板、推断启发式和常见应用类型的示例见 references/threat-modeling.md。

第 3 阶段 — 发现安全意图

在分析开始前，扫描已记录的安全决策、威胁模型和已知限制。这样可以区分有意为之的权衡与真正的问题，从而减少误报。

并行运行 3 个子 Agent：

• 文档扫描器 — 阅读项目范围内的文档，特别关注安全相关文件（SECURITY.md、THREAT_MODEL.md、.well-known/security.txt、docs/security/、ADR、合规文档、渗透测试报告）。完整的文件发现清单见 references/intent-discovery.md。
• 代码意图扫描器 — 搜索范围内的源代码，查找安全抑制标记（涵盖 SAST 工具、密钥扫描器和语言检查工具）以及包含安全关键词的理由注释。完整的标记和关键词清单见 references/intent-discovery.md。
• 历史记录扫描器 — 从 git 历史中提取意图信号，优先检查提交信息中提及安全关键词（CVE、漏洞、身份验证、权限提升、披露、加固、绕过、利用、渗透测试等）的提交，以及修改过安全敏感文件的提交。完整的关键词清单和模式指南见 references/intent-discovery.md。

无论代码库大小如何，此步骤始终执行。输出为按主题组织的结构化安全意图简报（已记录的威胁模型、已知风险与权衡、安全规范、已抑制的发现及其理由、历史安全修复）。条目数量不超过 100 项。

如果意图发现未产生任何条目，则简报为空。分析照常继续；报告的“已记录的安全态势”部分会说明未发现任何已记录的意图信号。

有关详细的子 Agent 提示词和简报模板，请参阅 references/intent-discovery.md。

第 4 阶段 — 构建源/汇映射

在标记漏洞前，枚举应用程序的不可信输入来源和危险汇点。该映射将指导后续审计：每项高危/严重级别的注入类发现，都必须追溯到已记录的来源和汇点。

来源包括 HTTP 入口点（请求体、查询参数、路径、标头、Cookie、多部分文件）、作为输入处理的身份验证凭据（解码后的 JWT/OAuth/SSO 声明）、CLI 输入（argv、stdin、env）、消息/事件输入（队列消费者、Webhook 接收器、定时任务负载）、被视为可信的外部调用响应，以及对先前不可信数据的存储读取（二阶来源）。

汇点包括数据库查询构造、Shell 和进程执行、代码执行（eval/Function/动态 import）、反序列化、文件系统操作、HTTP 出站请求（SSRF 攻击面）、模板渲染、HTTP 响应写入（HTML / 重定向 / Set-Cookie / 自定义标头）、日志记录（敏感数据泄漏和日志注入）、加密操作，以及身份验证/授权决策点。

映射无需写成详尽的说明文字；只需列出 source@file:line 和 sink@file:line 条目，并注明输入形态和操作即可。对于单体仓库，按服务分别构建映射。

有关源类别和汇点类别的完整列表、特定框架模式（Express、Flask、FastAPI、Django、Rails、Spring、Gin、ASP.NET 等）、构建映射的启发式方法及示例，请参阅 references/source-sink-mapping.md。

第 5 阶段 — 系统化分析

大型代码库分区

当范围超过 50 个文件或 10,000 行代码时（满足任一阈值即可），请使用并行子 Agent，避免分析流于表面。这两个阈值有意采用“或”的关系。

• 在单体代码库中，优先按服务划分；在服务内部，优先按架构层边界划分（数据访问、业务逻辑、API 处理程序、身份验证中间件）。
• 每个子 Agent 都应收到威胁模型简报、安全意图简报、源/汇映射，以及适用于其分区的检查清单。
• 每个子 Agent 按照相同的检查清单，独立对其分区执行阶段 A（文件级分析）。
• 所有子 Agent 完成后，对合并后的文件集执行阶段 B（跨信任边界数据流分析），特别关注跨分区的数据流——遗漏的授权检查和受污染数据注入常常藏在这里。
• 对重叠发现的问题进行去重；合并为最高严重性，并列出所有位置。

如果没有可用的子 Agent，或者范围较小，请按顺序执行所有阶段。如果即使分区分析也无法覆盖每一行代码，请优先检查入口点、身份验证和授权代码、阶段 4 中识别出的汇、机密信息处理，以及安全意图简报“已抑制发现”部分中提及的任何代码。

阶段 A — 文件级分析

遍历范围内的每个文件。对每个文件：

• 完整阅读文件。
• 检查 references/checklists/ 中所有适用的检查清单。威胁模型简报中的“适用检查清单”条目会指出需要加载哪些清单：任何身份验证代码都检查身份验证/授权/会话，任何紧邻汇的代码都检查注入，任何调用加密 API 的代码都检查密码学，文件上传/下载端点都检查文件处理，错误/日志检查则适用于所有代码，依此类推。跳过不适用于该应用类型的检查清单（例如 CLI 工具无需检查 XSS/CSRF）。
• 针对分区中出现的每种语言，加载语言易错点参考资料（references/language-footguns/<lang>.md）。结合领域检查清单执行语言特定检查。
• 根据安全意图简报交叉核对候选发现。如果简报在确切位置明确提及确切模式，则跳过。若简报提供了一般性背景，但未确认具体实例，则将严重性降低一个级别，并注明意图来源。
• 记录每项发现，包括文件路径、行号、领域类别、CWE ID、OWASP 映射（Top 10 和/或 API Top 10）、初步严重性、弱点、影响和具体建议。标记涉及跨文件数据流的发现，以便在阶段 B 中跟进。

如果同一个逻辑问题因共用工具函数而出现在多个文件中，请避免重复记录。应在根本原因处记录一次，并列出所有受影响的位置。

Phase B — 跨信任边界数据流

完成文件级分析后，遍历 Phase 4 映射中的每一组源与汇：

• 对每个源，沿着数据流经过的验证器、清理器、编码器、ORM 层、框架抽象和中间函数，追踪到它可能到达的每个汇。若路径较长，请沿着调用图追踪，而不是凭猜测判断。
• 在每一步评估：数据是否经过类型／长度／格式／范围验证？是否针对最终汇进行清理（HTML 编码、SQL 参数化、shell 引号处理、路径规范化）？是否在正确的边界执行授权检查（通常应在任何状态更改之前，而非之后）？信任转换是显式的（例如，函数名为 sanitize、escape、parameterize），还是隐式的（依赖假设）？
• 特别注意二阶污点：从数据库读取的数据最初由用户控制（存储型 XSS、二阶 SQL 注入、存储内容导致的日志注入）。
• 特别注意信任洗白：检查的是源值，却使用了绕过检查的派生值（例如，先规范化再检查与先检查再规范化的差异、标头解析不一致）。
• 检查每个受保护操作是否都进行了授权，而不只是规范端点——相邻端点、批量端点、GraphQL 字段解析器和管理工具往往会漏掉同一项检查。
• 应用业务逻辑检查（references/checklists/business-logic.md）：状态机绕过、授权竞态、重复支出、金融操作的原子性不足。
• 检查纵深防御缺口：关键操作仅由一项检查保护，若该检查失效则没有第二层防护。

记录新发现；若文件级发现的影响在跨文件上下文中发生变化，则更新其严重性。

构建利用场景

对于每项暂定为高危或严重的发现，尝试构建具体的利用场景，并回答以下问题：起始位置（攻击者是谁）、操作（具体请求／输入／操作序列）、路径（从源到结果的文件：行号步骤）以及结果（访问的具体数据、执行的命令、获得的权限）。

如果能够构建场景，请将其列在“利用场景”下。如果弱点本身明确，但无法构建场景（纵深防御缺口、第二层缓解措施、信任边界不明确、审核者无法臆造的缺失前提条件），则保留评估所得的严重性，并使用“利用场景 — 未确认”结构。**不要仅因难以构建场景，就悄然下调或删除高危／严重发现。**对于中危和低危发现，利用场景为可选项。

完整的四问规则、按弱点类别划分的场景模板、“未确认”模板以及应避免的反模式，请参阅 references/exploit-scenarios.md。

去重

生成报告前：

• 将根本原因相同、但出现在多个位置的发现合并为一项，并列出所有受影响的位置。
• 删除 Phase B 中发现的误报（例如，某项输入在一个文件中看似未经验证，但后来发现有中间件进行了验证——请确认该中间件确实应用于相关路由）。
• 将源自 Security Intent Brief 中同一项已记录权衡的发现合并为一项，并引用相应的意图条目。
• 根据最坏情况下现实可行的影响 × 可利用性 × 暴露程度，协调相互冲突的严重性评估。评分矩阵、威胁模型修正因素及示例请参阅 references/severity-guide.md。

阶段 6 — 生成报告

按照 Format Gate 中所选格式对应的模板生成最终报告：HTML 输出使用 references/report-template-html.md，Markdown 输出使用 references/report-template.md。以下内容规则适用于两种格式；结构呈现方式由模板定义。

• 将报告日期设为当前日期。
• 填写摘要表：范围、应用类型和暴露情况（取自 Threat Model Brief）、审计的域、按严重程度统计的发现数量。
• 添加“威胁模型”和“已记录的安全态势”部分，总结阶段 2 和阶段 3 的输出。
• 添加“源/汇映射”附录，总结阶段 4 的枚举结果，让读者了解分析了哪些内容。
• 分配从 SEC-001 开始的连续 SEC-NNN 标识符。按严重程度排序（Critical 优先），然后按下方参考索引所列顺序排列域类别，同一严重程度和类别内按文件路径排序。
• 每项发现包含：标识符、简短标题、域类别、CWE ID、OWASP Top 10 / API Top 10 映射、位置（file:line）、严重程度（附影响/可利用性/暴露情况细分）、描述、影响、利用场景（或针对 High/Critical 的“未确认”说明）以及建议。使用 references/owasp-cwe-mapping.md 查询 CWE/OWASP 映射；选择最贴切的 CWE。
• 在项目根目录保存报告，遵循所选模板的文件名约定（HTML 使用 SECURITY-AUDIT-REPORT-YYYY-MM-DD.html，Markdown 使用 SECURITY-AUDIT-REPORT-YYYY-MM-DD.md）；如果文件已存在，则递增数字后缀。

所选格式为 HTML 时，还需：

• 严格遵循 references/report-template-html.md 中的结构约定：必需的 ID、类和 data-* 属性均不可省略。该脚手架使报告可解析，并支持重新审计时进行差异比较。
• 在能提供额外信息时使用 HTML 专属功能：对于多服务或多租户应用，在威胁模型部分加入内嵌 SVG 信任边界图；对于路径跨越多个文件的 High/Critical 注入类发现，加入 SVG 源到汇的数据流图；折叠显示 Security Intent Brief 主题；在相关发现之间添加锚点交叉引用（共享根因、串联利用所需前提）。如果文字已能清晰表达关系，则跳过这些功能。

保存后，向用户说明文件路径，并简要总结结果，包括 Critical 发现数量（如有）、评分所依据的应用类型和暴露情况，以及任何可利用性尚未确认的 High 发现。

参考索引

在相应阶段开始时加载这些参考资料。SKILL.md 正文有意不重复其中的内容。

工作流参考资料（进入相关阶段时加载）：

• references/threat-modeling.md — 阶段 2 简报模板和推断启发式。
• references/intent-discovery.md — 阶段 3 子 Agent 提示词和简报模板。
• references/source-sink-mapping.md — 阶段 4 枚举启发式。
• references/exploit-scenarios.md — 阶段 5 漏洞利用场景构建。
• references/severity-guide.md — 影响 × 可利用性 × 暴露程度评分。
• references/owasp-cwe-mapping.md — OWASP 和 CWE 标签速查。
• references/report-template.md — 用户选择 Markdown 时的阶段 6 报告格式。
• references/report-template-html.md — 用户选择 HTML（默认）时的阶段 6 报告格式。

领域检查清单（仅加载威胁模型简报标记为适用的检查清单）。按组排列，以便选择，并定义报告中规范的领域类别排序：

身份与访问：

• references/checklists/auth-and-session.md
• references/checklists/authorization.md
• references/checklists/secrets-and-keys.md

输入处理与注入：

• references/checklists/injection.md
• references/checklists/xss-csrf-frontend.md
• references/checklists/ssrf-redirect-url.md
• references/checklists/deserialization.md
• references/checklists/file-handling.md

跨领域问题：

• references/checklists/crypto.md
• references/checklists/error-and-logging.md
• references/checklists/business-logic.md
• references/checklists/api-security.md

基础设施与供应链：

• references/checklists/dependencies.md
• references/checklists/containers-iac.md
• references/checklists/cicd.md

语言易错点（针对范围内检测到的每种语言加载一份）：

• references/language-footguns/python.md
• references/language-footguns/javascript-typescript.md
• references/language-footguns/java-kotlin.md
• references/language-footguns/go.md
• references/language-footguns/ruby.md
• references/language-footguns/php.md
• references/language-footguns/csharp-dotnet.md
• references/language-footguns/rust.md
• references/language-footguns/c-cpp.md