run-scan

技能：运行扫描

对项目模型运行 OpenTaint 扫描并收集其发现结果

输入

由调用方提供；省略时使用默认值。仅当必需输入缺失且没有合理默认值时才询问

• project-root（可选）— 目标项目的根目录。Opentaint 会将所有分析产物保存在固定的 <project-root>/.opentaint/ 目录下，因此以下所有 .opentaint/... 路径都会解析到该目录。默认值：当前目录
• rule-ids（可选）— 用于限定扫描范围的完整规则 ID
• max-memory（可选）— 运行扫描时使用的 --max-memory 值。默认值：未设置（引擎默认值 8G）

工作流

1. 运行扫描

扫描预构建模型 .opentaint/project。将报告写入 .opentaint/results/report.sarif，并加载内置规则集以及项目在 .opentaint/rules 下的自有规则：

opentaint scan --project-model .opentaint/project \
  -o .opentaint/results/report.sarif \
  --ruleset builtin --ruleset .opentaint/rules \
  --track-external-methods

• --rule-id <full-id> — 限定为指定的可执行规则（可重复，每个输入规则 ID 使用一次）；引用的库规则仍可用，无需单独列出其 ID。省略则运行所有已加载的规则
• --passthrough-approximations .opentaint/pass-through — 仅当该目录存在时添加：passThrough 配置会在规则级别覆盖内置配置；提供的规则仅在匹配时才会覆盖内置规则
• --dataflow-approximations .opentaint/dataflow — 仅当该目录存在时添加：基于代码的近似配置（源文件会自动编译；预编译的 .class 目录会原样传入）

两个近似配置目录标志都会递归遍历目录树；每个父目录只需传入一次，无需分别传入每个包或批次。

扫描耗时较长——请在后台运行并等待其完成。将 --timeout 保持为引擎默认值（900s）；CLI 会自行结束分析并写入已有的 SARIF 数据。

2. 内存不足时重试一次

从默认值 8G 开始。8G 时发生内存不足——即使引擎仍写入了部分 SARIF——也不可接受：收集任何内容前，先使用 --max-memory 16G 重试一次。绝不使用更高值（更多 RAM 不会改善结果），只提升一次。如果调用方传入了 max-memory，则从首次尝试起就使用该值

3. 收集报告，或升级处理

即使伴随出现两种常见扫描错误之一，SARIF 也足够完整，可以使用：超时（CLI 结束了分析并写入已有内容），或在 16G 时内存不足（按 §2 提升后）；请按原样使用。其他两种情况都不能作为可接受的结果。因近似配置格式错误导致的配置加载失败，应修复而非提升内存：按输出要求报告引擎错误以及 .opentaint/pass-through/.opentaint/dataflow 下出错的文件，以便修复并重新扫描。即使在 16G 下也完全没有 SARIF，则属于普通失败：按输出要求报告失败情况及扫描设置。

输出

简短精炼地报告所做的工作

产物：

以下三项均与报告一起位于 .opentaint/results/ 下：

• .opentaint/results/report.sarif — 包含代码流跟踪的发现结果
• .opentaint/results/dropped-external-methods.yaml — 因缺少模型而导致数据流事实被丢弃的外部方法
• .opentaint/results/approximated-external-methods.yaml — 已建模的外部方法

摘要：

• 发现数量，以及被丢弃与已近似处理的外部方法数量
• 是否将内存提升至 16G
• 如果扫描因近似配置格式错误而在配置加载时失败：报告引擎错误以及出错的 .opentaint/pass-through 或 .opentaint/dataflow 下的文件（根据错误信息定位），以便修复并重新扫描——这不是内存不足错误，16G 无济于事
• 如果即使在 16G 下也没有生成 SARIF：说明扫描仍处于失败状态，并报告所用的设置（包含规则集、近似配置目录和模型的完整扫描命令）

限制

• 绝不手动编辑项目模型来更改扫描结果——此技能只读取模型。如果模型有误，应在模型阶段重新构建，而不是修改 project.yaml 或其下的任何内容