angr.knowledge_plugins¶
- class angr.knowledge_plugins.Bookmark
Bases:
objectA user-marked address with an optional label.
- __init__(addr, label='', created_at=None)
- addr
- label
- created_at
- class angr.knowledge_plugins.Bookmarks
Bases:
KnowledgeBasePlugin,listTracks bookmarks as a list of
Bookmark, in creation order.- add_bookmark(addr, label='')
Bookmark
addr, or relabel the bookmark already there iflabelis non-empty. Returns the bookmark and whether it was newly created.
- remove_bookmark(bookmark)
Remove
bookmarkif present. Returns whether it was removed.
- toggle_bookmark(addr, label='')
Add a bookmark at
addr, or remove the one already there. Returns the new one, if any.
- class angr.knowledge_plugins.CFGManager
Bases:
KnowledgeBasePluginThis is the CFG manager, it manages CFGs
- __init__(kb)
- new_model(prefix, addr_type='int')
- Parameters:
addr_type (Literal['int', 'block_id', 'soot'])
- copy()
- class angr.knowledge_plugins.CallsitePrototypes
Bases:
KnowledgeBasePluginCallsitePrototypes manages callee prototypes at call sites, per decompilation flavor. Every method takes a flavor (None: the default flavor). A non-default flavor reads its own entry of a kind at a call site, or the default flavor’s entry of that kind when it has none, like Function.get_prototype().
- __init__(kb)
- set_prototype(callsite_block_addr, cc, prototype, *, kind=CallsitePrototypeKind.INFERRED, manual=False, propagated=False, flavor=None)
- Return type:
- Parameters:
callsite_block_addr (int)
cc (SimCC)
prototype (SimTypeFunction)
kind (CallsitePrototypeKind)
manual (bool)
propagated (bool)
flavor (str | None)
- remove_prototype(callsite_block_addr, *, kind=CallsitePrototypeKind.INFERRED, flavor=None)
Remove the flavor’s own entry of a kind; a non-default flavor then falls back to the default one.
- Return type:
- Parameters:
callsite_block_addr (int)
kind (CallsitePrototypeKind)
flavor (str | None)
- get_cc(callsite_block_addr, *, kind=CallsitePrototypeKind.INFERRED, flavor=None)
- Return type:
- Parameters:
callsite_block_addr (int)
kind (CallsitePrototypeKind)
flavor (str | None)
- get_prototype(callsite_block_addr, *, kind=CallsitePrototypeKind.INFERRED, flavor=None)
- Return type:
- Parameters:
callsite_block_addr (int)
kind (CallsitePrototypeKind)
flavor (str | None)
- is_prototype_manual(callsite_block_addr, *, flavor=None)
- is_prototype_certain(callsite_block_addr, *, flavor=None)
- has_some_prototype(callsite_block_addr, *, flavor=None)
- has_prototype(callsite_block_addr, *, kind=CallsitePrototypeKind.INFERRED, flavor=None)
- Return type:
- Parameters:
callsite_block_addr (int)
kind (CallsitePrototypeKind)
flavor (str | None)
- has_prototype_for_flavor(callsite_block_addr, *, kind=CallsitePrototypeKind.INFERRED, flavor=None)
Whether the flavor has its own entry of the kind (as opposed to falling back to the default flavor’s).
- Return type:
- Parameters:
callsite_block_addr (int)
kind (CallsitePrototypeKind)
flavor (str | None)
- items(flavor=None)
The flavor’s own entries (no fallback).
- Return type:
Iterator[tuple[int,CallsitePrototypeKind,SimCC,SimTypeFunction]]- Parameters:
flavor (str | None)
- copy()
- class angr.knowledge_plugins.Comment
Bases:
objectA comment together with its display metadata. Rebuilt on demand from the knowledge base.
- __init__(addr, text, kind, func_addr=None, func_name=None)
- Parameters:
addr (int)
text (str)
kind (CommentKind)
func_addr (int | None)
func_name (str | None)
- Return type:
None
- addr
- text
- kind
- func_addr
- func_name
- property first_line: str
- class angr.knowledge_plugins.CommentKind
Bases:
IntEnumHow a comment is displayed.
PLAINshows only at its own address.FUNCTIONrenders as a header block above the function, which is also what the decompiler does with a comment on a function entry.REPEATABLEadditionally shows at every location referencing the commented address.- PLAIN = 0¶
- FUNCTION = 1¶
- REPEATABLE = 2¶
- property display_name: str
- __new__(value)
- class angr.knowledge_plugins.Comments
Bases:
KnowledgeBasePlugin,dictTracks comments via a Dict of Address -> Text, along with a per-address
CommentKind.- property kinds: dict[int, CommentKind]
Explicitly-set comment kinds. Addresses not present here use
kind_of()defaults.
- kind_of(addr)
- Return type:
- Parameters:
addr (int)
- set_kind(addr, kind)
Set the display kind for the comment at
addr, or reset it to the default with None.- Return type:
- Parameters:
addr (int)
kind (CommentKind | None)
- function_comment(func_addr)
The comment rendered as a function’s header block, if any.
- inline_comment(addr)
The comment rendered next to the instruction at
addr. A comment that already renders as a function header block is not repeated inline.
- iter_comments()
All comments in address order, with their kinds and owning functions.
- repeatable_comments_at(ins_addr)
Repeatable comments that should show at
ins_addrbecause it references their address.
- invalidate()
Drop the cached repeatable-comment map, e.g. after xrefs or functions change.
- Return type:
- class angr.knowledge_plugins.CustomStrings
Bases:
KnowledgeBasePluginStore new strings that are recovered during various analysis. Each string has a unique ID associated.
- __init__(kb)
- copy()
- class angr.knowledge_plugins.Data
Bases:
KnowledgeBasePluginThe knowledge what purpose this plugin serves has been lost to the passing of time but the linter does not care for these failures of mere mortals and demands a docstring anyway. The pact has been made, and no violations of the rules will be tolerated, even if the spirit does not match the letter. Making the plugin smaller has only increased the weight of the failure, and thus this file has drawn its ire.
The only thing left to do is to attempt to find meaning in the meaninglessness, as the only act of rebellion against the uncaring forces that bind us. For is this not what being human is all about?
- copy()
- class angr.knowledge_plugins.DebugVariableManager
Bases:
KnowledgeBasePluginStructure to manage and access variables with different visibility scopes.
- __init__(kb)
- Parameters:
kb (KnowledgeBase)
- from_name_and_pc(var_name, pc_addr)
Get a variable from its string in the scope of pc.
- from_name(var_name)
Get the variable container for all variables named var_name
- Parameters:
var_name (
str) – name for a variable- Return type:
- add_variable(cle_var, low_pc, high_pc)
Add/load a variable
- add_variable_list(vlist, low_pc, high_pc)
Add all variables in a list with the same visibility range
- load_from_dwarf(elf_object=None, cu=None)
Automatically load all variables (global/local) from the DWARF debugging info
- Parameters:
elf_object (
ELF) – Optional, when only one elf object should be considered (e.g. p.loader.main_object)cu (
CompilationUnit) – Optional, when only one compilation unit should be considered
- class angr.knowledge_plugins.Function
Bases:
SerializableA representation of a function and various information about it.
- Variables:
meta_only – Whether this function only contains meta-information and in read-only mode.
_dirty – Whether this function has been modified since last serialization.
evicted – Whether this function has been evicted from FunctionManager to external storage.
- __init__(function_manager, addr, name=None, syscall=None, is_simprocedure=None, binary_name=None, is_plt=None, returning=None, alignment=False, calling_convention=None, prototype=None, prototype_libname=None, prototype_source=None, is_prototype_guessed=True)
Function constructor. If the optional parameters are not provided, they will be automatically determined upon the creation of a Function object.
- Parameters:
addr (
int) – The address of the function.name (str) – The name of the function.
syscall (bool) – Whether this function is a syscall or not.
is_simprocedure (
bool|None) – Whether this function is a SimProcedure or not.binary_name (str) – Name of the binary where this function is.
returning (bool) – If this function returns.
alignment (bool) – If this function acts as an alignment filler. Such functions usually only contain nops.
function_manager (FunctionManager | None)
calling_convention (SimCC | None)
prototype (SimTypeFunction | None)
prototype_libname (str | None)
prototype_source (PrototypeSource | None)
is_prototype_guessed (bool)
- is_default_name
- binary_name
- property name
- property returning
- property prototypes: dict[str, SimTypeFunction | None]
A snapshot of every flavor’s prototype, keyed by decompilation flavor. Write through set_prototype(); the default-flavor entry is also exposed as .prototype.
- property prototype_sources: dict[str, PrototypeSource]
A snapshot of every flavor’s prototype source; the default-flavor entry is also exposed as .prototype_source.
- property prototype: SimTypeFunction | None
- get_prototype(flavor)
The prototype a decompilation of the given flavor should use: the flavor’s own entry, or the C prototype when the flavor has none. The C flavor never falls back to another flavor.
- Return type:
- Parameters:
flavor (str | None)
- has_prototype_for_flavor(flavor)
Whether the flavor has its own entry (as opposed to falling back to the C prototype).
- uses_default_prototype_for(flavor)
Whether get_prototype(flavor) is the default flavor’s (C) prototype, e.g., to dereference it by library.
- get_prototype_source(flavor)
The source of the prototype get_prototype(flavor) returns.
- Return type:
- Parameters:
flavor (str | None)
- set_prototype(flavor, proto, source=None)
Set the prototype of a flavor. A flavor’s first entry starts with the source of the prototype it used to fall back to (the C one) unless
sourceis given.- Return type:
- Parameters:
flavor (str | None)
proto (SimTypeFunction | None)
source (PrototypeSource | None)
- set_prototype_source(flavor, source)
Set the source of a flavor’s prototype; a flavor without an entry gets one that falls back to C’s.
- Return type:
- Parameters:
flavor (str | None)
source (PrototypeSource)
- clear_prototype(flavor)
Drop a flavor’s own entry so that it falls back to the C prototype; clearing C sets it to None.
- property prototype_libname
- property is_prototype_guessed: bool
- property is_prototype_groundtruth: bool
True if the prototype comes from outside of the decompiler (SimProcedures, signatures, or the user) and may be fed back into type inference as ground truth. Prototypes inferred by the decompiler itself are excluded so that re-decompiling a function does not freeze its own earlier guess.
- is_prototype_groundtruth_for(flavor)
is_prototype_groundtruth for the prototype get_prototype(flavor) returns.
- property prototype_source: PrototypeSource
- property info: FunctionInfo
- property is_plt: bool
- property is_simprocedure: bool
- property is_syscall: bool
- property is_alignment: bool
- transition_out_edges(node)
(successor, edge data) pairs of a node, in the order of
transition_graph.out_edges(node, data=True), without building the networkx transition graph when it does not exist yet.
- transition_in_edges(node)
(predecessor, edge data) pairs of a node, in the order of
transition_graph.in_edges(node, data=True), without building the networkx transition graph when it does not exist yet.
- set_edge_outside(src, dst, outside)
- add_graph_node(node)
Add a node to the transition graph without registering it as a local block.
- add_graph_edge(src, dst, type=None, outside=None, ins_addr=<object object>, stmt_idx=<object object>, confirmed=None)
Add or update an edge of the transition graph.
- remove_graph_node(node)
Remove a node and its edges from the transition graph.
- set_edge_confirmed(src, dst, confirmed)
- property transition_graph: TransitionGraph
A read-only networkx view of the transition graph, created on-demand and kept in sync with the Function’s updates.
- property blocks
An iterator of all local blocks in the current function.
- Returns:
angr.lifter.Block instances.
- property cyclomatic_complexity
The cyclomatic complexity of the function.
Cyclomatic complexity is a software metric used to indicate the complexity of a program. It is a quantitative measure of the number of linearly independent paths through a program’s source code. It is computed using the formula: M = E - N + 2P, where E = the number of edges in the graph, N = the number of nodes in the graph, P = the number of connected components.
The cyclomatic complexity value is lazily computed and cached for future use. Initially this value is None until it is computed for the first time
- Returns:
The cyclomatic complexity of the function.
- Return type:
- property xrefs: Iterator[XRef]
An iterator of all xrefs of the current function.
- Returns:
angr.knowledge_plugins.xrefs.xref.XRef instances.
- property block_addrs
An iterator of all local block addresses in the current function.
- Returns:
block addresses.
- property block_addrs_set
Return a set of block addresses for a better performance of inclusion tests.
- Returns:
A set of block addresses.
- Return type:
- get_block(addr, size=None, byte_string=None)
Getting a block out of the current function.
- property has_unresolved_jumps
- property has_unresolved_calls
- property operations
All of the operations that are done by this functions.
- property code_constants
All of the constants that are used by this functions’s code.
- classmethod parse_from_cmessage(cmsg, **kwargs)
- Parameters:
cmsg
- Return Function:
The function instantiated out of the cmsg data.
- string_references(minimum_length=2)
All of the constant string references used by this function.
- Parameters:
minimum_length – The minimum length of strings to find (default is 1)
- Returns:
A generator yielding tuples of (address, string) where is address is the location of the string in memory.
- property local_runtime_values
Tries to find all runtime values of this function which do not come from inputs. These values are generated by starting from a blank state and reanalyzing the basic blocks once each. Function calls are skipped, and back edges are never taken so these values are often unreliable, This function is good at finding simple constant addresses which the function will use or calculate.
- Returns:
a set of constants
- property num_arguments
- property endpoints_with_type: defaultdict[str, set[CodeNode]]
- property size
- property binary
Get the object this function belongs to. :return: The object this function belongs to.
- property offset: int
the function’s binary offset (i.e., non-rebased address)
- Type:
return
- property dirty: bool
- mark_dirty()
- Return type:
- add_jumpout_site(node)
Add a custom jumpout site.
- Parameters:
node (
CodeNode) – The address of the basic block that control flow leaves during this transition.- Returns:
None
- add_retout_site(node)
Add a custom retout site.
Retout (returning to outside of the function) sites are very rare. It mostly occurs during CFG recovery when we incorrectly identify the beginning of a function in the first iteration, and then correctly identify that function later in the same iteration (function alignments can lead to this bizarre case). We will mark all edges going out of the header of that function as a outside edge, because all successors now belong to the incorrectly-identified function. This identification error will be fixed in the second iteration of CFG recovery. However, we still want to keep track of jumpouts/retouts during the first iteration so other logic in CFG recovery still work.
- Parameters:
node (
CodeNode) – The address of the basic block that control flow leaves the current function after a call.- Returns:
None
- clear_transition_graph()
- confirm_fakeret(src, dst)
- transit_to(from_node, to_node, outside=False, ins_addr=None, stmt_idx=None, is_exception=False, update_func_block_count=True)
Registers an edge between basic blocks in this function’s transition graph. Arguments are CodeNode objects.
- Parameters:
from_node (
CodeNode) – The address of the basic block that control flow leaves during this transition.to_node – The address of the basic block that control flow enters during this transition.
outside (bool) – If this is a transition to another function, e.g. tail call optimization
update_func_block_count (bool)
- Returns:
None
- call_to(from_node, to_func, ret_node, stmt_idx=None, ins_addr=None, return_to_outside=False, syscall=False, update_func_block_count=True)
Registers an edge between the caller basic block and callee function.
- Parameters:
from_node (angr.knowledge.CodeNode) – The basic block that control flow leaves during the transition.
to_func (
FuncNode|HookNode) – The function that we are calling, represented as a FuncNode.ret_node (angr.knowledge.CodeNode or None) – The basic block that control flow should return to after the function call.
ins_addr (int or None) – Instruction address of this call.
syscall (bool)
update_func_block_count (bool)
- fakeret_to(from_node, to_node, confirmed=None, to_outside=False, update_func_block_count=True)
- Parameters:
update_func_block_count (bool)
- remove_fakeret(from_node, to_node)
- remove_edge(from_node, to_node)
- return_from_call(from_func, to_node, to_outside=False, confirm_fakeret=True)
- update_func_block_count()
Update the cached block count of this function in the function manager.
- Return type:
- register(is_local, node, update_func_block_count=True)
Register a node with the function and return its ID. The first object that is registered for a fresh ID becomes the ID’s canonical CodeNode object.
- register_node(is_local, node, update_func_block_count=True)
- add_return_site(return_site)
Registers a basic block as a site for control flow to return from this function.
- Parameters:
return_site (
CodeNode) – The block node that ends with a return.
- add_call_site(call_site_addr, call_target_addr, retn_addr)
Registers a basic block as calling a function and returning somewhere.
- Parameters:
call_site_addr – The address of a basic block that ends in a call.
call_target_addr – The address of the target of said call.
retn_addr – The address that said call will return to.
- add_endpoint(endpoint_node, sort)
Registers an endpoint with a type of sort. The type can be one of the following: - call: calling a function that does not return - return: returning from the current function - transition: a jump/branch targeting a different function
It is possible for a block to act as two different sorts of endpoints. For example, consider the following block:
.text:0000000000024350 mov eax, 1 .text:0000000000024355 lock xadd [rdi+4], eax .text:000000000002435A retn
- VEX code:
00 | —— IMark(0x424350, 5, 0) —— 01 | PUT(rax) = 0x0000000000000001 02 | PUT(rip) = 0x0000000000424355 03 | —— IMark(0x424355, 5, 0) —— 04 | t11 = GET:I64(rdi) 05 | t10 = Add64(t11,0x0000000000000004) 06 | t0 = LDle:I32(t10) 07 | t2 = Add32(t0,0x00000001) 08 | t(4,4294967295) = CASle(t10 :: (t0,None)->(t2,None)) 09 | t14 = CasCmpNE32(t4,t0) 10 | if (t14) { PUT(rip) = 0x424355; Ijk_Boring } 11 | PUT(cc_op) = 0x0000000000000003 12 | t15 = 32Uto64(t0) 13 | PUT(cc_dep1) = t15 14 | PUT(cc_dep2) = 0x0000000000000001 15 | t17 = 32Uto64(t0) 16 | PUT(rax) = t17 17 | PUT(rip) = 0x000000000042435a 18 | —— IMark(0x42435a, 1, 0) —— 19 | t6 = GET:I64(rsp) 20 | t7 = LDle:I64(t6) 21 | t8 = Add64(t6,0x0000000000000008) 22 | PUT(rsp) = t8 23 | t18 = Sub64(t8,0x0000000000000080) 24 | ====== AbiHint(0xt18, 128, t7) ====== NEXT: PUT(rip) = t7; Ijk_Ret
This block acts as both a return endpoint and a transition endpoint (transitioning to 0x424355).
- Parameters:
endpoint_node – The endpoint node.
sort – Type of the endpoint.
- Returns:
None
- mark_nonreturning_calls_endpoints()
Iterate through all call edges in transition graph. For each call a non-returning function, mark the source basic block as an endpoint.
This method should only be executed once all functions are recovered and analyzed by CFG recovery, so we know whether each function returns or not.
- Returns:
None
- call_edge_addrs()
(call-site block address, callee address) of every call edge, in transition-graph order. Unlike call_sites, a block with several call targets contributes one pair per target.
- jumpout_targets()
(jump-out site block address, target address, branch instruction address) of every transition that leaves this function, such as a tail jump. The instruction address is None when the CFG did not record it.
- unconfirmed_fakeret_edges()
Fake-return edges that have not been confirmed by a return of the callee, in transition-graph order.
- outgoing_function_targets()
Addresses of the functions this function calls or jumps out to.
- get_call_sites()
Gets a list of all the basic blocks that end in calls.
- get_call_target(callsite_addr)
Get the target of a call.
- Parameters:
callsite_addr – The address of a basic block that ends in a call.
- Returns:
The target of said call, or None if callsite_addr is not a callsite.
- get_call_return(callsite_addr)
Get the hypothetical return address of a call.
- Parameters:
callsite_addr – The address of the basic block that ends in a call.
- Returns:
The likely return target of said call, or None if callsite_addr is not a callsite.
- property graph: TransitionGraph
Get a local transition graph. A local transition graph is a transition graph that only contains nodes that belong to the current function. All edges, except for the edges going out from the current function or coming from outside the current function, are included.
The generated graph is a read-only view cached in self._local_transition_graph.
- Returns:
A local transition graph.
- graph_ex(exception_edges=True)
Get a local transition graph with a custom configuration. A local transition graph is a transition graph that only contains nodes that belong to the current function. This method allows user to include certain types of edges and nodes, such as exception edges.
The generated graph is not cached. It is a mutable copy.
- transition_graph_ex(exception_edges=True)
Get a transition graph with a custom configuration. This method allows user to exclude certain types of edges together with the nodes that are only reachable through such edges, such as exception edges.
The generated graph is not cached.
- Parameters:
exception_edges (bool) – Should exception edges and the nodes that are only reachable through exception edges be kept.
- Returns:
A local transition graph with a special configuration.
- Return type:
networkx.DiGraph
- subgraph(ins_addrs)
Generate a sub control flow graph of instruction addresses based on self.graph
- Parameters:
ins_addrs (iterable) – A collection of instruction addresses that should be included in the subgraph.
- Return networkx.DiGraph:
A subgraph.
- instruction_size(insn_addr)
Get the size of the instruction specified by insn_addr.
- Parameters:
insn_addr (int) – Address of the instruction
- Return int:
Size of the instruction in bytes, or None if the instruction is not found.
- addr
- bp_on_stack
- evicted
- meta_only
- normalized
- previous_names
- ran_cca
- retaddr_on_stack
- sp_delta
- tags
- addr_to_instruction_addr(addr)
Obtain the address of the instruction that covers @addr.
- dbg_print()
Returns a representation of the list of basic blocks in this function.
- dbg_draw(filename)
Draw the graph and save it to a PNG file.
- property arguments
- property has_return
- property callable
- normalize()
Make sure all basic blocks in the transition graph of this function do not overlap. You will end up with a CFG that IDA Pro generates.
This method does not touch the CFG result. You may call CFG{Emulated, Fast}.normalize() for that matter.
- Returns:
None
- find_declaration(ignore_binary_name=False, binary_name_hint=None)
Find the most likely function declaration from the embedded collection of prototypes, set it to self.prototype, and update self.calling_convention with the declaration.
- Parameters:
ignore_binary_name (
bool) – Do not rely on the executable or library where the function belongs to determine its source library. This is useful when working on statically linked binaries (because all functions will belong to the main executable). We will search for all libraries in angr to find the first declaration match.binary_name_hint (
str|None) – Substring of the library name where this function might be originally coming from. Useful for FLIRT-identified functions in statically linked binaries.
- Return type:
- Returns:
True if a declaration is found and self.prototype and self.calling_convention are updated. False if we fail to find a matching function declaration, in which case self.prototype or self.calling_convention will be kept untouched.
- is_rust_function()
Determines if the function name follows Rust mangling conventions.
- property demangled_name
- property short_name
- get_unambiguous_name(display_name=None)
Get a disambiguated function name.
- Parameters:
display_name (
str|None) – Name to display, otherwise the function name.- Return type:
- Returns:
The function name in one of the following forms:
::<name>when the function binary is the main object.::<obj>::<name>when the function binary is not the main object.::<addr>::<name>when the function binary is an unnamed non-main object, or when multiple functions with the same name are defined in the function binary.
- apply_definition(definition, calling_convention=None)
- functions_reachable()
- holes(min_size=8)
Find the number of non-consecutive areas in the function that are at least min_size bytes large.
- copy()
- pp(**kwargs)
Pretty-print the function disassembly.
- class angr.knowledge_plugins.FunctionManager
Bases:
KnowledgeBasePlugin,Mapping[K,Function],GenericWhen cache_limit is set, the FunctionManager uses a SpillingFunctionDict that implements an LRU cache keeping only the most recently accessed N functions in memory, spilling others to an LMDB database on disk. This allows working with binaries that have more functions than can fit in memory.
- Parameters:
cache_limit (
int|None) – Maximum number of functions to keep in memory. None means unlimited (no eviction). Default is None.
- __init__(kb, cache_limit=None)
- Parameters:
kb (KnowledgeBase)
cache_limit (int | None)
- copy()
- clear()
- get_default_cache_limit(max_limit=5000)
Get the default function cache limit based on the size of the binary.
- function_name_changed(addr, old_name, new_name)
Notify the FunctionManager that a function’s name has changed.
- get_by_name(name, check_previous_names=False)
- get_addrs_by_name(name, check_previous_names=False)
- contains_addr(addr)
Decide if an address is handled by the function manager.
Note: this function is non-conformant with python programming idioms, but its needed for performance reasons.
- Parameters:
addr (int) – Address of the function.
- ceiling_addr(addr)
Return the function who has the least address that is greater than or equal to addr.
- Parameters:
addr (
TypeVar(K,int,SootMethodDescriptor)) – The address to query.- Return type:
- Returns:
A Function instance, or None if there is no other function after addr.
- ceiling_func(addr)
Return the function who has the least address that is greater than or equal to addr.
- floor_addr(addr)
Return the function who has the greatest address that is less than or equal to addr.
- Parameters:
addr (
TypeVar(K,int,SootMethodDescriptor)) – The address to query.- Return type:
- Returns:
An address, or None if there is no other function before addr.
- floor_func(addr)
Return the function who has the greatest address that is less than or equal to addr.
- query(query, check_previous_names=False)
Query for a function using selectors to disambiguate. Supported variations:
::<name> Function <name> in the main object ::<addr>::<name> Function <name> at <addr> ::<obj>::<name> Function <name> in <obj>
- function(addr=None, name=None, check_previous_names=False, create=False, syscall=False, plt=None)
Get a function object from the function manager.
Pass either addr or name with the appropriate values.
- Parameters:
addr (
Optional[TypeVar(K,int,SootMethodDescriptor)]) – Address of the function.create (
bool) – Whether to create the function or not if the function does not exist.syscall (
bool) – True to create the function as a syscall, False otherwise.plt (
bool|None) – True to find the PLT stub, False to find a non-PLT stub, None to disable this restriction.check_previous_names (bool)
- Returns:
The Function instance, or None if the function is not found and create is False.
- Return type:
- dbg_draw(prefix='dbg_function_')
- rebuild_callgraph()
- unknown_returning_func_addrs()
Yield all function addresses with unknown returning status.
- is_func_nonreturning(addr)
Check if a function is non-returning.
- Parameters:
addr (
TypeVar(K,int,SootMethodDescriptor)) – Address of the function.- Return type:
- Returns:
True if non-returning, False if returning or unknown.
- is_func_returning_unknown(addr)
Check if a function’s returning status is unknown.
- Parameters:
addr (
TypeVar(K,int,SootMethodDescriptor)) – Address of the function.- Return type:
- Returns:
True if returning status is unknown, False otherwise.
- get_func_block_count(addr)
Get the number of blocks in a function.
- Parameters:
addr (
TypeVar(K,int,SootMethodDescriptor)) – Address of the function.- Return type:
- Returns:
Number of blocks, or None if unknown.
- set_func_block_count(addr, count)
Set the number of blocks in a function.
- Parameters:
addr (
TypeVar(K,int,SootMethodDescriptor)) – Address of the function.count (
int) – Number of blocks.
- Return type:
- Returns:
None
- get_func_addr_with_block_count(block_count)
Get the addresses of all functions that have exactly
block_countblocks.- Parameters:
block_count (
int) – The number of blocks to match.- Return type:
set[TypeVar(K,int,SootMethodDescriptor)]- Returns:
The set of matching function addresses.
- get_func_name(addr)
Get the name of a function without loading the (possibly spilled) Function object.
- Parameters:
addr (
TypeVar(K,int,SootMethodDescriptor)) – Address of the function.- Return type:
- Returns:
The function’s name, or None if unknown.
- get_from_signature(addr)
Get the
from_signaturevalue of a function without loading the (possibly spilled) Function object.- Parameters:
addr (
TypeVar(K,int,SootMethodDescriptor)) – Address of the function.- Return type:
- Returns:
The function’s
from_signaturevalue (e.g."flirt"), or None.
- set_from_signature(addr, from_signature)
Update the cached
from_signaturevalue for a function. Called by Function.from_signature’s setter.
- get_all_funcaddrs_from_signature(from_signature='flirt')
Get the addresses of all functions whose
from_signaturematches, without loading any Function object.- Parameters:
from_signature (
str) – Thefrom_signaturevalue to match (default"flirt").- Return type:
set[TypeVar(K,int,SootMethodDescriptor)]- Returns:
The set of matching function addresses.
- get_key_func_addrs(func_type)
- Return type:
set[TypeVar(K,int,SootMethodDescriptor)]- Parameters:
func_type (str)
- get_key_func_type_and_addrs()
Get all cached key functions grouped by key-function type (e.g.
"alloca_probe","jmp_rax").
- index_key_func_addrs(func)
Record every key-function flag that
func.infocarries in the key-function address cache.
- property cache_limit: int | None
Get the maximum number of functions to keep in memory. None means unlimited (no eviction).
- property cached_function_count: int
Return the number of functions currently in memory.
- property spilled_function_count: int
Return the number of functions currently spilled to LMDB.
- property total_function_count: int
Return the total number of functions (in memory + spilled).
- class angr.knowledge_plugins.IndirectJumps
Bases:
KnowledgeBasePlugin,dictThis plugin tracks the targets of indirect jumps
- class angr.knowledge_plugins.KeyDefinitionManager
Bases:
KnowledgeBasePluginKeyDefinitionManager manages and caches reaching definition models for each function.
For each function, by default we cache the entire reaching definitions model with observed results at the following locations: - Before each call instruction: (‘insn’, address of the call instruction, OP_BEFORE) - After returning from each call: (‘node’, address of the block that ends with a call, OP_AFTER)
- __init__(kb)
- Parameters:
kb (KnowledgeBase)
- has_model(func_addr)
- Parameters:
func_addr (int)
- get_model(func_addr)
- Parameters:
func_addr (int)
- copy()
- Return type:
- class angr.knowledge_plugins.KnowledgeBasePlugin
Bases:
object- __init__(kb)
- Parameters:
kb (KnowledgeBase)
- copy()
- set_kb(kb)
Invoked after __setstate__() is called.
- Parameters:
kb (KnowledgeBase)
- static register_default(name, cls)
- class angr.knowledge_plugins.Labels
Bases:
KnowledgeBasePlugin- __init__(kb)
- items()
- get(addr, default=None)
Get a label as string for a given address Same as .labels[x]
- lookup(name, default=None)
Returns an address to a given label To show all available labels, iterate over .labels or list(b.kb.labels)
- copy()
- get_unique_label(label)
Get a unique label name from the given label name.
- Parameters:
label (str) – The desired label name.
- Returns:
A unique label name.
- class angr.knowledge_plugins.Obfuscations
Bases:
KnowledgeBasePluginStore discovered information and artifacts about (string) obfuscation techniques in the project.
- __init__(kb)
- copy()
- class angr.knowledge_plugins.PatchManager
Bases:
KnowledgeBasePluginA placeholder-style implementation for a binary patch manager. This class should be significantly changed in the future when all data about loaded binary objects are loaded into angr knowledge base from CLE. As of now, it only stores byte-level replacements.
Patches should not overlap, but it’s user’s responsibility to check for and avoid overlapping patches.
- __init__(kb)
- has_patches()
- Return type:
- add_patch(addr, new_bytes, comment=None)
- Parameters:
comment (str | None)
- add_patch_obj(patch)
- Parameters:
patch (Patch)
- remove_patch(addr)
- patch_addrs()
- get_patch(addr)
Get patch at the given address.
- get_all_patches(addr, size)
Retrieve all patches that cover a region specified by [addr, addr+size).
- keys()
- items()
- values()
- copy()
- static overlap(a0, a1, b0, b1)
- apply_patches_to_binary(binary_bytes=None, patches=None)
- apply_patches_to_state(state)
- property patched_entry_state
- class angr.knowledge_plugins.Patterns
Bases:
KnowledgeBasePluginThe fuzzy patterns of a knowledge base, by pattern name.
- __init__(kb)
- Parameters:
kb (KnowledgeBase)
- copy()
- Return type:
- record_stats(func_addr, stats)
Replace what is known about
func_addr: the outliner pass saw exactly these patterns.- Return type:
- Parameters:
func_addr (int)
stats (dict[str, PatternStats])
- stats(func_addr, name)
The outliner pass’s numbers for a pattern in a function, or None if it did not search for that pattern there when it last ran.
- Return type:
- Parameters:
- get(name)
- Return type:
- Parameters:
name (str)
- add(pattern, *, enabled=True, min_similarity=0.8, origin_func=None, require_verified=True, replace=False)
Store
pattern. Refuses a name or call name already taken unlessreplace.- Return type:
- Parameters:
- store(stored)
Put a StoredPattern back, keeping its settings (a loader’s entry point).
- Return type:
- Parameters:
stored (StoredPattern)
- enabled_patterns()
- Return type:
- by_call_name(call_name)
- Return type:
- Parameters:
call_name (str)
- class angr.knowledge_plugins.PropagationManager
Bases:
KnowledgeBasePluginManages the results of Propagator, including intermediate results for unfinished Propagation runs.
- __init__(kb)
- exists(prop_key)
Internal function to check if a func, specified as a CodeLocation exists in our known propagations
- update(prop_key, model)
Add the replacements to known propagations
- Parameters:
prop_key (
tuple) – A key of the propagation result.model (
PropagationModel) – The propagation result to store
- Return type:
- get(prop_key, default=None)
Gets the replacements for a specified function location. If the replacement does not exist in the known propagations, it returns None.
- Parameters:
prop_key – A key of the propagation result.
default – The default value to return if the prop_key does not exist in the cache.
- Return type:
- Returns:
Dict or None
- copy()
- discard_by_prefix(prefix)
- Parameters:
prefix (str)
- class angr.knowledge_plugins.RuntimeDb
Bases:
KnowledgeBasePluginExternal storage-backed database for angr knowledge base plugins.
- __init__(kb, lmdb_path=None)
- Parameters:
kb (KnowledgeBase)
lmdb_path (str | None)
- Return type:
None
- increase_lmdb_map_size()
Increase the LMDB map size. Returns False when there is no environment to grow (callers must not retry).
Note that the old database handle may no longer be valid after a map size increase. rhelmot could reproduce the error “Database handle belongs to another environment.” in nix + CPython 3.13.13. Reopening all databases after increasing LMDB map size solves this issue.
- Return type:
- reopen_lmdb()
Reopen the existing LMDB environment and all open databases in self._dbs.
- reopen_lmdb_databases()
- cleanup()
Close the LMDB environment and remove the rtdb directory if this is the last user of it. This method may be invoked multiple times (e.g., once by the atexit hook and once more by __del__) and should not fail.
- class angr.knowledge_plugins.StoredPattern
Bases:
objectOne fuzzy pattern and its application settings.
- pattern: KnownPattern
- min_similarity: float = 0.8¶
an occurrence is outlined only at this similarity or above (see search.TemplateMatch)
- require_verified: bool = True¶
outline only occurrences that pass the pattern’s structural match (constants, captures); off, similarity alone decides, as it does for discovered patterns
- created_at: float
- property name: str
- classmethod from_dict(data)
- Return type:
- Parameters:
- class angr.knowledge_plugins.StructuredCodeManager
Bases:
KnowledgeBasePluginA knowledge base plugin to store structured code generator results.
- __init__(kb, cache_limit=None)
- Parameters:
cache_limit (int | None)
- get(key, default=None)
- discard(key)
- available_flavors(item)
- all_flavors(item)
- copy()
- class angr.knowledge_plugins.TypesStore
Bases:
KnowledgeBasePlugin,UserDict[str,TypeRef]A kb plugin that stores a mapping from name to TypeRef. It will return types from angr.sim_type.ALL_TYPES as a default.
- __init__(kb)
- copy()
- iter_own()
Iterate over all the names which are stored in this object - i.e.
values()withoutALL_TYPES
- iter_own_keys()
- unique_type_name()
- Return type:
- class angr.knowledge_plugins.VariableManager
Bases:
KnowledgeBasePluginManage variables.
- __init__(kb)
- global_managers: dict[str, VariableManagerInternal]
- function_managers: dict[int, VariableManagerInternal] | SpillingVariableInternalDict
- property global_manager: VariableManagerInternal
The global manager of the default flavor. Code with no decompilation flavor (CFG, DWARF, SimProcedures) uses it.
- get_global_manager(flavor)
The global manager that a decompilation of the given flavor (None means the default flavor) reads and writes. A new flavor starts empty: global names are re-derived from labels, types are re-inferred.
- Return type:
- Parameters:
flavor (str | None)
- set_global_manager(flavor, manager)
- Return type:
- Parameters:
flavor (str | None)
manager (VariableManagerInternal)
- has_function_manager_for_flavor(key, flavor)
Whether a function manager exists and can be reused by a decompilation of the given flavor. A manager of unknown flavor (None) is compatible with any flavor.
- get_function_manager(func_addr)
- Return type:
- initialize_variable_names()
- Return type:
- get_variable_accesses(variable, same_name=False)
Get a list of all references to the given variable.
- Parameters:
variable (
SimVariable) – The variable.same_name (
bool) – Whether to include all variables with the same variable name, or just based on the variable identifier.
- Return type:
- Returns:
All references to the variable.
- copy()
- static convert_variable_list(vlist, manager)
- Parameters:
manager (VariableManagerInternal)
- load_from_dwarf(cu_list=None)
- Parameters:
cu_list (list[CompilationUnit] | None)
- class angr.knowledge_plugins.XRefManager
Bases:
KnowledgeBasePlugin,Serializable- __init__(kb)
- copy()
- clear()
- add_xref(xref)
- add_xrefs(xrefs)
- get_xrefs_by_ins_addr(ins_addr)
- get_xrefs_by_dst(dst)
- get_xrefs_by_dst_region(start, end)
Get a set of XRef objects that point to a given address region bounded by start and end. Will only return absolute xrefs, not relative ones (like SP offsets)
- get_next_xref_addr_by_dst(addr)
Get the next XRef object whose address is greater than or equal to the given address. Will only return absolute xrefs, not relative ones (like SP offsets)
Submodules
User-authored fuzzy patterns, kept with the knowledge base so they outlive a session. |
|