deep-scan

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 将三个专业扫描能力串联为固定工作流，对目标路径进行分层、递进式风险排查：

1. Layer 1: high-impact-bug-audit — 聚焦崩溃、挂死、OOM、数据损坏、资源泄漏、状态污染等高影响缺陷
2. Layer 2: logic-analyzer — 分析代码修改/逻辑分支的深层影响，发现隐藏的逻辑不一致、边界遗漏、副作用
3. 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: 路径确认与范围界定

1. 确认 path 存在且为目录或文件
2. 列出该路径下的主要源文件类型（.cpp, .h, .hpp, .js, .ts 等），并排除 ets/cj 前缀文件
3. 若路径过大（超过50个文件），询问用户是否聚焦子目录或按模块拆分
4. 根据文件类型和路径特征，确定 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 应按以下原则收敛扫描范围，避免过度展开和重复分析：

1. 聚焦真实攻击面，而非理论风险

   • 只分析目标模块自身代码中实际存在的外部输入点（函数参数、返回值、动态加载调用等）。
   • 不主动推演父类/依赖模块的权限继承、生命周期行为或构建加载顺序等跨模块假设性问题，除非目标模块代码中直接涉及相关逻辑。

2. 避免与 Layer 1/2 重复分析

   • 若同一问题已在 Layer 1 或 Layer 2 中发现（如 int *bufLen 截断、requireNapi 失败路径），Layer 3 应直接将其映射为对应安全等级，补充安全视角（如“整数截断导致潜在越界读取”），而非重新从头展开分析。

3. 控制检查清单规模

   • 对无 IPC、无文件解析、无网络、无反序列化、无敏感数据的模块，不强制套用完整漏洞模式清单。
   • 重点检查：内存安全（与 Layer 1 交叉验证）、数据暴露/信息泄露、动态加载/外部依赖、以及实际存在的输入边界问题。

4. 跨模块系统性问题仅记录一次

   • 若发现的问题属于同一路径下多个模块共有的模式（如多个 NAPI 模块使用相同 int *bufLen 签名），在 Layer 3 中只记录一次，并在问题描述中注明“该模式同样存在于同路径下其他模块”，不逐模块重复输出。

5. 允许合并或精简

   • 若模块确实无实质性安全攻击面，Layer 3 输出可为空或仅保留 1-2 条从 Layer 1/2 映射的高优先级安全问题，保证信噪比。

Step 5: 汇总与报告生成

1. 去重与关联：合并三层发现，去除重复项，建立跨层关联（如 Layer 1 的 UAF 与 Layer 3 的内存安全漏洞）
2. 优先级重排：综合三层的严重程度、触发可能性、影响范围，生成最终的 P0/P1/P2 排序
3. 生成报告：
   • 将三层合并、去重、重排后的发现列表写入 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