Skip to Content
Code ScanningRules

Taint Analysis

Write source-to-sink dataflow rules with xgrep's taint mode.

A taint rule (mode: taint) reports when a value flows from a source you do not trust to a sink where it is dangerous, unless it passes through a sanitizer on the way. It catches injection-class bugs that a single pattern cannot, because the source and the sink are usually far apart in the code.

rules:
  - id: user-input-to-shell
    mode: taint
    message: User input reaches a shell command
    severity: ERROR
    languages: [python]
    pattern-sources:
      - pattern: flask.request.args.get(...)
    pattern-sinks:
      - pattern: os.system(...)
    pattern-sanitizers:
      - pattern: shlex.quote(...)

That rule fires on os.system(request.args.get("cmd")) but stays quiet when the value is wrapped in shlex.quote(...) first. A fourth list, pattern-propagators, carries taint through calls that move a value from one place to another (see Propagators).

Each pattern-* list takes the full set of search-mode operators, so a source, sink or sanitizer can be as precise as any other pattern. xgrep's taint mode supports interprocedural and cross-file (interfile: true) tracking; the full feature list is in Writing rules.

Cross-file tracking runs in the cross-file pass. A scan with your own rule pack (-f) turns that pass on when the pack contains an interfile: true rule; a scan of the built-in rules needs --graph. Under --no-graph such a rule still finds flows within a file, and the report warns that its cross-file flows were not looked for. See Cross-file analysis.

Language support

Taint mode needs a dataflow front end for the file's language. Apex, Bash, C, C++, Cairo, Clojure, C#, Dart, Elixir, Go, Hack, Java, JavaScript, TypeScript/TSX, Jsonnet, Julia, Kotlin, Lua, OCaml, Perl, PHP, PowerShell, Python, Ruby, Rust, Scala and Swift have one. A taint rule for any other language (Solidity, for example) loads and its patterns match, but no source is ever connected to a sink, so it cannot report anything there. xgrep says so instead of reporting a clean result:

  • xgrep validate lists each such rule with the languages it cannot evaluate.
  • xgrep scan logs a warning and adds a level: "warning" entry carrying the rule_id to the JSON report's errors, so --strict exits 4 as it does for any other coverage gap.

A rule that lists a supported and an unsupported language still runs where it can; only the unsupported language is reported. generic rules and search-mode rules are not affected.

Elixir taint follows bindings and pattern matches (=, case clauses, with and for generators, map, tuple and list patterns in function heads), pipes, string interpolation, implicit returns, every clause of a multi-clause function, and — under --graph — remote calls across files, resolved through the module path, alias, import and __MODULE__. Bindings are lexically scoped as in the language, so a rebinding inside an if or a case clause does not affect the variable after it. Not modelled: macros and quoted code, processes and message passing, guard-based sanitization, and which clause of a multi-clause function a literal argument selects (taint enters every clause), and the later clauses of a multi-clause fn (a callback's argument reaches its first clause only).

A pipe sink is matched in its pipe form, so write the sink both ways (System.cmd(cmd, args) and cmd |> System.cmd(args)) when both occur.

Dart taint follows declarations and assignments (a compound assignment adds to the variable), positional arguments into parameters, return and => bodies, string interpolation, for-in loop variables, field and index stores (o.f = v, m[k] = v, cascades such as o..f = v) with field sensitivity, collection and buffer mutators (list.add(v), buf.write(v)), callbacks passed to your own functions and to the built-in iterable methods (map, forEach, where, fold, …), closures called directly or through .call, and a field a constructor or method stores in this.f into the other methods of the class. A later assignment kills the earlier value only on every path: reassigning in one branch of an if does not clean the variable after it, and a switch case whose pattern cannot match a constant subject is treated as never running. Under --graph, calls cross files by name, and a call through an import prefix (import 'a.dart' as a; then a.handle(x)) reaches the library the prefix imports. Not modelled: named parameters (a named argument does not reach its parameter), initializing formals (this.f in a constructor's parameter list), a field returned by a getter to its caller, and guard-based sanitization.

Clojure taint follows let, loop, doseq, for and the other binding forms, vector and map destructuring ({:keys […]}, :strs, :syms, {b :k}), arguments into parameters (a & rest parameter collects the later arguments), the last form of a body as its value (through if, when, cond, let and do), fn and #(…) lambdas, callbacks passed to your own functions and to map, filter, reduce, run! and friends, and keyword lookups. Bindings are lexical: a binding inside a let does not affect the name after it. A call runs only the clause of a multi-arity function that its argument count selects (a fixed arity before a variadic one), and when the argument is a map or vector literal, a destructured key, slot or keyword lookup that the literal fills with a constant receives nothing — also when the key is reached through further destructures of a destructured value ((let [{middle :middle} outer, {body :body} middle] …)). Under --graph, a call reaches the namespace that its :require alias, :refer or full qualification names. Not modelled: threading macros (->, ->>), macros and quoted code, a function stored with def (only defn is a function), and :refer :all.

In Clojure patterns, (f $X) is a call of f with one argument, and $X matches any form — a symbol, a literal or a list. A literal head symbol matches that symbol only: (sink ...) does not match (sink-wrapper x).

Propagators

A pattern-propagators entry tells the engine that a call moves taint from one value to another. With from and to, taint on the from binding reaches the to binding:

pattern-propagators:
  - pattern: $DST.addAll($SRC)
    from: $SRC
    to: $DST

An entry with neither from nor to is a receiver-mutation propagator: a call that matches it with a tainted argument taints its receiver, so - pattern: $A.stash($B) taints bag in bag.stash(userInput). This form is an xgrep extension. Semgrep requires from and to, so write them out in a rule that must also run there.

A rule's own propagators take effect for Java, Apex, Python, JavaScript, TypeScript, Go, C#, C, C++, Rust, Swift, Ruby and Cairo. For other taint languages the entry is accepted but moves no taint yet, so a flow through the modelled call is not reported.

Flow finalization (metadata.flow)

Rules can refine their findings per flow — over the source→sink paths the ADR-0229 dataflow engine reconstructs — instead of per matched span. A rule opts in under metadata.flow, whose keys are strictly validated: an unknown key or guard name is a load-time error, so a typo can never silently disable the analysis. The engine-driven pass lives in pkg/dataflowscan (the bridge that imports both pkg/core and pkg/dataflow); core stays free of a pkg/dataflow import.

Guards and filters

metadata:
  flow:
    guards: [allowlist]
    filter: flow.completeGuards.contains("allowlist") == false

For every finding, xgrep reconstructs the source→sink flow, joins the if conditions dominating the sink to the variables actually on that flow's path, and asks each configured guard provider to annotate the conditions it recognises with a verdict. The rule's filter — an MQL expression over the flow resource (sourceLine, sinkLine, sinkVar, steps, guardKinds, completeGuards, incompleteGuards) — then decides whether the flow is a finding. Provider allowlist (java) recognises if (X.contains(tainted)) and reports whether X is a complete (constant-only, non-escaping) allowlist, sharing its classification with the allowlist-analyzer incomplete-sink alerts.

Reporting one finding per flow (report-at)

A check that matches both a weak primitive's construction (MD5.new()) and its consumption (hasher.update(data)) folds the connected pair into one finding:

metadata:
  flow:
    report-at: sink # or: source

sink keeps the consumption, source the construction/binding. This works through intermediate bindings and respects kill boundaries (a use after reassignment is not the same flow). A hit no flow connects keeps its own finding, so a construction whose consumption is out of view still reports.

Cross-rule finding identity (group)

A structural creation rule and a taint usage rule can share a group:

metadata:
  flow:
    group: go-weak-cipher

Within a group, a hit covered by a sibling rule's reported flow (the sibling's dataflow trace records where its flow entered) folds into the sibling's finding at the flow's sink end; where the sibling does not fire, the hit keeps its backstop role.

Safety

  • Per-variable precision. A guard only joins flows whose path contains the variable the condition tests; a second tainted variable sunk in the same guarded block keeps its finding.
  • Fail-open. A flow the engine cannot reconstruct, an unrecognised guard, or a filter error never suppresses a finding — suppression requires positive evidence. The CI gate TestAllFlowFiltersCompileAndExecute compiles and executes every shipped filter so a malformed one fails at author time rather than silently keeping every finding.

Last updated on

On this page