CodeMender 查找模式

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

比较查找模式

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

模式 命令 目标范围 典型运行时 适用场景
标准扫描 cm find PATH 指定目录 中等运行时 本地开发者探索、快速检查、探索性评价
差异扫描 cm find PATH --diff[=REF] 修改后的文件以及相关文件（例如调用方和被调用方） 快速运行时 拉取请求 CI/CD 流水线（GitHub Actions、Cloud Build）、pre-commit 钩子
深度扫描 cm find PATH --deep 整个代码库 更长的运行时 定期审核、发布准备情况、合规性认证 (SOC 2、ISO)

标准扫描（默认）

如果您在运行 cm find 时未提供其他扫描标志，则标准扫描是默认模式。它会对指定的目标目录运行单会话自主扫描。在扫描过程中，CodeMender 会发现源文件，根据漏洞模式确定其优先级，执行初始安全分析，并报告按严重程度和类型分组的潜在漏洞。

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

# Scan a directory using the default model
cm find ./src

# Scan with a specific Gemini model
cm find ./src --model gemini-3.8-flash

优势

标准扫描无需任何配置，也不需要额外的标志或参数。它在速度和覆盖率之间实现了平衡，运行时长适中，使用的令牌和计算资源最少，因此非常适合日常开发。

权衡和限制

标准扫描在大型代码库上的召回率较低，并且可能不会探索大型多软件包企业代码库中的每个文件，因为它在单个会话上下文中运行。它还主要侧重于单个文件中的本地模式，这限制了跨软件包分析，并且可能会遗漏跨多个软件包的漏洞。

何时使用

在以下情况下使用标准扫描：

  • 在提交更改之前，在本地机器上运行扫描，以便在本地开发期间快速获得反馈。
  • 检查新克隆的代码库或小型项目，初步评估其安全状况。
  • 在调查潜在问题时，检查特定子目录或模块。

差异扫描

差异扫描通过检查已修改和已添加的文件，针对拉取请求工作流和 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 会检查调用方和被调用方之间的关系，以捕获跨文件的安全回归和合约违规情况。由于它会抑制未触及代码中的发现，因此扫描只会阻止因更改而引入或受更改影响的问题的拉取请求，从而避免生成杂乱的报告和不必要的 build 失败。差异扫描还会发出 SARIF v2.1.0，以便直接集成到 GitHub 代码扫描注释和 Cloud Build 信息中心。

权衡和限制

差异扫描只会分析拉取请求中受影响区域内的代码，而不会在代码库中未触及的部分查找预先存在的漏洞。此外，还需要一个可访问目标基本参考的 Git 代码库。

何时使用

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

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

深度扫描

深度扫描是一种详尽的扫描模式，旨在进行全面的存储库级安全审核。它使用并行工作器（通过 --deep-workers 配置，默认值为 8，支持的范围为 1 到 16）同时审核整个代码库中的源文件。在发现候选结果后，它会根据周围的代码上下文对其进行验证和佐证，以滤除误报，然后再报告结果。

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

# Run an exhaustive deep scan across the entire repository
cm find . --deep

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

优势

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

权衡和限制

请勿将深度扫描用作会阻塞拉取请求的同步检查。深度扫描会执行全面的代码库级分析。因此，与标准扫描或差异扫描相比，它们需要更长的运行时和更高的令牌支出。

何时使用

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

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

选择查找模式

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

工作流或环境 使用场景和目标 推荐模式 示例命令
本地终端 快速发现或检查特定模块的信心 标准扫描 cm find ./src
本地终端 在推送之前对暂存的更改进行预提交检查 差异扫描 cm find . --diff --staged
CI/CD 流水线 针对更改的代码和调用者的自动拉取请求门禁 差异扫描 cm find . --diff=origin/main --fail-on=CRITICAL,HIGH
已安排的流水线或审核 每晚审核、预发布门禁、SOC 2 合规性 深度扫描 cm find . --deep --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 跳过所有交互式确认提示。
--unrestricted false 关闭文件系统沙盒。

差异扫描标志

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

标志 默认 说明
--diff[=REF] 关闭 针对目标参考（例如 origin/main 或 HEAD~1）启用差异模式。如果不指定 REF，则与 HEAD 进行比较。无法与 --deep 搭配使用。
--staged 关闭 仅将范围限定为已暂存的索引 (git diff --cached)。 需要 --diff。
--diff-depth DEPTH 1 影响分析的遍历深度（1 到 3，默认值：1 跳）。
--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 --deep 扫描：

标志 默认 说明
--deep false 启用详尽的整个代码库深度扫描。无法与 --diff 一起使用。
--deep-workers COUNT 8 深度扫描的并发工作器数量（1 到 16）。