angr.analyses.decompiler

class angr.analyses.decompiler.AILSimplifier

Bases: Analysis

Perform function-level simplifications.

__init__(func, func_graph, ail_manager, remove_dead_memdefs=False, stack_arg_offsets=None, unify_variables=False, gp=None, narrow_expressions=False, fold_expressions=True, only_consts=False, fold_callexprs_into_conditions=False, use_callee_saved_regs_at_return=True, rewrite_ccalls=True, rename_ccalls=True, rewrite_dirty=True, removed_vvar_ids=None, arg_vvars=None, avoid_vvar_ids=None)
class angr.analyses.decompiler.BaseStructuredCodeGenerator

Bases: object

__init__(flavor=None, notes=None, expr_comments=None, stmt_comments=None, const_formats=None)
static adjust_mapping_positions(offset, pos_to_node, pos_to_addr, addr_to_pos)

Adjust positions in the mappings to account for the notes that are prepended to the text.

Parameters:

  • offset (int) – The length of the notes to prepend.

  • pos_to_node (PositionMapping) – The position to node mapping.

  • pos_to_addr (PositionMapping) – The position to address mapping.

  • addr_to_pos (InstructionMapping) – The address to position mapping.

Return type:

tuple[PositionMapping, PositionMapping, InstructionMapping]

Returns:

Adjusted mappings.

reapply_options(options)
regenerate_text()
Return type:

None

reload_variable_types()
Return type:

None

next_idx(key)
Return type:

str

Parameters:

key (str)

reset_idx_counters()
Return type:

None

class angr.analyses.decompiler.BlockSimplifier

Bases: Analysis

Simplify an AIL block.

__init__(block, ail_manager, func_addr=None, stack_pointer_tracker=None, peephole_optimizations=None, preserve_vvar_ids=None, type_hints=None, cached_reaching_definitions=None, cached_propagator=None)
Parameters:
class angr.analyses.decompiler.CStructuredCodeGenerator

Bases: BaseStructuredCodeGenerator, Analysis

__init__(func, sequence, indent=0, cfg=None, variable_kb=None, func_args=None, binop_depth_cutoff=16, show_casts=True, braces_on_own_lines=True, use_compound_assignments=True, show_local_types=True, comment_gotos=False, cstyle_null_cmp=True, flavor=None, stmt_comments=None, expr_comments=None, show_externs=True, externs=None, const_formats=None, show_demangled_name=True, show_disambiguated_name=True, ail_graph=None, simplify_else_scope=True, cstyle_ifs=True, omit_func_header=False, display_block_addrs=False, display_vvar_ids=False, min_data_addr=4194304, notes=None, display_notes=True, max_str_len=None, prettify_thiscall=False, cstyle_void_param=True, variable_map=None)
Parameters:
reapply_options(options)
cleanup()

Remove existing rendering results.

regenerate_text()

Re-render text and re-generate all sorts of mapping information.

Return type:

None

render_text(cfunc)
Return type:

tuple[str, PositionMapping, PositionMapping, InstructionMapping, dict[Any, set[Any]]]

Parameters:

cfunc (CFunction)

render_notes()

Render decompilation notes.

Return type:

str

Returns:

A string containing all notes.

reload_variable_types()
Return type:

None

default_simtype_from_bits(n, signed=True)
Return type:

SimType

Parameters:
variables_unify(v1, v2)
Return type:

bool

Parameters:
class angr.analyses.decompiler.CallSiteMaker

Bases: Analysis

Add calling convention, declaration, and args to a call site.

__init__(block, *, ail_manager, reaching_definitions=None, stack_pointer_tracker=None)
Parameters:

ail_manager (Manager)

class angr.analyses.decompiler.Clinic

Bases: Analysis

A Clinic deals with AILments.

__init__(func, remove_dead_memdefs=False, exception_edges=False, sp_tracker_track_memory=True, fold_expressions=True, fold_callexprs_into_conditions=False, insert_labels=True, optimization_passes=None, cfg=None, peephole_optimizations=None, must_struct=None, variable_kb=None, reset_variable_names=False, rewrite_ites_to_diamonds=True, cache=None, mode=ClinicMode.DECOMPILE, sp_shift=0, inline_functions=None, inlined_counts=None, inlining_parents=None, vvar_id_start=0, optimization_scratch=None, desired_variables=None, force_loop_single_exit=True, refine_loops_with_single_successor=False, complete_successors=False, typehoon_cls=<class 'angr.analyses.typehoon.typehoon.Typehoon'>, max_type_constraints=100000, type_constraint_set_degradation_threshold=150, ail_graph=None, arg_vvars=None, start_stage=ClinicStage.INITIALIZATION, end_stage=None, skip_stages=(), notes=None, static_vvars=None, static_buffers=None, flatten_args=False, constrain_callee_prototypes=False, semvar_naming=True, flavor='pseudocode', variable_map=None)
Parameters:
block(addr, size)

Get the converted block at the given specific address with the given size.

Parameters:
Returns:

dbg_repr()
Returns:

calculate_stack_depth()
copy_graph(graph=None)
Return type:

DiGraph

parse_variable_addr(addr)
Return type:

tuple[Any, Any]

Parameters:

addr (Expression)

new_block_addr()

Return a block address that does not conflict with any existing blocks.

Return type:

int

Returns:

The block address.

static remove_empty_nodes(graph)
Return type:

DiGraph

Parameters:

graph (DiGraph)

constrain_callee_prototypes()

Constrain the types of callee function arguments based on facts that are observed at call sites. Note that this function will change the prototypes of (callee) functions in the knowledge base, which means it may affect the decompilation output of the current function if it is decompiled again.

class angr.analyses.decompiler.ClinicMode

Bases: Enum

Analysis mode for Clinic.

DECOMPILE = 1
COLLECT_DATA_REFS = 2
class angr.analyses.decompiler.DecompilationCache

Bases: object

Caches key data structures that can be used later for refining decompilation results, such as retyping variables.

__init__(addr)
parameters: dict[str, Any]
addr
type_constraints: dict[TypeVariable, set[TypeConstraint]] | None
arg_vvars: dict | None
func_typevar: TypeVariable | None
var_to_typevar: dict | None
stackvar_max_sizes: dict | None
stack_offset_typevars: dict | None
codegen: BaseStructuredCodeGenerator | None
clinic: Clinic | None
variable_map: VariableMap | None
ite_exprs: set[tuple[int, Any]] | None
binop_operators: dict[OpDescriptor, str] | None
errors: list[str]
function_summary: str | None
notes: dict[str, str]
max_tv_id: int
property local_types
class angr.analyses.decompiler.Decompiler

Bases: Analysis

The decompiler analysis.

Run this on a Function object for which a normalized CFG has been constructed. The fully processed output can be found in result.codegen.text

__init__(func, cfg=None, options=None, preset=None, optimization_passes=None, sp_tracker_track_memory=True, variable_kb=None, peephole_optimizations=None, vars_must_struct=None, flavor='pseudocode', expr_comments=None, stmt_comments=None, ite_exprs=None, binop_operators=None, decompile=True, regen_clinic=True, inline_functions=None, desired_variables=None, update_memory_data=True, want_full_graph=False, generate_code=True, use_cache=True, update_cache=True, expr_collapse_depth=16, clinic_graph=None, clinic_arg_vvars=None, clinic_start_stage=None, clinic_end_stage=None, clinic_skip_stages=(), static_vvars=None, static_buffers=None, codegen_cls=<class 'angr.analyses.decompiler.structured_codegen.c.CStructuredCodeGenerator'>)
Parameters:
reflow_variable_types(cache)

Re-run type inference on an existing variable recovery result, then rerun codegen to generate new results.

Returns:

Parameters:

cache (DecompilationCache)

find_data_references_and_update_memory_data(seq_node)
Parameters:

seq_node (SequenceNode)

transform_graph_from_ssa(ail_graph)

Translate an SSA AIL graph out of SSA form. This is useful for producing a non-SSA AIL graph for displaying in angr management.

Parameters:

ail_graph (DiGraph) – The AIL graph to transform out of SSA form.

Return type:

DiGraph

Returns:

The translated AIL graph.

transform_seqnode_from_ssa(seq_node)
Return type:

SequenceNode

Parameters:

seq_node (SequenceNode)

llm_refine()

Use the configured LLM to suggest improved variable names, function names, and variable types. Returns True if any changes were made.

Return type:

bool

llm_suggest_variable_names(llm_client=None, code_text=None, raise_exc=False)

Ask the LLM to suggest better variable names for the decompiled code. Returns True if any variables were renamed.

Parameters:

  • raise_exc (bool) – If True, exceptions from the LLM call are propagated to the caller. If False (default), exceptions are caught and the method returns False.

  • code_text (str | None)

Return type:

bool

llm_suggest_function_name(llm_client=None, code_text=None, raise_exc=False)

Ask the LLM to suggest a better function name. Only suggests rename for auto-generated names (starting with sub_ or fcn.). Returns True if the function was renamed.

Parameters:

  • raise_exc (bool) – If True, exceptions from the LLM call are propagated to the caller.

  • code_text (str | None)

Return type:

bool

llm_suggest_variable_types(llm_client=None, code_text=None, raise_exc=False)

Ask the LLM to suggest better C types for variables. Returns True if any variable types were changed.

Parameters:

  • raise_exc (bool) – If True, exceptions from the LLM call are propagated to the caller.

  • code_text (str | None)

Return type:

bool

llm_summarize_function(llm_client=None, code_text=None, raise_exc=False)

Ask the LLM to produce a natural-language summary of what the decompiled function does. The summary is stored in the DecompilationCache and returned.

Returns the summary string, or None if summarization failed.

Parameters:

  • raise_exc (bool) – If True, exceptions from the LLM call are propagated to the caller.

  • code_text (str | None)

Return type:

str | None

static options_to_params(options)

Convert decompilation options to a dict of params.

Parameters:

options (list[tuple[DecompilationOption, Any]]) – The decompilation options.

Return type:

dict[str, Any]

Returns:

A dict of keyword arguments.

class angr.analyses.decompiler.GraphDephication

Bases: DephicationBase

GraphDephication removes phi expressions from an AIL graph, essentially transforms a partial-SSA form of AIL graph to a normal AIL graph.

__init__(func, ail_graph, vvar_to_vvar_mapping=None, rewrite=False, variable_kb=None, variable_map=None)
Parameters:

  • func (Function | str) – The subject of the analysis: a function, or a single basic block

  • ail_graph – The AIL graph to transform.

  • vvar_to_vvar_mapping (dict[int, int] | None)

  • rewrite (bool)

  • variable_kb (KnowledgeBase | None)

  • variable_map (VariableMap | None)

class angr.analyses.decompiler.GraphRegion

Bases: object

GraphRegion represents a region of nodes.

Variables:

  • head – The head of the region.

  • graph – The region graph.

  • successors – A set of successors of nodes in the graph. These successors do not belong to the current region.

  • graph_with_successors – The region graph that includes successor nodes.

__init__(head, graph, successors, graph_with_successors, cyclic, full_graph, cyclic_ancestor=False)
head
graph
successors
graph_with_successors
full_graph
cyclic
cyclic_ancestor
copy()
Return type:

GraphRegion

recursive_copy(nodes_map=None)
property addr
static dbg_get_repr(obj, ident=0)
dbg_print(ident=0)
replace_region(sub_region, updated_sub_region, replace_with, virtualized_edges)
Parameters:
replace_region_with_region(sub_region, replace_with)
Parameters:
class angr.analyses.decompiler.ImportSourceCode

Bases: BaseStructuredCodeGenerator, Analysis

__init__(function, flavor='source', source_root=None, encoding='utf-8')
regenerate_text()
class angr.analyses.decompiler.RegionIdentifier

Bases: Analysis

A region is a single-entry-single-exit subgraph of control flow. The region identifier recursively identifies the smallest possible regions within a function graph and creates a GraphRegion object whose nodes are either Blocks or GraphRegions.

Note, that the analysis may modify the graph in-place. If you want to keep the original graph, set the update_graph parameter to False.

__init__(func, cond_proc=None, graph=None, ail_manager=None, update_graph=True, largest_successor_tree_outside_loop=True, force_loop_single_exit=True, refine_loops_with_single_successor=False, complete_successors=False, entry_node_addr=None)
static slice_graph(graph, node, frontier, include_frontier=False)

Generate a slice of the graph from the head node to the given frontier.

Parameters:

  • graph (networkx.DiGraph) – The graph to work on.

  • node – The starting node in the graph.

  • frontier – A list of frontier nodes.

  • include_frontier (bool) – Whether the frontier nodes are included in the slice or not.

Returns:

A subgraph.

Return type:

networkx.DiGraph[TNode]

test_reducibility()
Return type:

bool

class angr.analyses.decompiler.RegionSimplifier

Bases: Analysis

Simplifies a given region.

__init__(func, region, ail_manager, arg_vvars=None, simplify_switches=True, simplify_ifelse=True, variable_manager=None, loopctr_naming=True)
Parameters:
class angr.analyses.decompiler.SeqNodeDephication

Bases: DephicationBase

SeqNodeDephication removes phi expressions from a SequenceNode and its children. It also removes redundant variable assignments, e.g., vvar_2 = vvar_1 where both vvar_1 and vvar_2 are mapped to the same variable.

__init__(func, seq_node, vvar_to_vvar_mapping=None, rewrite=False, variable_kb=None, variable_map=None)
Parameters:
class angr.analyses.decompiler.Ssailification

Bases: Analysis

Ssailification (SSA-AIL-ification) transforms an AIL graph to its partial-SSA form.

__init__(func, ail_graph, entry=None, canonical_size=8, stack_pointer_tracker=None, func_addr=None, ail_manager=None, ssa_stackvars=False, ssa_tmps=False, func_args=None, rewrite_vvars=None, vvar_id_start=0)
Parameters:

  • func – The subject of the analysis: a function, or a single basic block

  • ail_graph – The AIL graph to transform.

  • canonical_size – The sizes (in bytes) that objects with an UNKNOWN_SIZE are treated as for operations where sizes are necessary.

angr.analyses.decompiler.StructuredCodeGenerator

alias of CStructuredCodeGenerator

class angr.analyses.decompiler.VariableMap

Bases: object

A side container that maps the .idx of AIL Statement and Expression objects to variable-related information.

The following pieces of information are tracked:

  • variable (a SimVariable) and variable_offset (an int): the variable that an AIL atom resolves to, and the offset into that variable.

  • custom_string (a bool): whether a Const expression refers to a custom string.

  • reference_values (a dict mapping SimType to a value): reference values associated with a Const expression (e.g., custom strings).

  • reference_variable (a SimVariable) and reference_variable_offset (an int): the variable that a constant expression references, and the offset into it. These are siblings of variable / variable_offset that are specifically used for constants that reference global/extern variables.

Keys are the integer .idx values of AIL Statement/Expression objects. Because Clinic builds one ailment.Manager per invocation, .idx values are unique within a single Clinic. So a VariableMap is scoped to one Clinic instance and is stored in the corresponding DecompilationCache.

__init__()
variable(obj)
Return type:

SimVariable | None

Parameters:

obj (TaggedObject | int)

variable_offset(obj)
Return type:

int

Parameters:

obj (TaggedObject | int)

custom_string(obj)
Return type:

bool

Parameters:

obj (TaggedObject | int)

reference_values(obj)
Return type:

dict[SimType, Any] | None

Parameters:

obj (TaggedObject | int)

reference_variable(obj)
Return type:

SimVariable | None

Parameters:

obj (TaggedObject | int)

reference_variable_offset(obj)
Return type:

int

Parameters:

obj (TaggedObject | int)

has_variable(obj)
Return type:

bool

Parameters:

obj (TaggedObject | int)

set_variable(obj, variable, offset=0)

Set the variable information for an AIL atom. If variable is None, the variable information for this atom is cleared.

Return type:

None

Parameters:
set_variable_offset(obj, offset)
Return type:

None

Parameters:
set_custom_string(obj, value=True)
Return type:

None

Parameters:
set_reference_values(obj, reference_values)
Return type:

None

Parameters:
set_reference_variable(obj, variable, offset=0)

Set the reference variable information for an AIL atom. If variable is None, the reference variable information for this atom is cleared.

Return type:

None

Parameters:
transfer(src, dst)

Copy all variable information associated with src to dst. Used when an AIL atom is deep-copied to a new .idx (e.g. during structuring/duplication) so that the new atom keeps the same variable association.

Return type:

None

Parameters:
to_json()

Serialize this VariableMap to a JSON-compatible object.

Variables are referenced by their .ident (reference-by-ident); they must be resolved back to SimVariable objects via a resolver in from_json().

Return type:

dict[str, Any]

classmethod from_json(data, resolve_variable)

Deserialize a VariableMap from a JSON-compatible object produced by to_json().

Parameters:

  • data (dict[str, Any]) – The JSON object.

  • resolve_variable (Callable[[str], SimVariable | None]) – A callable that maps a variable ident (str) to a SimVariable (or None if it cannot be resolved).

Return type:

VariableMap

Submodules

ail_simplifier

ailgraph_walker

block_io_finder

block_similarity

block_simplifier

callsite_maker

ccall_rewriters

clinic

condition_processor

counters

decompilation_cache

decompilation_options

decompiler

dephication

dirty_rewriters

empty_node_remover

expression_narrower

goto_manager

graph_region

jump_target_collector

jumptable_entry_condition_rewriter

label_collector

node_replacer

notes

optimization_passes

peephole_optimizations

presets

redundant_label_remover

region_identifier

region_simplifiers

region_walker

return_maker

semantic_naming

Semantic variable naming patterns for the decompiler.

seq_to_blocks

sequence_walker

ssailification

stack_item

structured_codegen

structurer_nodes

structuring

utils

variable_map