prd-securability-enhancement

PRD 可安全性增强（FIASSE/SSEM + ASVS）

增强 PRD 内容，确保每项功能都有明确、可测试的可安全性要求，并与 OWASP ASVS 保持一致，同时以 FIASSE v1.0.4 / SSEM 为指导。目标是在实施之前改进需求文档，让交付团队从设计之初就构建可安全的功能，而不是事后再补充控制措施。

此技能以需求为中心，不审查或编写代码。如果用户想进行代码审查，请引导其使用 securability-engineering-review。如果用户想生成代码，请引导其使用 securability-engineering。

何时调用

用户提出以下需求时，触发此技能：

• 增强或强化 PRD、规格说明、用户故事集或产品简介中的安全要求
• 为产品或功能选择 ASVS 保证级别（Level 1、2 或 3）
• 将功能映射到 ASVS 控制措施，或检查需求文档的 ASVS 覆盖情况
• 在开发开始前找出缺失的安全要求
• 为功能标注 SSEM 属性或 FIASSE 原则
• 为现有功能需求添加可测试的安全验收标准

相近表达：“对这份规格说明进行安全审查”“这份功能列表在安全方面缺少什么”“为我的 PRD 添加安全 NFR”“让这些需求具备可安全性”。

输入

开始前，向用户询问缺少的信息：

• PRD、规格说明或功能列表（Markdown、散文、工单导出等）
• 系统背景：用户类型、部署模式、数据敏感度、集成接口
• 合规或风险背景（如 HIPAA、PCI、SOC 2、受监管行业）
• 是否对 ASVS 级别有偏好，或希望此技能推荐级别

如果文档很长，请直接解析其中的功能；不要要求用户预先提取。

流程

步骤 1 — 解析功能

将每项功能提取为规范化记录。逐项记录：

• 功能 ID 和标题（如果缺少，则分配类似 F-01 的 ID）
• 参与者（用户角色、系统、外部服务）
• 涉及的数据及其敏感度类别
• 跨越的信任边界（浏览器↔服务器、服务↔服务、服务器↔存储、内部↔外部）
• 现有验收标准（逐字记录，即使不够完善）

如果源 PRD 将多项能力放在同一条目中，请拆分，以便单独测试每项功能。

步骤 2 — 首先选择 ASVS 级别

先选择级别，再映射要求，可避免范围不足或范围过度。使用以下标准：

级别	适用情形
1	内部工具、原型、低敏感度数据、没有监管压力，且遭到入侵时影响范围有限
2	典型的生产 Web/API 系统，具有经过身份验证的用户、业务关键行为、客户数据或中等监管风险敞口（大多数产品属于此级别）
3	高保证场景：支付、健康记录、政府、身份提供商，以及任何遭到入侵会造成严重实质影响或攻击者资源充足的场景

除非有证据支持选择更低或更高级别，否则默认采用 Level 2。记录：

• 所选级别
• 为什么较低级别不够（当级别 > 1 时）
• 任何应高于基准级别的特定功能（例如，Level-2 产品中的支付端点按 Level-3 处理）

步骤 3 — 将每项功能映射到 ASVS

对于每项功能，使用 data/asvs/README.md（章节索引）和 data/asvs/V*.md 中的 when_to_use frontmatter，确定适用章节。常见映射：

• 身份验证流程 → V2（身份验证）、V3（会话管理）
• 授权、所有权、多租户范围限定 → V4（访问控制）
• 文件上传/下载 → V5（文件处理）
• 加密、密码存储、令牌 → V6（密码学）
• 日志记录、错误处理、可观测性 → V7（错误/日志记录）
• PII、静态/传输中的数据 → V8（数据保护）、V14（安全通信）
• 公共 API → V9（API/Web 服务）
• 配置、机密、部署 → V10（配置）
• 工作流规则、反自动化 → V11（业务逻辑）
• 任何用户/外部输入 → V12（输入验证）
• 任何呈现给客户端或返回给客户端的内容 → V13（输出编码）
• 敏感数据生命周期 → V16（敏感数据）

根据所选 ASVS 级别筛选要求。对每项要求，将覆盖情况分类为：

• 已覆盖 — PRD 已满足其意图
• 部分覆盖 — 部分满足；需明确或强化验收标准
• 缺失 — 缺少该要求，必须补充
• 不适用 — 用一句话说明理由

使用下方的 ASVS 覆盖差距模式表，找出 PRD 经常遗漏的差距。

步骤 4 — 为每项功能添加可安全性说明

为每项功能写一段简短说明，仅指出会实质影响实现的 SSEM 和 FIASSE 要点。不要枚举全部十项 SSEM 属性或全部十条 FIASSE 原则——那样会造成冗余信息。

可参考的角度（仅在相关时提及）：

• 信任边界处理和输入规范化（FIASSE v1.0.4 S4.3、S4.4.1）
• 派生完整性 — 对于由服务器掌控的状态，绝不信任客户端提供的值（FIASSE v1.0.4 S4.4.1.2）
• 请求面最小化 — 仅处理预期的指定值（FIASSE v1.0.4 S4.4.1.1）
• 可观测性：必须记录或审计的内容（FIASSE v1.0.4 S3.2.1.4 + 问责；透明性 S2.5）
• 最小意外原则 — 在信任边界和错误路径上保持行为可预测（FIASSE v1.0.4 S2.6）
• 弹性或可用性驱动因素（速率限制、超时、优雅且安全的故障处理）
• 可测试性或可修改性要求（例如，将加密/身份验证集中到专用模块中）
• 依赖项维护 — 与第三方代码保持持续的维护关系（FIASSE v1.0.4 S4.6）

步骤 5 — 转换为可测试的验收标准

对于每项新增或强化的要求，至少编写一条验收标准，满足以下条件：

• 行为可观察（测试或审计可以确认通过/失败）
• 明确边界条件（故障模式、未经授权的参与者、格式错误的输入）
• 与可验证的产物关联（日志行、响应代码、被拒绝的操作）

此处不接受含糊的“安全”或“健壮”表述。

步骤 6 — 输出增强版 PRD 产物

按顺序生成以下各节，并使用下方的精确模板。

ASVS 覆盖差距模式表

以下是 PRD 经常遗漏的差距。当看到左侧的触发措辞时，添加右侧列出的要求——它们几乎总是缺失于源产物中。

PRD 触发措辞（功能的描述）	几乎总是遗漏的要求	ASVS 章节	标签
“用户使用电子邮件和密码登录”	账户枚举防护一致性（有效与无效电子邮件的响应和时序相同）；根据泄露密码列表筛查密码；身份验证事件审计日志；按账户限制暴力破解频率	V6.3.8, V2.1, V2.4, V16.3	“身份验证界面缺口”
“用户重置／忘记密码”	请求端点的账户枚举防护一致性；令牌仅可使用一次；有效期较短（≤15 分钟）；静态存储令牌哈希；按电子邮件和 IP 限制频率；记录令牌签发／兑换的审计日志	V6.3.8, V6.2, V2.4, V16.3	“重置流程缺口”
“用户上传文件”	类型允许列表（而非拒绝列表）；嗅探内容，而非只依赖声明的类型；大小上限；防病毒／安全存储路径；文件名规范化；存储位置在 Web 根目录之外；URL 不可被猜测	V5.1, V5.2, V12.1	“上传缺口”
“用户可以编辑个人资料”／“更新设置”	可变字段允许列表（请求正文中不得包含 email／role／is_admin）；检查资源所有权；记录变更的审计日志；捕获变更前后的值	V4.1, V4.2, V16.2, V16.3	“批量赋值缺口”
“管理员可以执行 X”／“基于角色的访问控制”	记录授权决策（授予／拒绝）的日志；集中式授权模块（而非分散的检查）；在边界处默认拒绝；每次获取记录时都按所有权进行范围限制	V4.1, V4.2, V16.2, V16.3	“授权缺口”
“公共 API 端点”／“第三方集成”	按密钥／客户端限制频率；每次调用都进行身份验证（而非仅首次调用）；传递请求 ID；响应字段允许列表（不得泄露内部字段）；契约验证	V2.4, V9.1, V13.1, V16.2	“API 缺口”
“向用户发送电子邮件／短信”	使用模板化内容，避免用户控制的主题／正文注入；按收件人和操作者限制频率；处理退信／滥用循环；提供退订选项并记录审计日志	V2.4, V12.1, V13.1, V16.3	“外发消息缺口”
“使用用户提供的参数搜索／筛选／列出”	参数允许列表；限制排序／分页范围；查询超时；结果数量上限；在服务器端强制按租户／所有者限制范围	V4.1, V12.1, V13.1	“查询界面缺口”
“Webhook 接收器”／“回调 URL”	验证来源（签名、mTLS、IP 允许列表）；防止重放（时间戳 + 随机数）；幂等键；限制频率；记录接收事件的审计日志	V2.4, V2.5, V9.1, V16.3	“Webhook 缺口”
“保存用户文件／文档／笔记”	所有者标识符绝不由客户端提供；限制大小和内容；读取或写入时清理富文本／HTML；记录写入的审计日志	V4.1, V5.1, V12.1, V16.3	“服务器拥有的状态缺口（派生完整性）”
“导出数据”／“下载报告”	导出时重新检查授权（不能只在 UI 路由检查）；限制频率；审计日志中包含行数；适用时执行 PII 清理策略	V4.1, V7.1.1, V8.1	“导出缺口”
“后台任务处理用户提交的数据”	遵循与同步路径相同的边界原则（验证、缩减界面、按所有者限制范围）；任务级审计日志；毒性消息处理和死信队列（DLQ）	V11.1, V12.1, V7.1.1	“异步路径边界缺口”
“配置／功能标志／管理员设置”	变更必须由经过身份验证的操作者发起，并留下审计记录；没有管理员角色时，不得通过产品 API 设置；绝不回显机密值；默认值安全	V7.1.1, V10.1, V14.2	“配置界面缺口”
任何地方提及“PII／PHI／金融数据”	字段级分类；静态和传输中的数据均加密；保留／处置策略；访问日志要求；导出／擦除（被遗忘权）流程	V8.1, V14.1	“敏感数据生命周期缺口”
“实时”／“websocket”／“流式传输”功能	每个连接都进行身份验证（而非仅验证第一条消息）；限制每个连接的资源用量；背压／队列上限；空闲超时；记录连接生命周期审计日志	V3.1, V9.1, V11.1.4	“流式传输缺口”
“基于 AI／LLM 的功能”	在信任边界处理提示注入；在产生下游副作用前验证输出；按操作者限制频率和成本；记录提示词和工具调用的审计日志；PII 脱敏策略	V11.1, V12.1, V8.1	“LLM 边界缺口”
当某项功能触发以下模式之一时，除非 PRD 明确涵盖了相应要求（大多数情况下并未涵盖），否则应在覆盖矩阵中将这些要求预填为缺失。

输出模板

A. ASVS 级别决策

## ASVS Level Decision

**Chosen Level**: [1 | 2 | 3]

**Rationale**: [2–4 sentences. Cover data sensitivity, user population, regulatory context, and material-impact reasoning. Note why lower levels are insufficient if Level > 1.]

**Feature-Level Escalations**: [List any features that need a higher level than baseline, with one-line justification, or "None".]

B. 覆盖矩阵

## Feature ↔ ASVS Coverage Matrix

| Feature | ASVS Section | Requirement ID | Level | Coverage | PRD Change Needed |
|---------|--------------|----------------|-------|----------|-------------------|
| F-01    | V2.2         | 2.2.1          | 2     | Missing  | Add MFA requirement for high-risk actions |
| F-01    | V7.1         | 7.1.1          | 2     | Partial  | Specify which auth events are logged |
| F-02    | V12.1        | 12.1.1         | 2     | Covered  | — |

此处应优先追求完整，而非简洁——每项功能 × 每项适用要求都要有一行。适用差距模式表时，应纳入该模式所揭示的具名要求。

C. 增强后的功能规格

对每项功能，严格按以下格式输出：

### Feature F-01: [Title]

**Actor**: [user role / system]
**Data**: [data classes touched]
**Trust Boundaries**: [boundaries crossed]

**ASVS Mapping**: V2.2.1, V7.1.1, ...

**Updated Requirements**:
- [Original requirement, kept or rewritten]
- [Newly added requirement from ASVS mapping]
- [Newly added requirement from ASVS mapping]

**Acceptance Criteria**:
- [Testable criterion tied to a requirement above]
- [Testable criterion tied to a requirement above]

**Securability Notes**: [Short paragraph — only material SSEM/FIASSE points for this feature. Do not enumerate all attributes.]

D. 横向安全性要求

适用于多项功能的控制（集中式日志记录、机密管理、依赖项策略、基准 TLS、错误处理标准）。每项列出一条，并附上 ASVS 参考。

E. 未解决的差距与假设

输入中任何无法确定的内容：缺失的系统上下文、不明确的数据敏感性、未说明的用户群体、延后的决策。请明确列出，以便团队在实施前解决。

示例（简版）

输入功能（来自 PRD）：

F-03：用户可以点击“忘记密码”并输入电子邮件地址来重置密码。系统会发送一封包含重置链接的邮件。

这会触发差距表中的“重置流程差距”模式，因此缺失的要求是可以预见的。

增强后的输出：

### Feature F-03: Password Reset via Email

**Actor**: Unauthenticated user (claiming an account)
**Data**: Email address (PII), password (credential), reset token
**Trust Boundaries**: browser → public API; API → email provider; API → credential store

**ASVS Mapping**: V2.2.2, V6.2.1, V6.2.2, V7.1.1, V11.1.4, V12.1.1

**Updated Requirements**:
- User can request a password reset by entering an account email at `/reset`.
- The system always returns the same success response whether or not the email matches an account (prevents account enumeration, V2.2.2).
- Reset tokens are single-use, expire within 15 minutes, and are stored only as a salted hash (V6.2).
- New passwords are validated against a minimum policy and screened against a known-breached-password list (V6.2.1).
- All reset requests, token issuances, token redemptions, and password changes are logged with user ID, source IP, user agent, and outcome (V7.1.1).
- Reset requests are rate-limited per email and per source IP (V11.1.4).
- The email input is canonicalized and validated against a strict format (V12.1.1).

**Acceptance Criteria**:
- Submitting a non-existent email returns the same response body, status code, and timing characteristics as a valid email (within tolerance).
- A reset token cannot be redeemed after 15 minutes or after first successful use; both cases produce a generic failure response and a logged `reset_token_invalid` event.
- More than 5 reset requests for the same email within 10 minutes are rejected with HTTP 429 and logged.
- Audit log lines for reset events are queryable by user ID and contain the fields above.

**Securability Notes**: This feature crosses an unauthenticated trust boundary (FIASSE v1.0.4 S4.3), so input handling and rate limiting are the load-bearing concerns. The reset token is server-owned state; never accept client-supplied token attributes beyond the opaque token itself (Derived Integrity, FIASSE v1.0.4 S4.4.1.2). Centralize token generation, hashing, and verification in a single module so the policy can evolve without touching call sites (Modifiability). All reset events must be observable in the audit pipeline so abuse patterns can be detected (Accountability + Observability, FIASSE v1.0.4 S3.2.1.4; Transparency S2.5).

输出应达到此处的具体程度——明确、可测试，并可追溯至 ASVS。

质量检查清单（输出前执行）

覆盖情况

• 每项功能都有 ID、参与者、数据分类和信任边界列表
• 在逐项功能映射前，先选择并说明 ASVS 级别
• 在所选级别下，将每项功能映射到所有适用的 ASVS 章节
• 将上方表格中的差距模式应用于每项相关功能
• 每项缺失/部分满足的条目都已转化为具体的 PRD 修改

输出规范

• 包含覆盖矩阵，并包含需修改列
• 每项功能均严格遵循规定的输出格式（参与者 / 数据 / 信任边界 / ASVS 映射 / 更新后的要求 / 验收标准 / 安全性说明）
• 验收标准可通过行为测试验证，而非仅表达愿景
• 安全性说明应切中要点——只包含重要的 SSEM/FIASSE 要点，不要穷举

可追溯性

• 每项新增要求都注明 ASVS 参考
• 横向要求部分涵盖共享控制
• 明确列出未解决的差距与假设

如有疑问

• 宁可补充缺失要求，也不要假设已经涵盖；请明确标注，让审核者一目了然。
• 每项功能应优先采用更少、更精准的 ASVS 参考，而非列出无人会跟进的长清单。
• 安全性说明应使用通俗语言——阅读对象是产品经理，而不仅仅是安全工程师。

参考资料

• 分步操作手册：plays/prd-fiasse-asvs-enhancement.md
• ASVS 章节索引：data/asvs/README.md
• ASVS 要求（按章节）：data/asvs/V*.md
• FIASSE v1.0.4 基本原则：data/fiasse/S2.1.md–S2.6.md（透明性 S2.5，最少惊扰原则 S2.6）
• FIASSE v1.0.4 SSEM 属性总类：data/fiasse/S3.2.1.md–S3.2.3.md；叶节点文件（例如 S3.2.1.4.md 可观测性）提供针对特定属性的指导
• FIASSE v1.0.4 边界控制与弹性编码：data/fiasse/S4.3.md、S4.4.md，以及规范输入处理叶节点 S4.4.1.md、S4.4.1.1.md、S4.4.1.2.md
• FIASSE v1.0.4 依赖项管理与责任维护：data/fiasse/S4.5.md、S4.6.md