Factory (AngrObjectFactory)

Factory for creating states, blocks, and simulation managers

The AngrObjectFactory (accessed via project.factory) provides convenient access to important angr analysis elements such as states, blocks, simulation managers, and callable functions.

Class Signature

class AngrObjectFactory:
    def __init__(self, project, default_engine: type[SimEngine] | None = None)

Parameters

project · Project

The angr Project instance.

default_engine · type[SimEngine]

The default execution engine to use (defaults to UberEngine).

Attributes

project · Project

The associated angr Project.

default_engine · SimEngine

The default execution engine instance (thread-local).

procedure_engine · ProcedureEngine

The engine for executing SimProcedures.

State Creation Methods

blank_state()

Signature:

def blank_state(
    self,
    addr=None,
    initial_prefix=None,
    fs=None,
    concrete_fs=False,
    chroot=None,
    **kwargs
) -> SimState

Returns a mostly-uninitialized state object.

Parameters:

addr · int

The address the state should start at instead of the entry point.

initial_prefix · str

If provided, all symbolic registers will hold symbolic values with names prefixed by this string.

fs · dict

A dictionary of file names with associated preset SimFile objects.

concrete_fs · bool · default: "False"

Whether the host filesystem should be consulted when opening files.

chroot · str

A path to use as a fake root directory (only when concrete_fs is True).

Returns: SimState - The blank state.

Example:

state = proj.factory.blank_state(addr=0x400000)

entry_state()

Signature:

def entry_state(
    self,
    addr=None,
    initial_prefix=None,
    fs=None,
    concrete_fs=False,
    chroot=None,
    argc=None,
    args=None,
    env=None,
    **kwargs
) -> SimState

Returns a state object representing the program at its entry point.

Parameters:

addr · int

Start address instead of the entry point.

argc · int | claripy.ast.BV

Custom value for the program’s argc.

args · list[str | bytes | claripy.ast.BV]

List of values to use as the program’s argv.

env · dict[str | bytes, str | bytes]

Dictionary to use as the environment.

Returns: SimState - The entry state.

Example:

state = proj.factory.entry_state(
    args=['./program', 'arg1', 'arg2'],
    env={'PATH': '/usr/bin'}
)

full_init_state()

Signature:

def full_init_state(self, **kwargs) -> SimState

Like entry_state(), but starts at a SimProcedure that plays the role of the dynamic loader, calling initializer functions before reaching the entry point.

Takes the same arguments as entry_state(), except for addr.

Returns: SimState - The fully initialized state.

Example:

state = proj.factory.full_init_state()

call_state()

Signature:

def call_state(
    self,
    addr,
    *args,
    base_state=None,
    cc=None,
    ret_addr=None,
    stack_base=None,
    alloc_base=None,
    grow_like_stack=True,
    toc=None,
    **kwargs
) -> SimState

Returns a state initialized to the start of a given function, as if it were called with given parameters.

Parameters:

addr · int

The address of the function to call.

args · Any

Positional arguments to pass to the function. Can be python types, which will be converted to binary format.

base_state · SimState

Use this SimState as the base instead of a blank state.

cc · SimCC

A SimCC object specifying the calling convention.

ret_addr · int

The function’s return target address.

stack_base · int

Pointer to use as the top of the stack.

alloc_base · int

Pointer for placing excess argument data.

grow_like_stack · bool · default: "True"

Whether allocations at alloc_base grow downward.

toc · int

The address of the table of contents for ppc64.

Returns: SimState - The state at the beginning of the function.

Example:

# Call function with arguments
state = proj.factory.call_state(
    0x400500,
    10,  # First argument
    "hello",  # Second argument (will be a pointer to string)
    ret_addr=0x400600
)

Simulation Manager Methods

simulation_manager() / simgr()

Signature:

def simulation_manager(
    self,
    thing: list[SimState] | SimState | None = None,
    **kwargs
) -> SimulationManager

Constructs a new simulation manager.

Parameters:

thing · SimState | list[SimState] | None

What to put in the new SimulationManager’s active stash. If None, uses entry_state().

Returns: SimulationManager - The new simulation manager.

Example:

# From entry state
simgr = proj.factory.simgr()

# From custom state
state = proj.factory.blank_state(addr=0x400000)
simgr = proj.factory.simgr(state)

# From multiple states
states = [state1, state2, state3]
simgr = proj.factory.simgr(states)

Note: simgr() is an alias for simulation_manager().

Block Methods

block()

Signature:

def block(
    self,
    addr,
    size=None,
    max_size=None,
    byte_string=None,
    thumb=False,
    backup_state=None,
    extra_stop_points=None,
    opt_level=None,
    num_inst=None,
    traceflags=0,
    insn_bytes=None,
    strict_block_end=None,
    collect_data_refs=False,
    cross_insn_opt=True,
    load_from_ro_regions=False,
    const_prop=False,
    initial_regs=None,
    skip_stmts=False,
) -> Block

Create a Block object representing a basic block of code.

Parameters:

addr · int

The address of the block.

size · int

The size of the block in bytes.

byte_string · bytes

Custom bytes to use instead of reading from memory.

thumb · bool · default: "False"

Whether this is ARM Thumb mode.

num_inst · int

Maximum number of instructions to lift.

opt_level · int

VEX optimization level (0-2).

Returns: Block - The block object.

Example:

block = proj.factory.block(0x400000)
print(f"Block has {block.instructions} instructions")
block.pp()  # Pretty-print disassembly

fresh_block()

Signature:

def fresh_block(self, addr, size, backup_state=None) -> Block

Create a fresh Block with a specific size.

Parameters:

addr · int

The address of the block.

size · int

The size of the block.

backup_state · SimState

State to read bytes from.

Returns: Block

Callable Methods

callable()

Signature:

def callable(
    self,
    addr: int | Function,
    prototype=None,
    concrete_only=False,
    perform_merge=True,
    base_state=None,
    toc=None,
    cc=None,
    add_options=None,
    remove_options=None,
    techniques: list[ExplorationTechnique] | None = None,
    step_limit: int | None = None,
) -> Callable

Create a Callable object that represents a function in the binary that can be called like a native Python function.

Parameters:

addr · int | Function

The address of the function (or a Function object).

prototype · str | SimTypeFunction

The prototype of the call as a string or SimTypeFunction.

concrete_only · bool · default: "False"

Throw an exception if execution splits into multiple states.

perform_merge · bool · default: "True"

Merge all result states into one at the end.

base_state · SimState

The state from which to do runs.

cc · SimCC

The calling convention to use.

step_limit · int

Maximum number of blocks to execute before pruning.

Returns: Callable - A callable object.

Example:

# Get a function
func = proj.kb.functions['main']

# Make it callable
main_callable = proj.factory.callable(func.addr)

# Call it like a Python function
result = main_callable(arg1=10, arg2=20)
print(f"Function returned: {result}")

Calling Convention Methods

cc()

Signature:

def cc(self) -> SimCC

Return a SimCC (calling convention) object parameterized for this project.

Returns: SimCC - The calling convention object.

Example:

cc = proj.factory.cc()

# Access argument locations
arg0 = cc.ARG_REGS[0]  # First argument register

# Create custom arguments
from angr.calling_conventions import SimRegArg, SimStackArg

reg_arg = SimRegArg('rdi', 8)
stack_arg = SimStackArg(0, 8)  # 8 bytes at offset 0 from SP

function_prototype()

Signature:

def function_prototype(self) -> SimTypeFunction

Return a default function prototype parameterized for this project.

Returns: SimTypeFunction - A default function prototype.

Other Methods

successors()

Signature:

def successors(
    self,
    state,
    engine=None,
    addr=None,
    jumpkind=None,
    inline=False,
    **kwargs
) -> SimSuccessors

Perform execution using an engine and return a SimSuccessors object.

Parameters:

state · SimState

The state to analyze.

engine · SimEngine

The engine to use (defaults to default_engine).

addr · int

An address to execute at instead of the state’s IP.

jumpkind · str

The jumpkind of the previous exit.

inline · bool · default: "False"

Don’t copy the state (inline execution).

Returns: SimSuccessors - Object containing successor states.

snippet()

Signature:

def snippet(self, addr, jumpkind=None, **block_opts) -> CodeNode

Create a CodeNode (HookNode, SyscallNode, or BlockNode) for the given address.

Parameters:

addr · int

The address of the snippet.

Returns: CodeNode - The code node.

Helper Classes

The factory provides access to helper classes:

SimRegArg and SimStackArg

# Access via factory.cc
factory.cc.SimRegArg
factory.cc.SimStackArg

PointerWrapper

# Access via factory.callable or factory.call_state
factory.callable.PointerWrapper
factory.call_state.PointerWrapper

# Usage in call_state
state = proj.factory.call_state(
    addr=0x400000,
    factory.call_state.PointerWrapper("hello")  # Pass pointer to string
)

Example Usage

import angr

proj = angr.Project('/bin/ls')
factory = proj.factory  # Usually accessed as proj.factory

# Create different types of states
blank = factory.blank_state()
entry = factory.entry_state(args=['./ls', '-la'])
full = factory.full_init_state()
call = factory.call_state(0x400500, 10, 20)

# Create simulation manager
simgr = factory.simgr(entry)
simgr.run()

# Create and analyze blocks
block = factory.block(proj.entry)
print(f"Entry block has {block.instructions} instructions")

# Create callable function
func_addr = proj.kb.functions['main'].addr
main = factory.callable(func_addr, prototype='int main(int argc, char **argv)')
result = main(2, ['./program', 'arg'])

# Access calling convention
cc = factory.cc()
print(f"First arg register: {cc.ARG_REGS[0]}")

# Execute a state
successors = factory.successors(entry)
for s in successors.successors:
    print(f"Successor at {s.addr:#x}")