| name | deep-scan |
| description | 对指定代码路径执行三层深度扫描：high-impact-bug-audit（高影响缺陷审计） → logic-analyzer（逻辑影响分析）→ security-review（安全审查）。 用于在代码审查、合入前检查、安全审计等场景下，对 C++/JS/TS 代码进行系统性风险排查。 触发方式： 1. 用户输入 /deep-scan {path} 2. 用户用自然语言表达“对某某路径做深度扫描/全面排查/安全审计/bug audit”等意图，
例如：“对 services/abilitymgr 做深度扫描”、“全面排查 frameworks/native 的高危 bug”、
“审计 interfaces/inner_api 的安全问题”。
输出：按 P0/P1/P2 优先级排序的 Excel 问题汇总表（规范输出）。 扫描范围默认排除 ets 和 cj 前缀的源文件；用户若通过自然语言明确要求包含，再另行确认。
|
Deep Scan — 三层深度扫描工作流
概述
本 skill 将三个专业扫描能力串联为固定工作流，对目标路径进行分层、递进式风险排查：
- Layer 1: high-impact-bug-audit — 聚焦崩溃、挂死、OOM、数据损坏、资源泄漏、状态污染等高影响缺陷
- Layer 2: logic-analyzer — 分析代码修改/逻辑分支的深层影响，发现隐藏的逻辑不一致、边界遗漏、副作用
- Layer 3: security-review — 进行商用级安全审计，识别注入、权限绕过、敏感数据泄漏、反序列化等安全漏洞
触发条件
- 用户输入
/deep-scan {path}（仅接受路径参数，不支持 options）
- 用户自然语言表达扫描意图，例如：
- “对 services/abilitymgr 做深度扫描”
- “全面排查 frameworks/native 的高危 bug”
- “审计 interfaces/inner_api 的安全问题”
- “扫描 test/unittest 的逻辑缺陷”
参数
| 参数 | 说明 | 默认值 |
|---|
path | 目标扫描路径（相对或绝对） | 必填 |
注意：通过 /deep-scan 斜杠命令触发时，仅解析 {path} 一个参数，不识别 --layer、--format、--output、--focus 等 options。用户若通过自然语言提出额外要求（如“只扫描 bug”或“输出 Markdown”），按自然语言理解执行。
扫描范围
- 默认排除：文件名以
ets 或 cj 开头的源文件（如 ets_runtime.cpp、cj_runtime.cpp、ets_*.h、cj_*.h）
- 包含：
.cpp、.cc、.h、.hpp、.js、.ts 等源文件
- 若用户通过自然语言明确要求包含 ets/cj 文件（如“把 ets_runtime 也扫进去”），需先向用户确认后再扩大范围
工作流步骤
Step 1: 路径确认与范围界定
- 确认
path 存在且为目录或文件
- 列出该路径下的主要源文件类型（
.cpp, .h, .hpp, .js, .ts 等），并排除 ets/cj 前缀文件
- 若路径过大（超过50个文件），询问用户是否聚焦子目录或按模块拆分
- 根据文件类型和路径特征，确定 Layer 1 的扫描重点（如 IPC 密集路径侧重 Parcel/反序列化）
Step 2: Layer 1 — High-Impact Bug Audit
加载并执行 high-impact-bug-audit skill 的扫描逻辑：
- 构建模块风险画像：总结目标路径的主要能力、外部输入点（API/IPC/文件/配置）、资源所有权、并发行为、可能的 P0/P1 结果
- 核心扫描：空指针/无效迭代器、越界访问、UAF/生命周期、死锁/挂死、OOM/未捕获异常、反序列化失败、整数溢出、资源泄漏、半初始化状态、忽略返回值
- 能力路由：根据路径实际能力选择针对性检查清单（文件解析、Parcel/JSON、mmap/fd/socket、全局缓存/异步、权限验证等）
- 确认触发路径：对每个 P0/P1 候选，证明或证伪 UI/API/IPC/配置/文件/网络等外部输入能否触达
- 证据分级：Confirmed / Likely / Suspicious / Excluded
- 输出：按
Priority = impact severity * triggerability * blast radius 排序的 Layer 1 发现列表
Step 3: Layer 2 — Logic Analyzer
加载并执行 logic-analyzer skill 的扫描逻辑：
- 变更影响分析：识别目标路径中的条件分支、状态转换、资源申请/释放配对、锁的获取/释放配对
- 边界与一致性检查：枚举所有分支路径，检查是否存在：
- 某条路径遗漏资源释放（与 Layer 1 资源泄漏发现交叉验证）
- 状态机转换存在非法或遗漏的边
- 前置条件检查与后续使用不一致
- 错误处理路径中未回滚已完成的副作用
- 并发逻辑：检查锁粒度、锁顺序、条件变量使用、原子操作与内存序
- 跨函数/跨模块影响：追踪关键数据流，识别一处修改对远端代码的隐藏影响
- 输出：Layer 2 逻辑问题列表，标注与 Layer 1 发现的关联
Step 4: Layer 3 — Security Review
加载并执行 security-review skill 的扫描逻辑：
- 攻击面识别：列出所有外部输入点（IPC 接口、文件解析、网络数据、配置读取、环境变量、用户输入）
- 漏洞模式扫描：
- 注入类：命令注入、SQL 注入（如有）、路径遍历、格式字符串
- 内存安全：缓冲区溢出、UAF、堆溢出、栈溢出（与 Layer 1 交叉验证）
- 权限与访问控制：权限检查绕过、TOCTOU、敏感操作未鉴权、能力泄漏
- 数据安全：敏感数据硬编码、日志泄漏、未加密传输/存储
- 反序列化：Parcel/JSON/二进制解析中的类型混淆、恶意构造数据
- 并发安全：竞态条件导致的安全状态破坏
- 合规与加固：检查是否符合最小权限原则、安全默认值、失败安全（fail-safe）
- 输出：Layer 3 安全问题列表，按严重等级（Critical / High / Medium / Low）排序
Layer 3 对小型/极简模块的聚焦原则
本小节是对 security-review skill 执行方式的补充约束，不修改 skill 本身内容。
当目标路径为小型/极简模块（如仅包含单个 NAPI 注册文件、简单 JS 类封装、无 IPC/无文件解析/无外部输入），Layer 3 应按以下原则收敛扫描范围，避免过度展开和重复分析：
-
聚焦真实攻击面，而非理论风险
- 只分析目标模块自身代码中实际存在的外部输入点（函数参数、返回值、动态加载调用等）。
- 不主动推演父类/依赖模块的权限继承、生命周期行为或构建加载顺序等跨模块假设性问题，除非目标模块代码中直接涉及相关逻辑。
-
避免与 Layer 1/2 重复分析
- 若同一问题已在 Layer 1 或 Layer 2 中发现（如
int *bufLen 截断、requireNapi 失败路径），Layer 3 应直接将其映射为对应安全等级，补充安全视角（如“整数截断导致潜在越界读取”），而非重新从头展开分析。
-
控制检查清单规模
- 对无 IPC、无文件解析、无网络、无反序列化、无敏感数据的模块，不强制套用完整漏洞模式清单。
- 重点检查：内存安全（与 Layer 1 交叉验证）、数据暴露/信息泄露、动态加载/外部依赖、以及实际存在的输入边界问题。
-
跨模块系统性问题仅记录一次
- 若发现的问题属于同一路径下多个模块共有的模式（如多个 NAPI 模块使用相同
int *bufLen 签名），在 Layer 3 中只记录一次，并在问题描述中注明“该模式同样存在于同路径下其他模块”，不逐模块重复输出。
-
允许合并或精简
- 若模块确实无实质性安全攻击面，Layer 3 输出可为空或仅保留 1-2 条从 Layer 1/2 映射的高优先级安全问题，保证信噪比。
Step 5: 汇总与报告生成
- 去重与关联：合并三层发现，去除重复项，建立跨层关联（如 Layer 1 的 UAF 与 Layer 3 的内存安全漏洞）
- 优先级重排：综合三层的严重程度、触发可能性、影响范围，生成最终的 P0/P1/P2 排序
- 生成报告：
- 将三层合并、去重、重排后的发现列表写入 JSON 文件
{模块名}_deep_scan_findings.json。JSON 中的字段名和风险等级均支持中英文两种写法：
- 字段名：
file_path / 文件路径，line_number / 行号，summary / 问题概述，description / 问题详细描述，issue_type / 问题类型，risk_level / 风险等级
- 风险等级：
critical|high|medium|low 或 致命|严重|一般|提示
- 格式示例：
{
"findings": [
{
"file_path": "问题所在源文件的相对路径或绝对路径",
"line_number": "123 或 120-130，多段用逗号分隔",
"summary": "简短、明确的问题标题（一句话）",
"description": "问题详细描述，必须包含：问题描述、问题代码片段、修复建议、影响评估",
"issue_type": "内存安全|并发安全|错误处理|权限安全|路径安全|整数安全|反序列化|代码逻辑|资源泄漏|信息安全",
"risk_level": "critical|high|medium|low 或 致命|严重|一般|提示"
}
]
}
- 调用统一报告生成脚本生成 Excel：
python3 /path/to/.claude/skills/deep-scan/scripts/generate_report.py \
--module-name <模块名> \
--input <模块名>_deep_scan_findings.json \
--output-dir .
- 输出文件：
{模块名}_deep_scan_issues.xlsx。
- 该脚本会统一保证表格的列头、列宽、颜色、边框、排序、冻结首行等样式完全符合下述「规范输出」要求。
Excel 汇总表格式（规范输出）
使用 .xlsx 文件，工作表名称为 {模块名} 高影响问题，必须包含以下列：
| 列名 | 内容要求 |
|---|
文件路径 | 问题所在源文件的相对路径或绝对路径 |
行号 | 问题代码位置，支持单行 123 或范围 120-130，多段用逗号分隔 |
问题概述 | 简短、明确的问题标题（一句话） |
问题详细描述 | 必须包含：问题描述、问题代码片段、修复建议、影响评估 |
问题类型 | 如：内存安全、并发安全、错误处理、权限安全、路径安全、整数安全、反序列化、代码逻辑、资源泄漏、信息安全 |
风险等级 | 致命 / 严重 / 一般 / 提示（或 critical / high / medium / low） |
样式规范：
- 首行为表头，深蓝底（
4472C4）白字，居中加粗
- 所有单元格细边框，自动换行，垂直顶对齐
风险等级 列按等级着色：致命 / critical=红色（FF0000）、严重 / high=浅红（FF7F7F）、一般 / medium=橙色（FFC000）、提示 / low=黄色（FFFF00）- 冻结首行，列宽参考：文件路径 55、行号 18、问题概述 40、问题详细描述 90、问题类型 18、风险等级 12
- 使用
.claude/skills/deep-scan/scripts/generate_report.py 生成时，上述格式会自动生效，无需手动设置单元格样式。
约束与注意事项
- 每个 Layer 的扫描必须基于实际代码证据，禁止猜测
- 默认排除文件名以
ets 或 cj 开头的源文件
- 对于无法确认触发路径的问题，标记为 Suspicious 并放入后续跟进，不混入 Confirmed/Likely
- 优先报告 Confirmed 和 Likely 的 P0/P1 问题，控制总发现数量以保证高信噪比
- 若目标路径包含大量自动生成的代码（如 ANI/NAPI 绑定生成代码），应排除或单独标注
- 报告中的代码引用必须包含文件路径和行号，格式为
path/to/file.cpp:123
