create-test-project

技能：创建测试项目

构建一个最小化的已编译测试项目，其样例能够复现验证规则或近似结果所依据的流程。样例在真实库方法与脚手架提供的通用污点标记之间传递数据，并且必须产生一种判定结果——必须标记的正例，或不得标记的反例。交付物是已编译模型；样例源码与其放在一起。

输入

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

• project-root（可选）— 目标项目的根目录。Opentaint 会将所有分析产物保存在固定的 <project-root>/.opentaint/ 目录下，因此下方所有 .opentaint/... 路径都会相对于该目录解析。默认值：当前目录
• language（必需）— 此项目的目标语言及语言专属说明
• type（必需）— 此项目要验证的内容，用于选择样例风格和下方的标识输入：rule-source、rule-sink 或 dataflow
• 对于 rule-source / rule-sink，填写 unit：单元 ID；其成员和 dependencies 来自 .opentaint/tracking/rules/sources|sinks/<unit>.yaml
• 对于 dataflow，填写 batch：批次；其 .opentaint/tracking/approximations/<batch>.yaml 提供要测试的数据流方法及其 dependencies

项目文件夹 <name> 使用该标识符命名——规则侧使用 unit，数据流近似使用 batch。

工作流

1. 搭建项目脚手架

脚手架命令和样例形式因语言而异——请根据 type 阅读对应参考文档：rule-source / rule-sink 使用 references/<lang>-rule.md，dataflow 使用 references/<lang>-approximation.md（只需阅读这一份完整参考文档，无需阅读另一份）。为该 type 搭建项目脚手架，并将 unit 的每个 dependencies 固定在指定版本。如果 <name> 项目已存在（因其覆盖范围扩大或依赖发生变更而再次调用），则应扩展现有项目：添加缺失的样例并重新编译，而不是重新搭建。初始化命令位于对应的参考文档中。脚手架提供通用污点标记和样例所针对的固定测试规则，因此你只需编写样例。

2. 编写样例

对于某个单元或批次，每个条目都记录了其 signature；请根据该可调用项在项目中的实际用法，构造忠实的样例。应用的实际路径无关紧要，只需确保数据在边界与标记之间流动：

对于 sink 单元，方法嵌套在 groups[].sinks 下；请测试每个方法，同时保留分组边界，以供后续规则作者使用。

• 对应项始终是通用标记，而不是真实的 source/sink，因此样例只测试待测单元
• 在测试的 rule-test.yaml 中，为每个样例登记其必须产生的判定结果——必须标记的正例，以及在该类型需要时不得标记的反例

样例代码、rule-test.yaml 格式，以及各类型所需的判定结果均见对应参考文档。

3. 编译为模型

将构建的项目编译到 .opentaint/test-compiled/<name>——规则侧将搭建的单个子项目（sources/ 或 sinks/）编译为对应的子模型；数据流项目则编译一次：

# rule side — the one you built
opentaint compile .opentaint/test-projects/<name>/sources -o .opentaint/test-compiled/<name>/sources
# dataflow
opentaint compile .opentaint/test-projects/<name> -o .opentaint/test-compiled/<name>

编译通过即为交付物。反馈循环：构建失败通常是样例或依赖问题，可以修复——明确指出实际错误，修复后重新编译。编译通过后，按照 Tracking 将测试项目阶段标记为完成。

4. 升级处理

如果项目在约 3 次修复后仍无法编译，且原因不明确 → 报告失败，并将测试项目阶段保持为待处理状态，由协调器介入。

输出

简短扼要地报告已完成的工作

工件

• .opentaint/test-compiled/<name> — 后续阶段运行时使用的已编译测试模型；报告每个路径以及使用的确切 compile 命令
• .opentaint/test-projects/<name> — 示例源代码和记录其判定结果的 rule-test.yaml，与模型放在一起

摘要

• 每个案例编写的样例数量
• 因无法编写样例而排除的任何方法（标记为 failed），并简要说明原因
• 失败的项目（如有）

跟踪

此技能只回写测试项目阶段：

• 规则一侧 → 在源单元或汇单元中设为 stages.test_project: done
• 数据流近似 → 在批次文件中为每个方法添加一条 build.test_project 记录；样例已纳入项目的方法设为 status: done；无法编写样例的方法（已排除）设为 status: failed

.opentaint/tracking/rules/sources/<package-kebab>.yaml — 每个包对应一个源单元（一个依赖项可能涉及多个包），文件名使用包名，将 . 替换为 -。tag 始终是可复用的 untrusted-data-source 组。dependencies 指明包所属的依赖项；sources 中的每项入口点为 { method, signature, note, rule_id }（method 和 signature 使用计划中的精确语言专属标识符）；stages 跟踪该单元的规则编写进度；如果无法让该单元通过，则在其下添加 blocker 字符串。请在注释中说明清楚

dependencies:
  - <dependency-id>
tag: untrusted-data-source
sources:
  - { method: "<qualified-member>", signature: "<language-signature>", note: untrusted message payload, rule_id: null }
stages:
  test_project: pending
  tests_passing: pending

.opentaint/tracking/rules/sinks/<package-kebab>.yaml — 每个包对应一个汇单元（一个依赖项可能涉及多个包，每个包各有一个单元），文件名使用包名，将 . 替换为 -。dependencies 指明包所属的依赖项。groups 按可复用的汇标签对包中的危险操作进行分类；每个组为 { tag, sinks }，每个汇为 { method, signature, note, rule_id }。标签属于组，不属于单个方法：一条规则可以覆盖多个方法，多个规则也可以扩展同一漏洞类别。method 和 signature 使用计划中的精确语言专属标识符。stages 跟踪该单元的规则编写进度。请在注释中说明清楚

dependencies:
  - <dependency-id>
groups:
  - tag: path-traversal-sink
    sinks:
      - { method: "<qualified-member>", signature: "<language-signature>", note: writes data to an untrusted path, rule_id: null }
stages:
  test_project: pending
  tests_passing: pending

.opentaint/tracking/approximations/<batch>.yaml — 一个批次的可调用项分类，<batch> 为计划的文件名主体。每个可调用项必须且只能属于一个判定类别，类别以计划中的精确语言专属 method 和 signature 为键，以便区分不同变体：

• passthrough、dataflow — 已建模的载体；每项为 { method, signature }
• skipped — 终止的非载体；每项为 { method, signature, reason }
• engine_issues — 单独存放引擎已证明无法传播的载体（已构建但仍被丢弃）；每项为 { method, signature, reason }。这类方法会终止处理，且与 skipped 一样处理——唯一差别是原因。merge-skipped 会将其作为独立的 engine_issues 组并入 skipped.yaml，与常规的 methods 并列。

dependencies 列出数据流测试项目所需的依赖项标识符。build 块跟踪构建情况——test_project 记录每个数据流方法的测试项目状态（样例已写入该批次的测试项目时为 done；无法编写样例、因此从项目中排除时为 failed）；done 保存已完成的 { method, signature }。请在注释中说明清楚

passthrough:
  - { method: "<qualified-member-a>", signature: "<language-signature-a>" }
dataflow:
  - { method: "<qualified-member-b>", signature: "<language-signature-b>" }
skipped:
  - { method: "<qualified-member-c>", signature: "<language-signature-c>", reason: "retains none of its input data" }
engine_issues: []
dependencies: []
build:
  test_project:
    - { method: "<qualified-member-b>", signature: "<language-signature-b>", status: done }
  done: []

约束

OpenTaint 是一个全程序、过程间、字段敏感的别名分析引擎。它已能传播穿过可见应用代码、调用、别名和单个字段；自定义规则和近似仅用于建模指定的源、汇或不透明方法边界。编译时常量和字面值不携带污点，因此，如果源或载体的输出只有常量，则不会引入任何内容。

• 每个单元使用一个 <name> 文件夹——切勿写入其他单元的测试项目，以免并发 Agent 之间发生竞争