Utilities

Utility functions and error classes for advanced angrop usage

Utility Functions

angrop provides a comprehensive set of utility functions in rop_utils.py for working with symbolic execution, gadget analysis, and ROP chain construction.

Address and Assembly

addr_to_asmstring

def addr_to_asmstring(project, addr) -> str

Converts an address to a human-readable assembly string.

project · angr.Project · required

The project containing the binary

addr · int · required

The address to disassemble

Returns: String of semicolon-separated instructions (e.g., "pop rax; pop rbx; ret")

Example:

asm = addr_to_asmstring(project, 0x401000)
print(asm)  # "mov eax, ebx; add eax, 0x10; ret"

AST Dependency Analysis

get_ast_dependency

def get_ast_dependency(ast) -> set

Identifies which registers affect a symbolic AST expression.

ast · claripy.ast.BV · required

The AST to analyze. Must be created from a symbolic state where registers are named "sreg_REG-"

Returns: Set of register names that affect the AST value

Algorithm:

• Extracts all variables starting with "sreg_"
• Returns the register name portion (e.g., "sreg_rax-123" → "rax")
• Returns empty set if any non-register variables are found

Example:

# After symbolic execution
rax_val = final_state.registers.load('rax')
deps = get_ast_dependency(rax_val)
print(deps)  # {'rbx', 'rcx'}  (rax depends on rbx and rcx)

get_ast_controllers

def get_ast_controllers(state, ast, reg_deps) -> set

Identifies which registers can fully control (unconstrain) an AST expression.

state · angr.SimState · required

The symbolic state

ast · claripy.ast.BV · required

The AST to analyze

reg_deps · set · required

Set of register dependencies (from get_ast_dependency)

Returns: Set of register names that can make the AST take arbitrary values

Algorithm:

1. For each dependent register, set all other registers to a test value
2. Check if the resulting AST is unconstrained using fast_unconstrained_check
3. Return registers that allow arbitrary values

Example:

# rax = rbx + rcx + 0x1000
controllers = get_ast_controllers(state, rax_val, {'rbx', 'rcx'})
print(controllers)  # {'rbx', 'rcx'}

# rax = (rbx & 0xFF) + rcx
controllers = get_ast_controllers(state, rax_val, {'rbx', 'rcx'})
print(controllers)  # {'rcx'}  (rbx is constrained by AND)

get_ast_const_offset

def get_ast_const_offset(state, ast, reg_deps) -> int

Extracts the constant offset from a memory access expression.

state · angr.SimState · required

The symbolic state

ast · claripy.ast.BV · required

The memory address AST

reg_deps · set · required

Register dependencies

Returns: The constant offset value

Example:

# mov [rax + 0x10], rbx
addr_ast = mem_write_action.addr.ast
offset = get_ast_const_offset(state, addr_ast, {'rax'})
print(offset)  # 0x10

Constraint Checking

unconstrained_check

def unconstrained_check(state, ast) -> bool

Checks if an AST is completely unconstrained (can take any value).

Returns: True if the AST has no constraints in the solver

fast_unconstrained_check

def fast_unconstrained_check(state, ast) -> bool

Quickly checks if an AST is probably unconstrained using heuristics.

Heuristics:

1. Allowed operations: Extract, BVS, add, sub, xor, Reverse, BVV, ZeroExt, SignExt
2. Disallowed patterns:
   • Bitwise AND with non-all-ones constant
   • Bitwise OR with non-zero constant
   • Shifts by non-zero amount
   • Operations like x + x (constrained)
3. Byte-level check: Each byte must be unconstrained
4. Fallback: Uses loose_constrained_check if heuristics pass

Example:

# rax is completely controllable
if fast_unconstrained_check(state, state.regs.rax):
    print("Can set rax to any value")

# (rax & 0xFF) is constrained
if not fast_unconstrained_check(state, state.regs.rax & 0xFF):
    print("Cannot fully control lower byte")

loose_constrained_check

def loose_constrained_check(state, ast, extra_constraints=None) -> bool

Checks if an AST can take at least 3 out of 5 test values.

Test values:

1. 0x0
2. 0xFFFFFFFF... (all ones)
3. 0xAAAAAAAA... (alternating)
4. 0x55555555... (alternating)
5. 0x9ABC... (mixed pattern)

Returns: True if at most 2 test values are unsatisfiable

Register Utilities

get_reg_name

def get_reg_name(arch, reg_offset) -> str

Finds the register name for a given offset in the register file.

arch · angrop.arch.Arch · required

Architecture instance

reg_offset · int · required

Byte offset in the register file

Returns: Register name

Raises: RegNotFoundException if no register found at offset

Example:

from angrop.arch import get_arch

arch = get_arch(project)
reg_name = get_reg_name(arch, 0)  # "rax" on x64

State Creation

make_initial_state

def make_initial_state(project, stack_gsize) -> angr.SimState

Creates an optimized initial state for ROP analysis.

Features:

• Custom memory plugin (SpecialMem) for faster uninitialized memory
• Symbolic stack of size stack_gsize * arch.bytes
• Optimized angr options for gadget analysis
• 1-second solver timeout

Options enabled:

• CONSERVATIVE_READ_STRATEGY
• AVOID_MULTIVALUED_WRITES
• NO_SYMBOLIC_JUMP_RESOLUTION
• TRACK_ACTION_HISTORY
• TRACK_REGISTER_ACTIONS
• TRACK_MEMORY_ACTIONS

Options disabled:

• AVOID_MULTIVALUED_READS
• SUPPORT_FLOATING_POINT
• All resilience and simplification options

make_symbolic_state

def make_symbolic_state(project, reg_set, stack_gsize, extra_reg_set=None, symbolize_got=False) -> angr.SimState

Creates a symbolic state with specified registers symbolized.

project · angr.Project · required

The angr project

reg_set · set · required

Registers to symbolize (named "sreg_REG-")

stack_gsize · int · required

Symbolic stack size in pointer-sized elements

extra_reg_set · set | None · default: "None"

Additional registers to symbolize (named "esreg_REG-")

symbolize_got · bool · default: "False"

Symbolize the GOT table (for non-FULL RELRO binaries)

Example:

state = make_symbolic_state(
    project, 
    reg_set={'rax', 'rbx', 'rcx'},
    stack_gsize=80
)
# state.regs.rax is now symbolic (BVS("sreg_rax-...", 64))

Execution Control

step_one_inst

def step_one_inst(project, state, stop_at_syscall=False) -> angr.SimState

Steps a state forward by exactly one instruction.

Handles:

• Kernel execution (steps through if not stop_at_syscall)
• Hooked addresses (steps through)

step_to_unconstrained_successor

def step_to_unconstrained_successor(project, state, max_steps=2, allow_simprocedures=False, stop_at_syscall=False) -> angr.SimState

Steps until reaching an unconstrained successor or syscall.

max_steps · int · default: "2"

Maximum steps to take

Returns: State at unconstrained successor or syscall

Raises: RopException if cannot reach unconstrained state

step_to_syscall

def step_to_syscall(state) -> angr.SimState

Steps state forward until just before a syscall instruction.

Returns: State at syscall instruction

Raises: RuntimeError if unable to reach syscall

Address Checking

is_kernel_addr

def is_kernel_addr(project, addr) -> bool

Checks if an address is in kernel space.

Returns: True if the address belongs to the kernel object (cle##kernel)

is_in_kernel

def is_in_kernel(project, state) -> bool

Checks if a state’s instruction pointer is in kernel space.

Timeout Decorator

timeout

@timeout(seconds_before_timeout)
def your_function(...):
    # Your code here

Decorator that raises RopTimeoutException if function exceeds time limit.

Features:

• Uses SIGALRM signal
• Handles nested timeouts (respects shortest timeout)
• Delays timeout during __del__ methods to avoid exceptions during cleanup

Example:

from angrop.rop_utils import timeout
from angrop.errors import RopTimeoutException

@timeout(3)
def analyze_gadget(addr):
    # This will timeout after 3 seconds
    result = expensive_analysis(addr)
    return result

try:
    gadget = analyze_gadget(0x401000)
except RopTimeoutException:
    print("Analysis timed out")

Value Conversion

cast_rop_value

def cast_rop_value(val, project) -> RopValue

Converts a value to a RopValue instance and performs rebase analysis.

bits_extended

def bits_extended(ast) -> int | None

Returns the number of bits added by ZeroExt or SignExt operations.

Example:

# ast = ZeroExt(32, BVS('x', 32))
bits = bits_extended(ast)  # 32

Error Classes

angrop defines custom exceptions in errors.py for fine-grained error handling.

RegNotFoundException

class RegNotFoundException(Exception)

Raised when a register cannot be found at a specified offset.

Example:

from angrop.rop_utils import get_reg_name
from angrop.errors import RegNotFoundException

try:
    reg = get_reg_name(arch, 9999)
except RegNotFoundException as e:
    print(f"Register not found: {e}")

RopException

class RopException(Exception)

Base exception for general ROP analysis errors.

Common scenarios:

• Gadget does not reach unconstrained state
• Cannot get to single successor
• SP change is symbolic or uncontrolled
• Memory access with no dependencies

Example:

from angrop.errors import RopException

try:
    gadget = analyze_complex_gadget(addr)
except RopException as e:
    print(f"Gadget analysis failed: {e}")

RopTimeoutException

class RopTimeoutException(RopException)

Raised when gadget analysis exceeds the timeout limit.

Usage with timeout decorator:

from angrop.rop_utils import timeout
from angrop.errors import RopTimeoutException

@timeout(3)
def slow_analysis(addr):
    # Analysis code
    pass

try:
    slow_analysis(0x401000)
except RopTimeoutException:
    print("Analysis exceeded 3 second timeout")

Common Patterns

Custom Gadget Analysis

from angrop.rop_utils import (
    make_symbolic_state,
    step_to_unconstrained_successor,
    get_ast_dependency,
    get_ast_controllers
)
from angrop.errors import RopException

def analyze_custom_gadget(project, addr, arch):
    # Create symbolic state
    state = make_symbolic_state(
        project,
        reg_set=arch.reg_list,
        stack_gsize=80
    )
    state.ip = addr
    
    try:
        # Step to unconstrained
        final_state = step_to_unconstrained_successor(
            project, state, max_steps=2
        )
        
        # Analyze register effects
        rax_val = final_state.registers.load('rax')
        deps = get_ast_dependency(rax_val)
        controllers = get_ast_controllers(state, rax_val, deps)
        
        return {
            'addr': addr,
            'rax_deps': deps,
            'rax_controllers': controllers
        }
    except RopException as e:
        return None

Memory Access Validation

from angrop.rop_utils import (
    get_ast_dependency,
    get_ast_controllers,
    get_ast_const_offset
)

def analyze_memory_write(state, action):
    addr_ast = action.addr.ast
    data_ast = action.data.ast
    
    # Analyze address
    addr_deps = get_ast_dependency(addr_ast)
    addr_controllers = get_ast_controllers(state, addr_ast, addr_deps)
    addr_offset = get_ast_const_offset(state, addr_ast, addr_deps)
    
    # Analyze data
    data_deps = get_ast_dependency(data_ast)
    data_controllers = get_ast_controllers(state, data_ast, data_deps)
    
    return {
        'addr_controlled_by': addr_controllers,
        'addr_offset': addr_offset,
        'data_controlled_by': data_controllers
    }