experience-lwc-security-validate

审查 LWS 安全性

对 Lightning Web Component 执行结构化的 Lightning Web Security（LWS）和产品安全合规检查。提供两种输出模式：

• 审查模式（默认）——按严重性排列的发现 + 已应用的代码修复。
• 评分模式——生成以 LWS 规则目录（lws-001…lws-023b）为键的 SARIF 2.1.0 JSON 报告，用于下游门控、评估评分或 CI 导入。

两种模式使用参考资料中的同一套检测规则；区别仅在于输出格式。

适用场景

• 用户要求对特定 LWC 进行“安全审查”“LWS 检查”“发布前安全审计”或“合规检查” → 使用审查模式。
• 用户要求为组件安全性“评分”，或希望获得机器可读的发现，以便输入门控或评估 → 使用评分模式。
• 为组件发布做准备，需要统一的安全报告。
• 实施修复后，验证安全态势没有退化。

不要将此技能用于：

• 构建新组件（使用 experience-lwc-generate）。
• 无障碍（单独应用 WCAG 2.2）或 RTL 审查——不在范围内。
• 在功能标志后为修复设置门控（修复合入后再应用功能标志门控）。
• 非 LWC 安全审查（Apex、Aura、服务器端）——不在范围内。

前提条件

• 组件路径（modules/… 下的 LWC 包）。
• 可访问组件的 JS/TS、HTML 模板、CSS 和 .js-meta.xml。
• 输出模式：review（默认——查找、修复并报告）或 score（查找并生成 SARIF JSON，不要修改代码）。如果用户的请求没有明确指出模式，请在开始前与用户确认。

知识库

每份参考资料都是事实依据。不要凭记忆总结——打开参考资料，应用其中的指南，并在报告中引用所用的具体章节。

• Lightning Web Security（LWS）目录：LWS Security Expert——列出受阻 API 及其允许的替代方案。
• 规则目录（lws-001…lws-023b）：Product Security Framework——每条规则都列出了检测模式，以及规范的 SARIF ruleId / level / message 模板。评分模式会使用这些确切值，为每个匹配项生成一条 SARIF 结果。

工作流

第 1 步——确定审查范围

收集组件路径并确定要审查的文件。包含组件包中的每个文件：.html、.js/.ts、.css、.js-meta.xml，以及由同一团队维护、且由目标组件调用的任何子组件。

记录现有的功能标志门控——需要修改代码的发现必须遵守这些门控。

第 2 步——阅读知识库

在作出判断前，从头到尾阅读 LWS Security Expert 和 Product Security Framework。LWS 参考资料列出了受阻的 DOM API 及其允许的替代方案；Product Security 框架提供了严重性分类、包含 23 条规则的 SARIF 目录和修复模式。

步骤 3 — 遍历规则目录

针对组件包运行 Product Security Framework 中的每条规则（lws-001 至 lws-023b）。对于每条规则：

1. 严格套用 “How to Find the Issue” 中的模式。不要走捷径——每条规则都列出了必须考虑的混淆模式（方括号表示法、Unicode 转义、Reflect.*、字符串拼接）。
2. 对每个匹配项记录：ruleId、level（目录中的 error / warning）、file、startLine、startColumn（未知时填 1）、message（使用目录中的 message 模板，并替换代码中的实际 {placeholder}）。
3. 如果某条规则有前置条件“仅分析从 'lwc' 导入的文件”（lws-008），则通过 scripts/check-lwc-import.sh <file> 检查——存在 from 'lwc' 导入时，脚本会输出 lwc-import=yes，否则输出 lwc-import=no。如果结果为 no，则跳过该文件的此规则。

此目录是权威检测清单；后续 JS/TS、HTML 和 .js-meta.xml 条目是 SARIF 规则之外的附加检查。

步骤 4 — HTML 模板检查（附加）

检查每个模板中的以下内容：

• 使用 lwc:inner-html 的情况——验证来源是否可信。
• 未转义的表达式是否传入了 LWS 视为敏感的属性（href、src、srcdoc、内联事件处理程序）。
• 带绑定表达式的直接 style="…"——可考虑改用 CSS 类。
• 未设置沙箱的嵌入式 <iframe> 或 <object>（步骤 3 会通过 lws-023a/lws-023b 检查 srcdoc 和协议相关情况；此步骤检查是否缺少 sandbox 属性）。

步骤 4-5 中发现的问题使用规则 ID lws-tpl-001…lws-tpl-NNN（HTML）和 lws-meta-001…lws-meta-NNN（元数据）——在报告中按发现的问题依次编号，以免与 SARIF 目录中的规则冲突。

步骤 5 — 元数据与配置检查（附加）

检查 .js-meta.xml 中的以下内容：

• 过于宽泛的 API 访问权限（lightning__FlowScreen、lightning__AppPage 等），而组件并不需要这些权限。
• 暴露的包含敏感数据的公共属性。
• 缺少针对目标界面的 capabilities 限制。

检查 Apex 绑定中的以下内容：

• 使用 @wire 调用 Apex 方法，但未设置 @AuraEnabled(cacheable=true)，而此处适合缓存。
• 绕过权限检查的直接命令式调用。

步骤 4-5 中发现的问题使用规则 ID lws-tpl-001…lws-tpl-NNN（HTML）和 lws-meta-001…lws-meta-NNN（元数据）——在报告中按发现的问题依次编号，以免与 SARIF 目录中的规则冲突。

步骤 6 — 生成报告

根据先决条件中确认的模式选择输出格式。

审查模式（默认）

使用 examples/review-report.md 作为模板——在 ## Security (LWS + Product) 下，每个发现的问题对应一个项目符号；在 ## Summary 下提供一行总计。

严重程度排序：Critical → High → Medium → Low（将 SARIF error 映射为 High，warning 映射为 Medium，除非规则另有说明）。注明每个问题对应的参考章节（例如，“Product Security § lws-001 document.createProcessingInstruction”）。

评分模式

仅输出一份 SARIF 2.1.0 JSON 文档，不得包含其他内容。前后不得添加文字。不要将 JSON 写入文件；直接内联返回。results 数组为空表示未发现问题。

使用 examples/score-report.sarif.json 作为结构参考——保持相同的顶层结构（$schema、version、runs[0].tool.driver.rules[]、runs[0].results[]），并填入实际触发的规则和匹配项。

规则：

• ruleId 必须与目录中的条目完全一致（lws-001…lws-023b，或步骤 4-5 中的 lws-tpl-* / lws-meta-* 命名空间）。
• 对于目录中标记为 level: error 的规则，level 为 error；对于标记为 level: warning 的规则，level 为 warning。不得使用其他值。
• message.text 使用目录中的 message 模板，并替换占位符（例如，将 {eventName} 替换为代码中找到的实际事件名称）。
• 每个匹配项对应一个 result。如果某条规则在一个文件中触发三次，则输出三个结果。
• tool.driver.rules 中仅包含已触发的规则；即使 results 数组为空，也必须包含 tool.driver.rules（使用 []）。

步骤 7 — 应用修复（仅限审查模式）

评分模式下跳过——评分模式为只读。

对于每个已接受的问题：

1. 编辑组件文件（HTML、JS/TS、CSS、meta.xml）以应用修复。
2. 保留现有的正确行为和功能标志门控。如果针对同一问题已配置门控，请保持不变。为分阶段推出而新增的功能标志门控不在此技能范围内——请另行应用。
3. 不要悄悄删除旧代码——需要门控时，请保留原有路径。
4. 不要为了让测试通过而降低安全性；如果测试依赖不安全模式，请修复测试。

步骤 8 — 验证

• 审查模式：针对更新后的文件重新运行步骤 3 的目录扫描；所有已修复的问题都不得再出现。运行 Jest 测试和所有组件级安全测试。如果修复涉及 Apex 访问模式，请与服务端审查人员确认权限。
• 评分模式：返回前，将生成的 SARIF 写入临时文件，并运行 scripts/validate-sarif.sh <path>——该脚本会确认 JSON 可解析、version 为 2.1.0、每个 ruleId 都符合目录模式（lws-NNN[a-z]? / lws-tpl-NNN / lws-meta-NNN）且已在 tool.driver.rules 中声明、每个 level 都是 error 或 warning，并且每个结果都包含 physicalLocation.artifactLocation.uri 和 region.startLine。返回 SARIF 前，请修复所有失败项。

交叉引用

• 相关技能：
  • experience-lwc-generate — 用于编写从一开始就符合安全要求的新 LWC 包。
  • design-systems-slds-validate — SLDS/设计系统合规性检查（可访问性与 WCAG 2.2 有交集——请单独运行）。
  • dx-code-analyzer-run — 全仓库静态分析检查；与此技能配合使用，可覆盖 LWS 目录之外的内容。

验证

• 已针对该包评估所有目录规则（lws-001…lws-023b），而非仅检查人工挑选的子集。
• 每个问题都已应用修复（审查模式）或在 SARIF 结果中列出（评分模式），或者附有说明原因的明确延期备注。
• 每个问题都引用了具体的目录规则 ID——不得使用自由形式的“看起来可疑”条目。
• 修复没有引入新的 XSS 注入点、不安全的 URL 流程或受限的 DOM API。
• 评分模式的输出是有效的 SARIF 2.1.0 JSON，直接内联返回，且不带任何外围说明文字。