Skip to content
New

DeepSeek V4.1 Flash free for 7 days: 10M tokens a day after a top-up of $10 or more. Until Nov 30.

How it works
trailofbits/taint-traceWeb and bug bounty

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. Use when analysis misses flows, cannot resolve framework bindings, or produces false positives from imprecise models.⁩

v2026.11.12-149d7b22 installs+2 in 7 days8.2K StarsCC-BY-SA-4.0synced 22 hours ago

Install

No NotHoly CLI yet? Install it first.

$ curl -fsSL https://notholy.com/install.sh | sh
$ notholy skills install trailofbits/taint-trace

Writes to ⁦~/.notholy/skills⁩ after checking the signature and the SHA-256.

SignatureSigned, ed25519
BeMuNPOFC+…uzQhwRAg==The CLI checks the SHA-256 and the signature before it writes a file.
Package9771c364…92397f76
9771c364eda3…bbd892397f7649 files · ⁦108.2 KB⁩
ScanMedium39 findings
  • injection.no_confirmationSKILL.md:110
  • injection.no_confirmationreferences/catalog.md:9
  • injection.no_confirmationreferences/clang.md:14
See the full scan
Sourcegithub.com/trailofbits/skills/tree/main/plugins/trailmark/skills/taint-trace@149d7b2

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

Files in this version

Permissions

PermissionDeclaredFound by the scan
Reads filesYesYes
Writes filesYesYes
Runs shell commandsYesYes
Uses the networkYesYes
Uses connectorsNoNo
Drives a browserNoNo

Scan findings

Reviewed on Nov 13, 2026

  1. MediumPrompt injection · injection.no_confirmationSKILL.md:110
  2. MediumPrompt injection · injection.no_confirmationreferences/catalog.md:9
  3. MediumPrompt injection · injection.no_confirmationreferences/clang.md:14
  4. MediumPrompt injection · injection.no_confirmationreferences/joern.md:105
  5. MediumPrompt injection · injection.no_confirmationreferences/model-quality.md:90
  6. MediumFile · Executable script shipped with the skillscripts/activation.py
  7. MediumFile · Executable script shipped with the skillscripts/catalog.py
  8. MediumFile · Executable script shipped with the skillscripts/contracts.py
  9. MediumFile · Executable script shipped with the skillscripts/finding_comparison.py
  10. MediumFile · Executable script shipped with the skillscripts/graph_context.py
  11. MediumFile · Executable script shipped with the skillscripts/joern_fixture.py
  12. MediumPrompt injection · injection.no_confirmationscripts/joern_fixture.py:235
  13. MediumFile · Executable script shipped with the skillscripts/manifest_validation.py
  14. MediumFile · Executable script shipped with the skillscripts/native.py
  15. MediumFile · Executable script shipped with the skillscripts/psalm_feature_probes.py
  16. MediumFile · Executable script shipped with the skillscripts/psalm_features.py
  17. MediumFile · Executable script shipped with the skillscripts/psalm_version.py
  18. MediumFile · Executable script shipped with the skillscripts/runner.py
  19. MediumFile · Executable script shipped with the skillscripts/runner_artifacts.py
  20. MediumFile · Executable script shipped with the skillscripts/runner_config.py
  21. MediumFile · Executable script shipped with the skillscripts/runner_contracts.py
  22. MediumFile · Executable script shipped with the skillscripts/runner_probe.py
  23. MediumFile · Executable script shipped with the skillscripts/runner_startup.py
  24. MediumFile · Executable script shipped with the skillscripts/taint_trace.py
  25. MediumFile · Executable script shipped with the skillscripts/taint_trace.sh
  26. MediumFile · Executable script shipped with the skillscripts/test_activation.py
  27. MediumFile · Executable script shipped with the skillscripts/test_graph.py
  28. MediumFile · Executable script shipped with the skillscripts/test_joern.py
  29. MediumFile · Executable script shipped with the skillscripts/test_native.py
  30. MediumFile · Executable script shipped with the skillscripts/test_precision.py
  31. MediumFile · Executable script shipped with the skillscripts/test_psalm_compat.py
  32. MediumFile · Executable script shipped with the skillscripts/test_psalm_features.py
  33. MediumFile · Executable script shipped with the skillscripts/test_report.py
  34. MediumFile · Executable script shipped with the skillscripts/test_runner.py
  35. MediumFile · Executable script shipped with the skillscripts/test_style.py
  36. MediumFile · Executable script shipped with the skillscripts/test_taint_trace.py
  37. MediumFile · Executable script shipped with the skillscripts/trace_artifacts.py
  38. MediumFile · Executable script shipped with the skillscripts/trace_report.py
  39. InfoLink · Links to outside domains

A clean scan lowers the risk but does not prove a package is safe. Read what you install.

VersionPublishedCommitSHA-256SignaturePermission change
v2026.11.12-149d7b2Nov 13, 2026149d7b29771c364Signed–

Ask anything your scope allows.

Create an account, add credits and ask the first question in the chat or the terminal.

  1. 1/3

    Create the account

    Individual or company. You can switch to a company later without losing balance or keys.

    IndividualCompany
  2. 2/3

    Add credits

    By card. Pay per token, no subscription.

    $5.00minimum deposit
  3. 3/3

    Ask

    In the chat, or install the CLI and run notholy login in your terminal.

    $ notholy login