taint-trace

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Taint Trace

污点追踪

Make an existing static taint analyzer understand the codebase's missing contracts. Trailmark supplies structural evidence; the chosen analyzer computes taint flows. Every reported flow must identify the analyzer run and the models it depended on.
让现有的静态污点分析器理解代码库中缺失的契约。 Trailmark 提供结构性证据;所选分析器负责计算污点流。 每条报告的数据流都必须标明所使用的分析器运行,以及其所依赖的模型。

Quick Start

快速开始

Invoke
/trailmark:taint-trace-run
with a target directory. Optional arguments select languages, backend overrides, and a sink focus. The dynamic workflow owns the staged execution; the contracts here also apply on hosts executing this skill directly. When invoking the workflow from this loaded skill, pass
skill_dir: "{baseDir}"
so its trusted helper/reference location is explicit, including checkout installs.
bash
bash "{baseDir}/scripts/taint_trace.sh" catalog
bash "{baseDir}/scripts/taint_trace.sh" context \
  --target <target> --languages auto \
  --output <target>/.trailmark/taint-trace/context.json
Read the language and backend catalog, then only the selected backend's reference. Prefer a working taint configuration already in the project. Otherwise use the catalog's ordered candidates and any requested backend overrides. A passing capability probe establishes the selected analysis mode; parser support and exit status alone do not. For version-specific mechanisms such as Psalm 7's precise flow contracts, inspect the probe's per-feature capability results and use only demonstrated mechanisms. The launcher runs the helper through
uv
, using
trailmark>=0.8.0,<0.9
from the package index. Native analyzers are separate dependencies.
使用目标目录调用
/trailmark:taint-trace-run
。可选参数用于选择语言、后端覆盖项和 sink 关注点。动态工作流负责分阶段执行;此处定义的契约也适用于直接执行此 skill 的主机。 从已加载的 skill 调用工作流时,传入
skill_dir: "{baseDir}"
,以明确指定可信辅助工具和参考目录的位置,包括从 checkout 安装的情况。
bash
bash "{baseDir}/scripts/taint_trace.sh" catalog
bash "{baseDir}/scripts/taint_trace.sh" context \
  --target <target> --languages auto \
  --output <target>/.trailmark/taint-trace/context.json
阅读语言与后端目录,然后只阅读所选后端的参考文档。优先使用项目中已经能够正常工作的污点配置。否则,使用目录中按顺序排列的候选项以及用户请求的后端覆盖项。 通过能力探测可以确定所选的分析模式;仅凭 parser 支持和退出状态并不足以证明其可用。 对于 Psalm 7 的 precise flow contracts 等版本特定机制,应检查探测结果中针对各项功能的能力结果,并且只使用已经证明可行的机制。 启动器通过
uv
运行辅助工具,并从包索引中安装
trailmark>=0.8.0,<0.9
。原生分析器是需要单独安装的依赖项。

Required Graph Evidence

必需的图证据

The helper directly checks
entrypoint_evidence()
,
entrypoint_candidates()
,
source_policy()
, attack-surface, diagnostics, and traversal APIs. Keep these capability checks even with the release dependency. Read graph evidence for binding and snapshot contracts. An incompatible installation is a setup failure; it cannot be replaced with LLM reachability guesses.
Inspect callers, callees, source spans, unresolved calls, dependency boundaries, and entrypoint evidence around dangerous sink arguments and external-input accessors. Use the graph to select relevant source for reasoning. Keep the analyzer's target scope broad enough to retain other entrypoints and alternative paths.
Entrypoint evidence can be a heuristic, an ambiguous binding, or a reference whose runtime consumer is unknown. Confirm which parameter, return, field, or receiver carries external data. A callback registration does not itself establish execution; a reachable function does not imply a tainted return value. Preserve these unknowns in model provenance and the report. References and deferred calls must remain distinguishable from confirmed calls.
辅助工具会直接检查
entrypoint_evidence()
、
entrypoint_candidates()
、
source_policy()
、攻击面、诊断信息和遍历 API。即使已有发行版依赖,也必须保留这些能力检查。 阅读图证据,了解绑定和快照契约。 不兼容的安装属于设置失败,不能用 LLM 的可达性猜测来替代。
检查危险 sink 参数和外部输入访问器周围的调用方、被调用方、source span、未解析调用、依赖边界和 entrypoint 证据。 使用图选择与推理相关的 source。保持分析器的目标范围足够宽泛,以保留其他 entrypoint 和替代路径。
Entrypoint 证据可能是启发式信息、模糊绑定,也可能是运行时使用方未知的引用。必须确认究竟是哪个参数、返回值、字段或 receiver 携带了外部数据。 回调注册本身不能证明代码会执行;函数可达也不代表其返回值已受到污染。 必须在模型 provenance 和报告中保留这些未知项。引用和延迟调用必须与已确认的调用保持可区分。

Model Contracts

模型契约

  • Add the smallest supported contract that repairs an observed modeling gap. Prefer native attributes/docblocks when supported; otherwise use native stubs, configuration, semantics, or rules. Comments the analyzer ignores are not models.
  • Establish why the analyzer needs the contract: retain baseline evidence of a missing binding, unresolved type, opaque boundary, or precision problem, and state the expected observable effect. Source evidence can justify a contract without showing that it adds value. Leave already understood wrappers unchanged; there is no annotation quota. See model quality.
  • Anchor each model to its declaration and exact affected value, vulnerability context, source evidence, assumptions, and native artifact. Graph node identities and line numbers belong to a snapshot; rebind after edits. When native tags leave conditions or context limits unclear, explain them in a short adjacent comment. Keep detailed graph evidence in the provenance artifacts.
  • Explain propagation with the implementation or dependency contract. Do not create a parameter-to-return summary solely because a call path would otherwise break.
  • A sanitizer removes only the threat it actually prevents, under the required conditions and for the correct value. HTML escaping does not sanitize SQL or shell commands. A boolean validator is not an unconditional sanitizer. When the backend cannot express the distinction, omit the sanitizer model and record the limitation.
  • Add type hints only when supported by source evidence and useful for analyzer resolution. Prefer documentation-only types when a runtime hint would change accepted values. Preserve application behavior, existing annotations, and existing analyzer configuration. Merge additions idempotently; do not widen exclusions, add suppressions, overwrite user models, or introduce runtime taint instrumentation.
  • Keep language boundaries explicit. Separate native findings may have a graph relationship without forming an analyzer-proven cross-language taint trace.
  • 添加能够修复已观察到建模缺口的最小受支持契约。 在受支持时优先使用原生 attributes/docblocks;否则使用原生 stubs、配置、semantics 或 rules。分析器会忽略的注释不属于模型。
  • 说明分析器为什么需要该契约:保留关于缺失绑定、未解析类型、不透明边界或精确度问题的基线证据,并说明预期产生的可观察效果。 Source 证据可以证明契约的合理性,但不一定能证明它增加了分析价值。不要修改分析器已经能够理解的 wrapper;不存在注解数量配额。 参见模型质量。
  • 将每个模型锚定到其声明和确切受影响的值、漏洞上下文、source 证据、假设及原生 artifact。 图节点标识和行号属于特定快照;编辑后必须重新绑定。 当原生 tags 未明确说明条件或上下文限制时,在邻近位置添加简短注释进行解释。将详细的图证据保存在 provenance artifacts 中。
  • 使用实现或依赖契约解释 propagation。不要仅仅因为调用路径 otherwise 会中断,就创建 parameter-to-return summary。
  • Sanitizer 只能移除其确实能够阻止的威胁,而且必须满足所需条件并作用于正确的值。HTML escaping 不会净化 SQL 或 shell 命令。布尔值 validator 不是无条件的 sanitizer。当后端无法表达这些区别时,应省略 sanitizer 模型并记录该限制。
  • 只有在 source 证据支持且有助于分析器解析时才添加 type hints。 当运行时 hint 会改变可接受值时,优先使用仅文档化的类型。保持应用行为、现有注解和现有分析器配置不变。 以幂等方式合并新增内容;不要扩大排除范围、添加 suppressions、覆盖用户模型或引入运行时 taint instrumentation。
  • 明确保持语言边界。彼此独立的原生 finding 之间可能存在图关系,但这并不构成由分析器证明的跨语言 taint trace。

Native Execution and Artifacts

原生执行与 Artifacts

Keep a baseline run before adding models and an enriched run afterward. Validate native model syntax and use real positive/negative capability fixtures for the selected language and backend. Required contracts are in artifact handling. The helpers extract evidence and validate artifacts; they do not implement a taint engine or certify model semantics. Inspect analyzer startup before discovery, version checks, builds, or analysis: autoloaders, plugins, compiler extensions, and configuration hooks can execute target code. Use trusted tooling and backend-supported isolation; record explicit hooks and any remaining execution assumptions. Static analysis is not a sandbox. Pass the baseline validation gate before modifying source or models. Rebuild context after edits while retaining the original snapshot; findings produced with added contracts remain conditional on those documented assumptions.
Store context, model provenance, native configuration, native outputs, and a readable report in the target's
.trailmark/taint-trace/
. Preserve source snapshots and native traces/SARIF where available. Record exact tool versions, commands, effective target coverage, exclusions, model changes, and finding changes. Keep captured evidence out of native source/rule discovery, including tools that scan unknown extensions; duplicate declarations can silently hide findings. Native warning counts are not unique flows or coverage. Inspect native traces for duplicate wrapper locations and shared-helper context merging before claiming a recovered flow or precision improvement. Model review establishes neither utility nor coverage; leave benefit unmeasured without native comparison evidence.
Distinguish analyzed, limited, skipped, and failed components. Single-function engines are useful but must be labeled limited. Skipped languages, missing extensions, unbound models, parse errors, and empty scans cannot become clean results. A fully skipped run has performed no taint analysis.
在添加模型之前保留一次基线运行,并在之后执行一次增强运行。 验证原生模型语法,并为所选语言和后端使用真实的正向/负向能力 fixture。 所需契约见artifact 处理。 辅助工具负责提取证据和验证 artifacts;它们不实现 taint engine,也不认证模型语义。
在 discovery、版本检查、构建或分析之前检查分析器启动过程:autoloaders、plugins、compiler extensions 和配置 hooks 都可能执行目标代码。 使用可信工具和后端支持的隔离机制;记录明确的 hooks 以及仍然存在的执行假设。静态分析不是沙箱。 在修改源代码或模型之前,必须通过基线验证门禁。 编辑后重新构建上下文,同时保留原始快照;使用新增契约产生的 finding 仍以已记录的假设为条件。
在目标的
.trailmark/taint-trace/
中存储上下文、模型 provenance、原生配置、原生输出和可读报告。 在可用时保留 source 快照以及原生 traces/SARIF。 记录确切的工具版本、命令、有效目标覆盖率、排除项、模型变更和 finding 变更。 不要让捕获的证据进入原生 source/rule discovery,包括会扫描未知扩展名的工具;重复声明可能会在无提示的情况下隐藏 finding。 原生警告数量并不等于唯一数据流数量或覆盖率。 在声称恢复了数据流或提升了精确度之前,检查原生 traces 中是否存在重复的 wrapper 位置和 shared-helper 上下文合并。 模型审查本身既不能证明实用性,也不能证明覆盖率;如果没有原生对比证据,就应将收益标记为未测量。
区分已分析、受限、跳过和失败的组件。单函数引擎可能有用,但必须标记为受限。 跳过的语言、缺失的扩展、未绑定的模型、解析错误和空扫描都不能被视为干净的结果。完全跳过的运行没有执行任何污点分析。

Backend References

后端参考

BackendRead when selected
PsalmPHP docblocks, stubs, and taint flow
PysaPython model files and configuration
Clang Static AnalyzerC/C++ taint configuration
Infer PulseC-family/Java capture and taint policies
JoernNative dataflow queries and custom semantics
Checker FrameworkExisting Java tainting configurations
Semgrep CE/ProTaint rules, language gates, and engine scope
OpenGrepCompatible rules and intrafile analysis
CodeQLNative model packs and query configuration
后端选中后阅读
PsalmPHP docblocks、stubs 和 taint flow
PysaPython 模型文件与配置
Clang Static AnalyzerC/C++ 污点配置
Infer PulseC-family/Java capture 与污点策略
Joern原生数据流查询与自定义 semantics
Checker Framework现有 Java 污点配置
Semgrep CE/Pro污点规则、语言门禁和引擎范围
OpenGrep兼容规则和函数内分析
CodeQL原生模型包与查询配置

Rationalizations to Reject

应拒绝的理由

RationalizationWhy it fails
"Trailmark's tainted subgraph proves the flow"It is call reachability; require a native analyzer finding for a taint claim.
"The helper is named sanitize, so it is safe"Names do not establish context, output handling, or conditional behavior; inspect the implementation.
"The tool parsed the language, so taint works"A frontend can parse while omitting dataflow; require the expected positive and negative fixture outcomes.
"No findings means the project is clean"Missing models, ignored files, tool errors, and limited analysis all produce silence; retain measured coverage and gaps.
"Annotate every argument to connect the graph"Wrong source/sink positions manufacture findings and hide actual contracts; bind the affected value.
"The annotation is correct, so it improves analysis"The analyzer may already understand the body; require a modeling-gap hypothesis and native evidence of benefit.
"More warnings means more coverage"New locations can repeat existing flows or reflect context merging; compare native traces and preserve positive/literal-negative behavior.
"It only asks for the version"Startup can load project hooks before handling the flag; apply the backend's startup controls first.
"Suppress it so the new configuration passes"Suppressions conceal unresolved modeling or application defects; report them instead.
理由失败原因
"Trailmark 的 tainted subgraph 证明了数据流"它仅表示调用可达性;污点声明必须依赖原生分析器 finding。
"辅助工具名为 sanitize,所以它是安全的"名称无法确定上下文、输出处理或条件行为;必须检查实现。
"工具解析了该语言,所以污点分析有效"前端可以完成解析,却遗漏数据流;必须获得预期的正向和负向 fixture 结果。
"没有 finding 就意味着项目是干净的"缺失模型、被忽略的文件、工具错误和受限分析都会产生沉默;必须保留实测覆盖率和缺口。
"标注每个参数以连接图"错误的 source/sink 位置会制造 finding,并隐藏真正的契约;必须绑定受影响的值。
"注解是正确的,所以它能改进分析"分析器可能已经理解函数体;必须提出建模缺口假设,并提供原生收益证据。
"更多警告意味着覆盖率更高"新位置可能重复已有数据流或反映上下文合并;应比较原生 traces,并保持正向及字面负向行为。
"它只会询问版本号"启动过程可能在处理该参数之前加载项目 hooks;应先应用后端的启动控制措施。
"添加 suppression,让新配置通过"Suppressions 会掩盖未解决的建模问题或应用缺陷;应当报告这些问题。