angr.analyses.decompiler.semantic_naming¶

Semantic variable naming patterns for the decompiler.

This package provides various patterns for automatically naming variables based on their semantic usage (loop counters, array indices, etc.).

The naming passes are split into two categories: - Clinic-based passes: Run on the AIL graph before structuring (ClinicNamingBase) - Region-based passes: Run after structuring on the structured region (RegionNamingBase)

Loop counter naming is a Region-based pass that runs in RegionSimplifier to leverage the structured LoopNode information.

class angr.analyses.decompiler.semantic_naming.ArrayIndexNaming

Bases: ClinicNamingBase

Detects variables used as array indices and renames them.

Array index patterns detected: - base + idx * scale (common array indexing) - base + idx (byte array or pointer arithmetic) - ptr[idx] style access

PRIORITY: int = 50¶

__init__(*args, **kwargs)

analyze()

Analyze the graph for array index patterns.

Return type:: dict[SimVariable, str]
Returns:: Dictionary mapping SimVariable to new name

class angr.analyses.decompiler.semantic_naming.BooleanNaming

Bases: ClinicNamingBase

Detects variables used as boolean flags and renames them.

Boolean flag patterns detected: - Variables assigned only 0 or 1 - Variables used directly in conditions (if (var) or if (!var)) - Variables compared to 1 - Variables that are results of comparison operations

PRIORITY: int = 80¶

__init__(*args, **kwargs)

analyze()

Analyze the graph for boolean flag patterns.

Return type:: dict[SimVariable, str]
Returns:: Dictionary mapping SimVariable to new name

class angr.analyses.decompiler.semantic_naming.CallResultNaming

Bases: ClinicNamingBase

Detects variables that store function call results and names them based on the called function.

PRIORITY: int = 40¶

__init__(*args, **kwargs)

analyze()

Analyze the graph for function call result patterns.

Return type:: dict[SimVariable, str]
Returns:: Dictionary mapping SimVariable to new name

class angr.analyses.decompiler.semantic_naming.ClinicNamingBase

Bases: SemanticNamingBase

Base class for semantic naming passes that run in Clinic on AIL graphs.

These passes operate on the raw AIL graph before structuring, allowing them to analyze control flow patterns directly.

__init__(ail_graph, variable_manager, functions, entry_node)

Parameters:

ail_graph (DiGraph)
variable_manager (VariableManagerInternal)
functions (FunctionManager)
entry_node (Block)

class angr.analyses.decompiler.semantic_naming.PointerNaming

Bases: ClinicNamingBase

Detects variables used as pointers and renames them.

Pointer patterns detected: - Variables used as addresses in Load/Store operations - Variables involved in pointer arithmetic - Variables passed to functions expecting pointers - Variables receiving pointer-returning function results - Variables used in linked-list patterns (next/prev access)

PRIORITY: int = 45¶

__init__(*args, **kwargs)

analyze()

Analyze the graph for pointer variable patterns.

Return type:: dict[SimVariable, str]
Returns:: Dictionary mapping SimVariable to new name

class angr.analyses.decompiler.semantic_naming.RegionLoopCounterNaming

Bases: RegionNamingBase

Detects loop counter variables from structured LoopNodes and renames them to standard names like i, j, k based on nesting depth.

This pass operates after structuring and uses the iterator information already extracted by LoopSimplifier (stored in LoopNode.iterator).

PRIORITY: int = 10¶

__init__(region, variable_manager, functions)

Parameters:

region (BaseNode)
variable_manager (VariableManagerInternal)
functions (FunctionManager)

analyze()

Analyze the structured region for loop counters and return a mapping of variables to their new names.

Return type:: dict[SimVariable, str]
Returns:: Dictionary mapping SimVariable to new name (e.g., “i”, “j”, “k”)

class angr.analyses.decompiler.semantic_naming.RegionNamingBase

Bases: SemanticNamingBase

Base class for semantic naming passes that run in RegionSimplifier on structured regions.

These passes operate after structuring, allowing them to leverage structured information like LoopNode, ConditionNode, etc. They can reuse loop analysis results from structuring instead of re-analyzing the graph.

__init__(region, variable_manager, functions)

Parameters:

region (BaseNode)
variable_manager (VariableManagerInternal)
functions (FunctionManager)

class angr.analyses.decompiler.semantic_naming.SemanticNamingBase

Bases: ABC

Abstract base class for semantic variable naming patterns.

Subclasses implement specific naming patterns (loop counters, array indices, etc.) This is the common base for both Clinic-based and RegionSimplifier-based passes.

PRIORITY: int = 100¶

__init__(variable_manager, functions)

Parameters:

variable_manager (VariableManagerInternal)
functions (FunctionManager)

abstractmethod analyze()

Analyze and return a mapping of variables to their suggested names.

Return type:: dict[SimVariable, str]
Returns:: Dictionary mapping SimVariable to suggested name

apply_names(exclude_vars=None)

Apply the computed names to the variables.

Parameters:: exclude_vars (set[SimVariable] | None) – Variables to skip (already named by higher priority patterns)
Return type:: set[SimVariable]
Returns:: Set of variables that were renamed

class angr.analyses.decompiler.semantic_naming.SemanticNamingOrchestrator

Bases: object

Orchestrates multiple semantic naming patterns.

Runs each pattern in priority order (lower PRIORITY value = runs first). Variables named by higher-priority patterns are not renamed by lower-priority ones.

__init__(ail_graph, variable_manager, functions, entry_node, patterns=None)

Parameters:

ail_graph (DiGraph)
variable_manager (VariableManagerInternal)
functions (FunctionManager)
entry_node (Block)
patterns (list[type[ClinicNamingBase]] | None)

analyze()

Run all semantic naming patterns in priority order.

Return type:: dict[SimVariable, str]
Returns:: Combined mapping of all renamed variables to their new names

resolve_name_collisions()

Suffix duplicate names (len, len1, …) so each variable is unique.

Two distinct variables can get the same name (two strlen -> “len”, or CallResultNaming and PointerNaming both -> “ptr”).

Return type:: None

class angr.analyses.decompiler.semantic_naming.SizeNaming

Bases: ClinicNamingBase

Detects variables used as sizes, lengths, or counts based on: 1. Being passed as size parameters to known functions 2. Being used in loop bounds (compared with loop counters) 3. Having names that suggest size semantics

PRIORITY: int = 70¶

__init__(*args, **kwargs)

analyze()

Analyze the graph for size/length variable patterns.

Return type:: dict[SimVariable, str]
Returns:: Dictionary mapping SimVariable to new name

Submodules

`array_index_naming`	Semantic variable naming for array indices.
`boolean_naming`	Semantic variable naming for boolean flag variables.
`call_result_naming`	Semantic variable naming for function call results.
`naming_base`	Base class for semantic variable naming patterns.
`orchestrator`	Orchestrator for semantic variable naming patterns.
`pointer_naming`	Semantic variable naming for pointer variables.
`region_loop_counter_naming`	Semantic variable naming for loop counters using structured regions.
`size_naming`	Semantic variable naming for size/length/count variables.