discover-attack-surface

技能：发现攻击面

处理一份项目使用的依赖成员分配任务，并从中找出污点源——即不可信数据首次进入的方法。分配的语言参考文档定义了以下工作流的具体检查命令和标识符格式。

输入

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

• project-root（可选）——目标项目的根目录。Opentaint 将所有分析产物保存在固定的 <project-root>/.opentaint/ 目录下，因此以下所有 .opentaint/... 路径均相对于该目录解析。默认值：当前目录
• language（必需）——此项目的目标语言及特定语言说明
• plan（必需）——此 Agent 的分区计划路径 .opentaint/tracking/rules/plans/<id>.yaml：需要分类的项目使用的依赖成员

工作流

开始前先阅读 references/<language>.md。其中的编号步骤提供了以下工作流的特定语言细节。

1. 检查计划中的成员

分配计划的 scopes 包含已提取、仍需判定的项目使用依赖成员。只检查这些成员。确认其依赖身份和准确签名，然后阅读应用源代码、依赖源代码和 API 文档、典型用法以及相关框架配置，以了解数据如何进入项目。

2. 分类计划中的成员

污点源是一个明确的边界：不可信数据在此首次从网络、持久化存储、序列化、消息传递、执行或其他外部通道进入。对于可调用成员，判断它是否返回或以其他方式暴露攻击者可控的数据。仅传递其接收到的数据的成员是传播器，而非污点源。

根据行为而非包名或类名进行分类。对于单个成员，优先记录边界情况的污点源并注明不确定性：后续扫描和分类可排除误报，而遗漏的污点源会造成无法挽回的漏报。

3. 记录判定结果和源单元

按照语言参考文档要求的格式，补全计划中的源列表。记录计划中发现的每个污点源，并创建其源单元，设置 tag: untrusted-data-source；稍后在 create-rule 中将该单元解析为现有规则或新规则。非污点源不创建单元。若结果为空，需明确标记，以便 reconcile join 将其与 Agent 未返回结果的计划区分开来。如果已有归属的单元，则合并新条目，不要改写其现有条目或阶段。

4. 返回前验证

根据分类重新检查完整的分配范围。重新阅读每个被排除的成员，确保它没有建立外部输入边界。确认每个污点源都同时出现在已完成的计划和源单元中，没有被排除的成员拥有单元，并且不存在待处理或空值判定。

输出

简短精炼地报告完成的工作

产物：

• .opentaint/tracking/rules/sources/<unit>.yaml — 已完成计划要求的每个源单元
• 已分配的计划，其中已在 source 下记录发现的污点源

摘要：

• 找到的源成员，每项一行
• 任何受阻事项或仍不确定的内容

跟踪

.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

此技能会设置 tag: untrusted-data-source，填写 dependencies，并为每个源添加一个 { method, signature, note, rule_id } 条目。将计划中的 method 和 signature 复制过来，在 note 中说明数据为何不可信，并将 rule_id: null 和 stages 留给规则编写阶段处理。

计划 .opentaint/tracking/rules/plans/<id>.yaml — 从其 scopes 映射中读取你的成员，将找到的源记录在顶层 source 列表中；随后，合并步骤会记录 source 和 safe（成员 − source），并以精确的 method 和 signature 为键，确保不同的可调用变体保持独立。该文件可重新生成，也可丢弃，不是持久状态：

id: lib-001
scopes:
  <package-kebab>:
    - { method: "<qualified-member-a>", signature: "<language-signature-a>" }
    - { method: "<qualified-member-b>", signature: "<language-signature-b>" }
source:
  - { method: "<qualified-member-a>", signature: "<language-signature-a>" }

source: null 是生成计划中表示尚未处理的哨兵值。完成后，将其替换为找到的确切源；如果没有源，则替换为 source: []；mark-safe 会让 null 计划保持原样以供重新分派，而不是错误地将其所有成员归类为 safe。列为源的每个成员也必须出现在其源单元中。

约束

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

• 此阶段只查找源——即不可信数据进入的边界；稍后会根据污点前沿查找 sink
• 只处理你自己的计划及其映射的源单元——绝不处理其他 Agent 的计划或单元、共享覆盖范围／分类状态或 tags.yaml。计划会根据语言参考资料划分各自的写入权限
• 存储式／二阶注入（数据先持久化再读回）由引擎本身建模——不要为读回操作记录源，也不要为存储→读取路径记录传播器