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 validatelists each such rule with the languages it cannot evaluate.xgrep scanlogs a warning and adds alevel: "warning"entry carrying therule_idto the JSON report'serrors, so--strictexits 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: $DSTAn 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") == falseFor 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: sourcesink 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-cipherWithin 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
TestAllFlowFiltersCompileAndExecutecompiles and executes every shipped filter so a malformed one fails at author time rather than silently keeping every finding.
Last updated on