angr.analyses.decompiler.known_patterns.gating

Criteria gates: per-target (and per-function) enablement for pattern templates.

A KnownPatternTemplate carries static applicability filters (arch / language / runtime / platform) and a boolean default_enabled. Many idioms are opt-in because their shape is too generic to ship on every binary: Load(p) == 0 is a list-emptiness test in a kernel module and a null check everywhere else.

A gate is the third channel: it lets an opt-in template say “turn me on when this evidence is present”. Two kinds of evidence are modelled:

  • target evidence (TargetGate): a fact about the binary as a whole, derived once into the PatternContext: this is a Linux kernel module, this is a Windows kernel-mode driver. Cheap, exact, and evaluated before any matching happens.

  • corroboration (CorroboratedBy): another, unambiguous pattern already matched in the same function. This is what converts “too generic to ship” into “safe here”: Load(Load(s)) is meaningless on its own, but in a function where std::string::length (a load at the string’s size offset) or std::string::capacity (the self-referential SSO select) already matched, the object really is a std::string and the load really is front().

Corroboration needs the match results, so it is resolved by KnownPatternFinder in a second matching stage: the finder matches with the ungated set, collects the evidence, re-evaluates the gates that asked for it, and, only if that opens something, matches again with the enlarged set. Gates that do not need evidence are resolved up front.

A gate can only open an opt-in template; it never disables a default-on one.

class angr.analyses.decompiler.known_patterns.gating.GateContext

Bases: object

Everything a gate may look at.

Variables:
  • ctx (PatternContext) – The target’s PatternContext (arch, platform, C++ runtime, and the binary-evidence facts).

  • project (Project | None) – The Project, for gates that need to look past the context.

  • evidence (frozenset[str]) – Names and call names of the patterns established in the function currently being matched: both the patterns that matched in the first stage and the known-pattern calls already present in the graph (outlined by an earlier round). Empty when gates are evaluated outside a function.

ctx: PatternContext
project: Project | None = None
evidence: frozenset[str] = frozenset({})
with_evidence(evidence)
Return type:

GateContext

Parameters:

evidence (Iterable[str])

__init__(ctx, project=None, evidence=frozenset({}))
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.gating.PatternGate

Bases: object

Base class for template gates. Instances are callables so that a gate can be used anywhere a Callable[[GateContext], bool] is expected.

opens(gctx)
Return type:

bool

Parameters:

gctx (GateContext)

property requires_evidence: bool

Whether this gate can only be decided once the function’s matches are known. Such gates are evaluated a second time by the finder.

property label: str
__init__()
Return type:

None

class angr.analyses.decompiler.known_patterns.gating.TargetGate

Bases: PatternGate

Opens when a predicate over the target’s PatternContext holds.

The predicate reads facts that were derived once from the loaded binary, so evaluating it is free and its result is the same for every function.

name: str
predicate: Callable[[PatternContext], bool]
opens(gctx)
Return type:

bool

Parameters:

gctx (GateContext)

property label: str
__init__(name, predicate)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.gating.CorroboratedBy

Bases: PatternGate

Opens in a function where at least one of witnesses already matched.

Witnesses are given as template name or call_name values; the finder puts both spellings of every established pattern into the evidence set.

witnesses: frozenset[str]
opens(gctx)
Return type:

bool

Parameters:

gctx (GateContext)

property requires_evidence: bool

Whether this gate can only be decided once the function’s matches are known. Such gates are evaluated a second time by the finder.

property label: str
__init__(witnesses)
Parameters:

witnesses (frozenset[str])

Return type:

None

class angr.analyses.decompiler.known_patterns.gating.AnyOf

Bases: PatternGate

Opens when any sub-gate opens.

gates: tuple[PatternGate, ...]
opens(gctx)
Return type:

bool

Parameters:

gctx (GateContext)

property requires_evidence: bool

Whether this gate can only be decided once the function’s matches are known. Such gates are evaluated a second time by the finder.

property label: str
__init__(gates=<factory>)
Parameters:

gates (tuple[PatternGate, ...])

Return type:

None

class angr.analyses.decompiler.known_patterns.gating.AllOf

Bases: PatternGate

Opens when every sub-gate opens.

gates: tuple[PatternGate, ...]
opens(gctx)
Return type:

bool

Parameters:

gctx (GateContext)

property requires_evidence: bool

Whether this gate can only be decided once the function’s matches are known. Such gates are evaluated a second time by the finder.

property label: str
__init__(gates=<factory>)
Parameters:

gates (tuple[PatternGate, ...])

Return type:

None

angr.analyses.decompiler.known_patterns.gating.corroborated_by(*witnesses)

A gate that opens in a function where one of witnesses matched.

Return type:

CorroboratedBy

Parameters:

witnesses (str)

class angr.analyses.decompiler.known_patterns.gating.CorroboratedByPattern

Bases: PatternGate

Opens where evidence matching a regex was established.

CorroboratedBy takes a fixed list of witness names, which no longer scales: families are generated per element size, so “any std::vector<T>::size” is five hundred names. This matches the evidence set instead.

regex: str
opens(gctx)
Return type:

bool

Parameters:

gctx (GateContext)

property requires_evidence: bool

Whether this gate can only be decided once the function’s matches are known. Such gates are evaluated a second time by the finder.

property label: str
__init__(regex)
Parameters:

regex (str)

Return type:

None

angr.analyses.decompiler.known_patterns.gating.corroborated_by_pattern(regex)

A gate that opens in a function where evidence matching regex was established.

Return type:

CorroboratedByPattern

Parameters:

regex (str)

angr.analyses.decompiler.known_patterns.gating.any_of(*gates)
Return type:

AnyOf

Parameters:

gates (PatternGate)

angr.analyses.decompiler.known_patterns.gating.all_of(*gates)
Return type:

AllOf

Parameters:

gates (PatternGate)

angr.analyses.decompiler.known_patterns.gating.LINUX_KERNEL = TargetGate(name='linux-kernel-object', predicate=<function <lambda>>)

it carries the module metadata sections, or exports symbols through __ksymtab.

Type:

The binary is a Linux kernel module (or the kernel image itself)

Parameters:

gctx (GateContext)

Return type:

bool

angr.analyses.decompiler.known_patterns.gating.WINDOWS_KERNEL_DRIVER = TargetGate(name='windows-kernel-driver', predicate=<function <lambda>>)

it imports ntoskrnl/hal/a kernel -mode port or miniport library rather than the user-mode Win32 DLLs.

Type:

The binary is a Windows kernel-mode driver

Parameters:

gctx (GateContext)

Return type:

bool

angr.analyses.decompiler.known_patterns.gating.KERNEL_TARGET = AnyOf(gates=(TargetGate(name='linux-kernel-object', predicate=<function <lambda>>), TargetGate(name='windows-kernel-driver', predicate=<function <lambda>>)))

Either of the two kernel targets, the audience for the intrusive doubly-linked-list idioms, which list_head and LIST_ENTRY share.

Parameters:

gctx (GateContext)

Return type:

bool