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 thePatternContext: 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 wherestd::string::length(a load at the string’s size offset) orstd::string::capacity(the self-referential SSO select) already matched, the object really is astd::stringand the load really isfront().
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:
objectEverything a gate may look at.
- Variables:
ctx (
PatternContext) – The target’sPatternContext(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
- __init__(ctx, project=None, evidence=frozenset({}))¶
- Parameters:
ctx (PatternContext)
project (Project | None)
- Return type:
None
- class angr.analyses.decompiler.known_patterns.gating.PatternGate¶
Bases:
objectBase 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:
- 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.
- __init__()¶
- Return type:
None
- class angr.analyses.decompiler.known_patterns.gating.TargetGate¶
Bases:
PatternGateOpens when a predicate over the target’s
PatternContextholds.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:
- Parameters:
gctx (GateContext)
- __init__(name, predicate)¶
- Parameters:
name (str)
predicate (Callable[[PatternContext], bool])
- Return type:
None
- class angr.analyses.decompiler.known_patterns.gating.CorroboratedBy¶
Bases:
PatternGateOpens in a function where at least one of
witnessesalready matched.Witnesses are given as template
nameorcall_namevalues; the finder puts both spellings of every established pattern into the evidence set.- opens(gctx)¶
- Return type:
- Parameters:
gctx (GateContext)
- class angr.analyses.decompiler.known_patterns.gating.AnyOf¶
Bases:
PatternGateOpens when any sub-gate opens.
- gates: tuple[PatternGate, ...]
- opens(gctx)¶
- Return type:
- 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.
- __init__(gates=<factory>)¶
- Parameters:
gates (tuple[PatternGate, ...])
- Return type:
None
- class angr.analyses.decompiler.known_patterns.gating.AllOf¶
Bases:
PatternGateOpens when every sub-gate opens.
- gates: tuple[PatternGate, ...]
- opens(gctx)¶
- Return type:
- 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.
- __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
witnessesmatched.- Return type:
- Parameters:
witnesses (str)
- class angr.analyses.decompiler.known_patterns.gating.CorroboratedByPattern¶
Bases:
PatternGateOpens where evidence matching a regex was established.
CorroboratedBytakes 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:
- Parameters:
gctx (GateContext)
- angr.analyses.decompiler.known_patterns.gating.corroborated_by_pattern(regex)¶
A gate that opens in a function where evidence matching
regexwas established.- Return type:
- Parameters:
regex (str)
- angr.analyses.decompiler.known_patterns.gating.any_of(*gates)¶
- Return type:
- Parameters:
gates (PatternGate)
- angr.analyses.decompiler.known_patterns.gating.all_of(*gates)¶
- Return type:
- 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:
- 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:
- 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_headandLIST_ENTRYshare.- Parameters:
gctx (GateContext)
- Return type: