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.
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
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
, using
from the
package index. Native analyzers are separate dependencies.
Required 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.
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.
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.
Native Execution and 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.
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.
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 |
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. |