taint-trace
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTaint 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 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
so its trusted helper/reference location is explicit, including checkout installs.
/trailmark:taint-trace-runskill_dir: "{baseDir}"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.jsonRead 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 , using from the
package index. Native analyzers are separate dependencies.
uvtrailmark>=0.8.0,<0.9使用目标目录调用 。可选参数用于选择语言、后端覆盖项和 sink 关注点。动态工作流负责分阶段执行;此处定义的契约也适用于直接执行此 skill 的主机。
从已加载的 skill 调用工作流时,传入 ,以明确指定可信辅助工具和参考目录的位置,包括从 checkout 安装的情况。
/trailmark:taint-trace-runskill_dir: "{baseDir}"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 等版本特定机制,应检查探测结果中针对各项功能的能力结果,并且只使用已经证明可行的机制。
启动器通过 运行辅助工具,并从包索引中安装 。原生分析器是需要单独安装的依赖项。
uvtrailmark>=0.8.0,<0.9Required Graph Evidence
必需的图证据
The helper directly checks , ,
, 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.
entrypoint_evidence()entrypoint_candidates()source_policy()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.
辅助工具会直接检查 、、、攻击面、诊断信息和遍历 API。即使已有发行版依赖,也必须保留这些能力检查。
阅读图证据,了解绑定和快照契约。
不兼容的安装属于设置失败,不能用 LLM 的可达性猜测来替代。
entrypoint_evidence()entrypoint_candidates()source_policy()检查危险 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 . 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.
.trailmark/taint-trace/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 仍以已记录的假设为条件。
在目标的 中存储上下文、模型 provenance、原生配置、原生输出和可读报告。
在可用时保留 source 快照以及原生 traces/SARIF。
记录确切的工具版本、命令、有效目标覆盖率、排除项、模型变更和 finding 变更。
不要让捕获的证据进入原生 source/rule discovery,包括会扫描未知扩展名的工具;重复声明可能会在无提示的情况下隐藏 finding。
原生警告数量并不等于唯一数据流数量或覆盖率。
在声称恢复了数据流或提升了精确度之前,检查原生 traces 中是否存在重复的 wrapper 位置和 shared-helper 上下文合并。
模型审查本身既不能证明实用性,也不能证明覆盖率;如果没有原生对比证据,就应将收益标记为未测量。
.trailmark/taint-trace/区分已分析、受限、跳过和失败的组件。单函数引擎可能有用,但必须标记为受限。
跳过的语言、缺失的扩展、未绑定的模型、解析错误和空扫描都不能被视为干净的结果。完全跳过的运行没有执行任何污点分析。
Backend References
后端参考
| Backend | Read when selected |
|---|---|
| Psalm | PHP docblocks, stubs, and taint flow |
| Pysa | Python model files and configuration |
| Clang Static Analyzer | C/C++ taint configuration |
| Infer Pulse | C-family/Java capture and taint policies |
| Joern | Native dataflow queries and custom semantics |
| Checker Framework | Existing Java tainting configurations |
| Semgrep CE/Pro | Taint rules, language gates, and engine scope |
| OpenGrep | Compatible rules and intrafile analysis |
| CodeQL | Native model packs and query configuration |
| 后端 | 选中后阅读 |
|---|---|
| Psalm | PHP docblocks、stubs 和 taint flow |
| Pysa | Python 模型文件与配置 |
| Clang Static Analyzer | C/C++ 污点配置 |
| Infer Pulse | C-family/Java capture 与污点策略 |
| Joern | 原生数据流查询与自定义 semantics |
| Checker Framework | 现有 Java 污点配置 |
| Semgrep CE/Pro | 污点规则、语言门禁和引擎范围 |
| OpenGrep | 兼容规则和函数内分析 |
| CodeQL | 原生模型包与查询配置 |
Rationalizations to Reject
应拒绝的理由
| Rationalization | Why 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 会掩盖未解决的建模问题或应用缺陷;应当报告这些问题。 |