CodeMender 查找模式

CodeMender 通过 cm find 命令提供三种不同的扫描模式。每种模式都针对软件开发生命周期的特定阶段而设计，在速度、范围和深度之间取得平衡。

比较查找模式

下表比较了三种 cm find 扫描模式：

模式 命令 目标范围 典型运行时 适用场景
深度扫描（默认） cm find PATH 指定的目录或代码库 更长的运行时 全面的安全审核、发布就绪情况、合规性认证（SOC 2、ISO）
差异扫描 cm find PATH --diff[=REF] 修改后的文件以及依赖文件（例如调用方和被调用方） 快速运行时 拉取请求 CI/CD 流水线（GitHub Actions、Cloud Build）、预提交钩子
快速扫描 cm find PATH --quick 指定目录 中等运行时 探索当地开发者的佳作、快速检查、探索性评价

深度扫描（默认）

如果您在运行 cm find 时未提供其他扫描标志，则默认模式为深度扫描（为实现向后兼容性，也支持 --deep 标志）。这是一种详尽的扫描模式，专为全面的安全审核而设计。它使用并行工作器（通过 --deep-workers 配置，默认值为 8，支持 1 到 16 的范围）同时审核目标目录或代码库中的源文件。在发现候选发现结果时，它会根据周围的代码上下文对其进行验证和证实，以便在报告结果之前滤除假正例。

以下示例演示了如何对代码库运行深度扫描：

# Run an exhaustive deep scan across the repository (default mode)
cm find .

# Tune concurrency and use the cyber-specialized security model
cm find . --deep-workers=8 --model=gemini-3.8-flash-cyber

优势

深度扫描无需任何配置即可运行，可在大型企业代码库中实现高召回率和全面的漏洞发现。它优于单会话扫描，并使用自动验证来保持高精确率。它还独立于平台，适用于 Gemini 支持的所有语言，无需特定语言的编译器、构建设置或语法文件。最后，它通过将分析重点放在生产代码上，并最大限度地减少非生产文件的计算和 token 消耗，从而优化资源使用。

权衡和限制

请勿将深度扫描用作会阻止拉取请求的同步检查。深度扫描会执行彻底的逐文件分析。因此，与快速扫描或差异扫描相比，它们需要更长的运行时和更高的 token 支出。

何时使用

在以下情况下，请使用深度扫描：

  • 在所有生产代码库中，按夜间或每周时间表运行预定的安全审核。
  • 在发布主要版本或进行生产部署之前，执行全面的预发布安全审核。
  • 生成审核证据，用于 SOC 2、ISO 27001、FedRAMP 或 PCI-DSS 合规性和认证审核。
  • 在将新代码库添加到 CodeMender 时，建立初始安全基准。

差异扫描

差异扫描会检查已修改和已添加的文件，重点关注发生更改的确切行范围（差异块），从而对拉取请求工作流和 CI/CD 流水线执行 Git 差异分析。除了检查更改的代码行之外，它还会执行影响分析，以发现代码库中调用、导入或依赖于修改后的函数和符号的未更改文件。这有助于确保在一个文件中更改协定或函数签名不会在依赖文件中引入漏洞。

在扫描期间，CodeMender 会自动隔离未修改代码中预先存在的漏洞，以免旧问题导致扫描失败或阻止拉取请求。然后，它会根据您的 --fail-on 政策评估发现结果，并以表格、JSON 或 SARIF v2.1.0 格式输出结果。

以下示例演示了如何针对工作副本更改、暂存更改或目标分支运行差异扫描：

# Scan working copy changes versus HEAD
cm find . --diff

# Scan staged changes only (pre-commit)
cm find . --diff --staged

# Scan a pull request branch against the main branch in CI/CD
cm find . --diff=origin/main --format=sarif --output=results.sarif \
    --fail-on=CRITICAL,HIGH

如需了解端到端流水线配置，请参阅与 CI/CD 集成。

优势

差异扫描快速且具有确定性，通常在 2 分钟内完成，以缩短 CI/CD 流水线运行时。与仅检查更改行的 diff 扫描器不同，--diff 会检查调用方和被调用方关系，以捕获跨文件安全回归和协定违规。由于它会抑制未修改代码中的发现结果，因此扫描只会阻止因更改而引入或受更改影响的问题的拉取请求，从而避免报告过多和不必要的构建失败。差异扫描还会发出 SARIF v2.1.0，以便直接集成到 GitHub 代码扫描注释和 Cloud Build 信息中心。

权衡和限制

差异扫描仅分析拉取请求受影响区域内的代码，不会在代码库中未改动的部分查找预先存在的漏洞。此外，还需要一个有权访问目标基础引用的 Git 代码库。

何时使用

在以下情况下，请使用差异扫描：

  • 在 GitHub Actions、Cloud Build、GitLab CI 或 Jenkins 等 CI/CD 流水线中，对每个拉取请求运行自动化检查。
  • 在将代码推送到远程仓库之前，请在预提交或预推送钩子中验证本地更改是否干净。
  • 验证发布分支之间的合并不会导致回归。

快速扫描

快速扫描 (cm find --quick) 会对指定目标目录运行单会话自主扫描，而不是默认的并发逐文件深度扫描。在扫描期间，CodeMender 会发现源文件，根据漏洞模式确定其优先级，执行初始安全分析，并报告按严重程度和类型分组的潜在漏洞。

以下示例演示了如何对目标目录运行快速扫描：

# Run a single-session quick scan on a directory using the default model
cm find ./src --quick

# Run a quick scan with a specific Gemini model
cm find ./src --quick --model gemini-3.8-flash

优势

快速扫描兼顾了速度和覆盖范围，运行时间适中，且使用的 token 和计算资源比完整深度扫描更少，因此在日常开发过程中进行快速探索性检查时更具成本效益。

权衡和限制

快速扫描在大型代码库中的召回率较低，并且可能不会探索大型多软件包企业代码库中的每个文件，因为它在单个会话上下文中运行。它还主要关注单个文件中的局部模式，这限制了跨软件包分析，并且可能会遗漏跨越遥远软件包的漏洞。

何时使用

在以下情况下，请使用快速扫描：

  • 在本地机器上运行快速扫描，以便在本地开发期间快速获得反馈。
  • 检查新克隆的代码库或小型项目，快速初步评估其安全状况。
  • 在进行快速探索性检查时，检查特定子目录或模块。

选择查找模式

请使用下表为您的工作流选择合适的扫描模式：

工作流或环境 应用场景和目标 推荐模式 示例命令
本地终端 快速发现或对特定模块进行置信度检查 快速扫描 cm find ./src --quick
本地终端 在推送之前对暂存的更改进行预提交检查 差异扫描 cm find . --diff --staged
CI/CD 流水线 针对更改的代码和调用方自动进行拉取请求控制 差异扫描 cm find . --diff=origin/main --fail-on=CRITICAL,HIGH
已安排的流水线或审核 夜间审核、预发布检查、SOC 2 合规性 深度扫描 cm find . --deep-workers=8

命令标志参考（按模式）

下表介绍了每种扫描模式支持的命令行标志。

常用标志（所有模式）

以下标志适用于所有 cm find 扫描模式：

标志 默认 说明
-c, --context TEXT "" 用于指导扫描代理的其他上下文，例如架构说明。
--model MODEL_NAME gemini-3.8-flash 要使用的 Gemini 模型（gemini-3.8-flash、gemini-3.8-flash-cyber）。
-y, --yes false 跳过交互式确认提示和自动更新检查。 在启用操作系统级沙盒并采用默认网络隔离 (permissive-closed) 的情况下，cm find 会以只读方式装载工作区，并自动跳过命令确认提示。
--sandbox true 在操作系统级沙盒中运行命令（例如，--sandbox=false 可停用）。在 cm find 中，沙盒会以只读方式装载工作区。
--allow-all-paths false 停用工作区路径边界检查（与 --sandbox=false 结合使用，可访问未装载到沙盒中的主机路径）。
--allow-all-commands false 为此运行停用 command_policy.yaml 屏蔽名单强制执行。
--include-hidden false 在文件发现期间包含隐藏的目录和文件（以 . 开头）。

深度扫描标记

以下标志用于配置默认 cm find（或 cm find --deep）扫描：

标志 默认 说明
--deep true 运行详尽的逐文件深度扫描（未传递模式标志时的默认模式）。不能与 --diff 或 --quick 一起使用。
--deep-workers COUNT 8 每个文件深度扫描的并发工作器数量（1 到 16）。
--enable-bash false 在每个文件的 --deep 工作器中启用 shell 命令执行 (run_command)（或设置 CMOC_FIND_ENABLE_BASH=true）。快速扫描 (--quick) 和差异扫描 (--diff) 默认启用 run_command。

差异扫描标志

以下标志用于配置 cm find --diff 扫描：

标志 默认 说明
--diff[=REF] 关闭 针对目标引用（例如 origin/main 或 HEAD~1）启用差异模式。如果没有 REF，则与 HEAD 进行比较。不能与 --deep 或 --quick 一起使用。
--staged 关闭 仅将 diff 范围限定为暂存索引 (git diff --cached)。需要 --diff。
--diff-workers COUNT 4 拉取请求审核作业的并发工作器数量（1 到 16）。
--diff-max-neighbors COUNT 10 要检查的依赖调用方或被调用方文件的数量上限。
--fail-on SEVERITIES CRITICAL,HIGH 以逗号分隔的严重级别，会导致 cm find 退出并显示代码 1。
--fail-on-truncation 关闭 如果邻居发现超出上限，则退出并返回代码 1。
--format FORMAT table 输出格式：table、json 或 sarif。
--output FILE 标准输出 将报告写入文件，而不是标准输出。

快速扫描标志

以下标志用于配置 cm find --quick 扫描：

标志 默认 说明
--quick false 运行单会话快速扫描，而不是默认的并发逐文件深度扫描。不能与 --deep 或 --diff 一起使用。