angr.analyses.decompiler.known_patterns.pattern

KnownPattern: declarative metadata around a pattern-AST.

A KnownPattern couples a structural pattern (see dsl) with the information needed to turn a match into a synthesized call: the call name, the ordered parameters (mapping captures to call arguments and types), the return type, and applicability guards.

class angr.analyses.decompiler.known_patterns.pattern.CppRef

Bases: object

A reference to a C++ class type registered in the cpp::std SimTypeCollection, keyed by its unique (mangled-style) name.

unique_name: str
ptr: bool = True
resolve(arch)
Return type:

SimType | None

Parameters:

arch (archinfo.Arch)

__init__(unique_name, ptr=True)
Parameters:
Return type:

None

angr.analyses.decompiler.known_patterns.pattern.resolve_typeref(ref, arch)

Resolve a TypeRef into a SimType: a C declaration string is parsed with parse_type; a CppRef is looked up in the cpp::std collection.

Return type:

SimType | None

Parameters:
class angr.analyses.decompiler.known_patterns.pattern.PatternParam

Bases: object

One parameter of the synthesized call.

Variables:

  • capture (str) – Name of the pattern capture bound to this parameter.

  • type (str | CppRef | None) – Argument type for the synthesized call’s prototype; flows into Typehoon as a per-argument subtype constraint.

  • type_hint – Optional cpp::std unique name emitted as a direct vvar type hint (for by-value captures where the vvar is the object rather than a pointer to it).

capture: str
type: str | CppRef | None = None
type_hint: str | None = None
__init__(capture, type=None, type_hint=None)
Parameters:
Return type:

None

class angr.analyses.decompiler.known_patterns.pattern.KnownPattern

Bases: object

A known code idiom, described declaratively.

Variables:

  • name (str) – Identifier, e.g. "std_string_length".

  • display_name (str) – Human-readable name, e.g. "std::string::length".

  • call_name (str) – Target name of the synthesized Call.

  • pattern (PatternExpr | PatternStmt | PGraphPat) – The structural pattern to match.

  • params (tuple[PatternParam, ...]) – Ordered parameters; their captures become the call arguments, in order.

  • returnty (str | CppRef | None) – Return type of the synthesized call.

  • returnty_factory (Callable[[Arch, dict[str, int]], SimType | None] | None) – Optional callable building a call-site-specific return type from the values of the constant extra_args captures (e.g. CONTAINING_RECORD returns a pointer to a record whose layout depends on the matched field offset). Falls back to returnty when it returns None or when the constant values are unavailable.

  • extra_args (tuple[str, ...]) – Names of (typically constant) captures appended to the call arguments after params.

  • arches (tuple[str, ...] | None) – Allowed archinfo.Arch.name values; None = any.

  • platforms (tuple[str, ...] | None) – Allowed OS names (project.simos.name, lowercased); None = any.

  • where (Callable[[dict[str, Expression]], bool] | None) – Optional cross-capture predicate evaluated on the bindings after a structural match.

  • collapse_capture (str | None) – Optional capture name identifying the idiom that a match belongs to: within one function, matches binding it to the same virtual variable all describe one source-level idiom, and only the one with the largest collapse_max_capture constant is kept. The compiler folds CONTAINING_RECORD’s subtraction into every field displacement, so one source idiom otherwise emits a call per field, each naming a different (and mostly wrong) record base.

  • collapse_max_capture (str | None) – Capture whose constant value orders the collapsing; required when collapse_capture is set.

  • binary_guard (Callable[[Project], bool] | None) – Optional predicate on the Project; the pattern is only used when it returns True (e.g. require C++ evidence for STL patterns to avoid false positives on plain C binaries).

  • default_enabled (bool) – Whether the pattern is used when the caller does not explicitly select patterns. Generic patterns prone to false positives should set this False.

name: str
display_name: str
call_name: str
pattern: PatternExpr | PatternStmt | PGraphPat
params: tuple[PatternParam, ...]
returnty: str | CppRef | None = None
returnty_factory: Callable[[Arch, dict[str, int]], SimType | None] | None = None
extra_args: tuple[str, ...] = ()
arches: tuple[str, ...] | None = None
platforms: tuple[str, ...] | None = None
where: Callable[[dict[str, Expression]], bool] | None = None
collapse_capture: str | None = None
collapse_max_capture: str | None = None
binary_guard: Callable[[Project], bool] | None = None
default_enabled: bool = True
suppressed_by: tuple[str, str, str] | None = None

Drop a match of this pattern when a pattern whose name matches the regex matched on the same object: (name regex, my capture, their capture). The two captures must bind .likes()-equal expressions. This is how a generic accessor yields to a specific one on the same base: a bare Load(s + 8) is std::string::length on a string and _M_finish on a vector, and the vector’s other fields say which. Judged against every match of the suppressing family, selected or not, so it cannot interact with largest-match selection.

claims_only: bool = False

Match only to claim a base for suppressed_by purposes; never outlined, never rewritten, never reported. For shapes that identify an object beyond doubt but are not worth naming: a vector’s capacity check says “this is a vector” and nothing a reader wants a call for.

pure_calls: frozenset[str] = frozenset({})

Callees this pattern reads through PCallResult whose only effect is their result: once the pattern has consumed that result and nothing else does, the call goes too. Naming a callee in a pattern is already a claim about what it computes; this is the claim that it computes nothing else. __ctype_b_loc returns a table pointer, and a bare __ctype_b_loc(); left behind after isspace(c) is noise.

applicable(arch_name, platform)
Return type:

bool

Parameters:

  • arch_name (str)

  • platform (str | None)

const_args_of_call(call)

Recover the extra_args constant values from a synthesized call’s trailing arguments. Returns None when the call does not carry them.

Return type:

dict[str, int] | None

Parameters:

call (Call)

prototype(arch, const_args=None)

Build the synthesized call’s prototype. const_args (the values of the constant extra_args captures, see const_args_of_call()) enables call-site-specific return types via returnty_factory. Returns None if any declared type fails to resolve.

Return type:

SimTypeFunction | None

Parameters:
__init__(name, display_name, call_name, pattern, params, returnty=None, returnty_factory=None, extra_args=(), arches=None, platforms=None, where=None, collapse_capture=None, collapse_max_capture=None, binary_guard=None, default_enabled=True, suppressed_by=None, claims_only=False, pure_calls=frozenset({}))
Parameters:
Return type:

None