SkillAgentSearch skills...

taint-trace

Improves taint-analysis coverage and precision by using Trailmark graphs to repair native source, sink, sanitizer, propagation, and type models, then runs an existing taint analyzer

Install / Use

npx skills add trailofbits/skills --skill taint-trace

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Category

Legal

Supported Platforms

Universal

Tags

Our assessment of taint-trace

taint-trace scores 89/100 on our quality scale, 62nd of 209 Legal skills we index (top 30%).

Its SKILL.md is 9.4 KB long, split into 7 sections with 1 code example: a thorough specification that gives an agent plenty to work with.

With 7,225 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
15/20
Description
15/15
Adoption
16/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so taint-trace is actively maintained.
  • It is released under the CC-BY-SA-4.0 license; check its terms before commercial use.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-16. Automated pattern scan on 2026-11-16. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

taint-trace compared with similar skills

All 4 of these similar skills score higher than taint-trace; compare them before choosing.

SkillScoreStarsUpdatedFormat
taint-trace (this skill)by trailofbits897.2k54d agoSKILL.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md
designby nextlevelbuilder100149.0k6d agoSKILL.md

Frequently asked questions

How do I install taint-trace?
Run npx skills add trailofbits/skills --skill taint-trace. The install tabs above show the steps for each supported agent.
Which AI agents does taint-trace work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is taint-trace safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is CC-BY-SA-4.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is taint-trace still maintained?
The repository was last updated about 2 months ago, so taint-trace is actively maintained.

name: taint-trace description: "Improves taint-analysis coverage and precision by using Trailmark graphs to repair native source, sink, sanitizer, propagation, and type models, then runs an existing taint analyzer. Use when analysis misses flows, cannot resolve framework bindings, or produces false positives from imprecise models." allowed-tools: Read Grep Glob Bash Edit Write

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 skill_dir: "{baseDir}" so its trusted helper/reference location is explicit, including checkout installs.

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.

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.

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 .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.

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. |

Related Skills

View on GitHub
GitHub Stars7.2k
CategoryLegal
Updated1mo ago
Forks615

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions