incu-way-security-validation

安全性验证流程

通过门禁驱动的工作流，按照既定安全规则集（OWASP Top 10、OWASP ASVS、OWASP API Security Top 10、CWE Top 25）逐项检查代码——可以是整个模块、某项服务，也可以是当前分支上的更改——并将检查结果整理成一份可追溯的合规报告。输出文件位于 docs/security/validation/{slug}/VALIDATION.md。

这是一次标准／规则集审查，不同于 snyk-remediation：

• snyk-remediation 会运行自动化 SAST/SCA 扫描器，并修复它们标记的问题。
• 此流程是依据所选标准进行的人工逐项验证，能够发现扫描器会遗漏的设计和逻辑问题（访问控制失效、不安全的业务流程、缺失的授权检查、薄弱的加密方案），并将代码逐项对应到各项控制措施，给出通过／失败判定和证据。

要实现全面覆盖，请同时运行两者。此流程负责评估，默认不会修复问题；具体修复工作应作为后续的 incu-way-development / incu-way-bugs / snyk-remediation 事项。

两种调用模式：

• 独立运行（依据标准进行审计）： 使用独立分支 assess/secval-{slug} → PR 合并到 develop。
• 嵌入其他流程： 写入调用方当前分支／工作树；报告随该流程的 PR 一同提交。不创建单独的分支或 PR。例如：incu-way-development 在 Gate 3 验证新代码，并同时运行 Snyk/Sonar 扫描。

这是一个评估流程。与 incu-way-docs 一样，它不会维护 .ways/state.json。

---

仓库资格检查（优先执行）

在 Phase 0 之前，检查 ~/.ways/config.yaml 中的 blacklist（格式：incu-base 的 global-config 规则，该规则始终启用）是否匹配当前仓库。如果匹配，请告知用户此仓库已被 incu-way 列入黑名单，并询问是否仍要继续（一次性例外）或停止；在用户回答之前，不要运行任何阶段。文件不存在或没有匹配项：正常继续。

---

Phase 0 — 范围与规则集选择

目标： 在做出任何判断之前，确定验证对象及所依据的标准。只读。

信息收集

1. 确认目标：整个仓库、某个模块／服务，或当前分支的差异（新代码——git diff develop...HEAD）。
2. 根据目标和技术栈选择规则集：
   • OWASP Top 10 (2021)——通用 Web 应用基线（大多数代码的默认选项）。
   • OWASP API Security Top 10 (2023)——目标提供 API 时使用。
   • OWASP ASVS——需要正式验证等级（L1/L2/L3）时使用。
   • CWE Top 25——与语言无关的弱点基线。
3. 首先阅读现有安全背景资料（docs/security/、之前的 VALIDATION.md、威胁模型、CLAUDE.md 的安全章节），避免重复讨论已解决的问题，并与已有威胁模型保持一致（参见 incu-way-threat-model）。

调查目标

只做调查，暂不评判：入口点和路由、身份验证与会话处理、授权检查、输入处理与验证、输出编码、数据访问（查询、ORM 用法）、密钥与配置、加密用法、文件／网络／外部调用、错误处理与日志记录（以及是否会泄露敏感数据）、所涉及的依赖项。

Phase 0 退出条件

进入 Gate 1 前，Claude 应能够说明：

• 目标是什么，以及它是整个仓库、某个模块还是分支差异
• 适用的规则集，以及（对于 ASVS）适用的等级和原因
• 目标中相关的入口点、信任边界和敏感操作
• 使用了哪些现有安全文档／威胁模型
• 哪些方面尚不明确，将标记为待确认问题，而不是自行假设

不要根据名称或注释推断某项控制措施已通过。如果代码无法证明该控制措施已落实，则判定为失败或列为待确认问题，绝不能假定通过。

Gate 1 — 规则集和范围确认

提议目标和规则集：

## Proposed security validation

- **Target:** {repo | module X | current branch diff}
- **Ruleset(s):** {OWASP Top 10 2021 | OWASP API Top 10 2023 | OWASP ASVS L{1/2/3} | CWE Top 25}
- **Relevant surface:** {entry points / APIs / auth / data access in scope}
- **Out of scope:** {what this pass will not cover}
- **Relationship to scans:** {complements Snyk SAST/SCA — not a replacement}
- **Open questions:** {anything ambiguous}

• 询问：“以下是针对 {target} 的安全验证范围和规则集。请先确认，然后我再开始验证。”
• 停止。在用户确认范围和规则集之前，不要执行验证。

---

隔离设置（仅独立模式）

如果嵌入其他工作流中运行，请跳过此步骤——在现有分支／工作树中编写。

如果以独立模式运行，请在编写前询问用户希望如何隔离工作：

你希望我在当前检出中创建新分支，还是创建单独的 git worktree？

严格按照用户的回答执行。 询问后停止；在用户选择之前，不要创建分支或工作树。

如果当前检出存在未提交的更改，请停止并在切换分支或创建工作树之前询问用户。

选项 A — 在当前检出中创建分支

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c assess/secval-{slug}

选项 B — 单独的 worktree

仅在 .worktrees/ 下创建 worktree。不要向用户询问路径。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/assess-secval-{slug} -b assess/secval-{slug} origin/develop

{slug} 的格式为 {YYYY-MM-DD}-{kebab-target}（例如 2026-06-17-checkout-api）。所有输出都 会在选定的工作位置中写入并提交。

---

阶段 2 — 逐项验证控制措施

目标： 对照实际代码逐项检查所选规则集中的控制措施，并生成 VALIDATION.md。

验证规则（必须遵守）

• 每项控制措施都必须给出判定： Pass / Fail / N/A / Needs review。不得 默默跳过任何控制措施。
• 可追溯。 Pass 必须引用实现该控制措施的代码（path:line）；Fail 必须引用 存在漏洞的代码；N/A 必须说明该控制措施为何不适用。读者必须能够 核实每项判定。
• 不得臆断通过。 缺少证据不代表通过。如果无法确认某项控制措施，应标为 Needs review，而不是 Pass。
• 关注影响，而不只是标签。 每项 Fail 都必须说明攻击者可能实施的行为，并附上 CWE。
• 提出建议，不要修复。 每项 Fail 都要给出具体的修复建议；此工作流不会更改代码。

VALIDATION.md 结构

# Security Validation — {target}

## Scope
- Target: {repo | module | branch diff}
- Ruleset(s): {…}  (ASVS level: {L1/L2/L3} if applicable)
- Date: {YYYY-MM-DD}
- Branch validated: {branch}

## Summary
- Controls evaluated: {N}  (Pass: X, Fail: Y, N/A: Z, Needs review: W)
- Findings by severity: Critical X, High Y, Medium Z, Low W

## Control checklist — {ruleset name}
| Control | Verdict | Evidence | Notes |
|---------|---------|----------|-------|
| A01 Broken Access Control | Fail | `src/api/orders.ts:30` — no ownership check on GET /orders/:id | IDOR: any user reads any order |
| A02 Cryptographic Failures | Pass | `src/auth/hash.ts:8` — bcrypt cost 12 | |
| A03 Injection | Pass | parameterized queries throughout `src/db/` | |
| … | … | … | … |

## Findings (the fails, detailed)
| # | Control | Severity | CWE | Finding | Evidence | Impact | Remediation |
|---|---------|----------|-----|---------|----------|--------|-------------|
| 1 | A01 | High | CWE-639 | IDOR on order read | `src/api/orders.ts:30` | Any user reads any order | Enforce ownership/authz check before returning the record |
| 2 | … | … | … | … | … | … | … |

## Needs review
Controls that could not be confirmed and need a human/code answer.

## Out of scope
Controls or areas deliberately not covered, with reason.

如果一次验证涉及多个规则集，请为每个规则集重复控制措施清单表；发现项使用一张合并表格。

---

阶段 3 — 发现项和修复交接

• 将发现项按优先级排列（严重／高优先），整理成简短的修复清单，并为每项标注 对应的发现项编号。
• 明确分派修复工作——此工作流不会实施修复：
  • 依赖项漏洞／扫描器可检测的问题 → snyk-remediation
  • 现有行为中的逻辑／访问控制／设计修复 → incu-way-bugs
  • 属于正在开发的功能的修复 → 合并到该功能对应的 incu-way-development 项目中
• 为每项发现注明分派去向，确保交接清晰明确。

---

Gate 2 — 审核

验证文档编写完成后：

• 提供文档路径、汇总计数、按严重程度分类的失败项，以及Needs review清单。
• 说明：“安全验证报告已就绪，路径为 docs/security/validation/{slug}/VALIDATION.md。发现项已分派修复，待处理事项也已列出。请审核。”
• 停止。等待用户审核后再继续。

如果以嵌入模式运行，控制权将返回调用工作流，由其在自身的验证／审核关卡处理——报告将在那里审核，并随该工作流的 PR 一并提交。下方的独立模式 PR 步骤将跳过。

---

阶段 4 — PR（仅独立模式）

建议调用 incu-way-prepare-pr，推送 assess/secval-{slug} 并创建 PR。不要自行推送或运行 gh pr create。

供 incu-way-prepare-pr 使用的建议 PR 标题／正文：

Title: assess(security): validate {target} against {ruleset}

PR 正文必须包含：

• **范围：**目标、规则集，以及适用时的 ASVS 级别。
• **摘要：**通过／失败计数及按严重程度分类的发现项。
• **发现项和分派去向：**按优先级排列的失败项，以及各项修复的分派去向。
• **Needs review：**需要团队提供意见、尚未确认的控制措施。

PR 创建后，分享 PR URL。停止。在用户批准之前，不要合并。

快速参考 — 阶段门

阶段门	触发条件	说明内容	暂停，直至
1	提出规则集和范围	“这是针对 {target} 的安全验证范围和规则集。开始前请确认。”	用户确认
2	完成验证文档	“安全验证文档已准备就绪，位于 docs/security/validation/{slug}/VALIDATION.md。请审阅。”	用户审阅
3	（独立模式）已审阅	建议使用 incu-way-prepare-pr，为 PR assess/secval-{slug} → develop 创建 PR；用户运行后分享 URL	用户批准 PR

---

产出内容

docs/security/validation/{slug}/
  VALIDATION.md   # per-ruleset control checklist + detailed findings + remediation routing

---

注意事项

• 阶段门 1 确认范围和规则集之前，不要生成验证文档。
• 没有证据时，不要将控制项标记为 Pass——未经确认的状态应为 Needs review，绝不能是 Pass。
• 不要给出无法追溯的判定——每项都要引用代码，或说明为何不适用。
• 不要将此流程视为 Snyk SAST/SCA 扫描的替代品——它是对其的补充。
• 不要在此处实施修复——只进行验证、分配修复工作，并让目标流程 完成变更。
• 嵌入其他流程时，不要单独创建 PR——报告会随调用方的 PR 一同提交。
• 独立模式下，不要直接写入 develop 或 main——请使用 assess/secval-{slug}。