ROP

Core ROP gadget finder and chain builder class

The ROP class is angrop’s primary interface for semantic-aware ROP gadget discovery and chain building. It extends angr’s Analysis class and provides methods for finding gadgets, managing them, and building exploit chains.

Class Definition

class ROP(Analysis)

Semantic-aware ROP gadget finder that analyzes binary code to discover exploitable gadgets and build ROP chains.

Constructor

ROP(only_check_near_rets=True, max_block_size=None, max_sym_mem_access=None,
    fast_mode=None, rebase=None, is_thumb=False, kernel_mode=False, 
    stack_gsize=80, cond_br=False, max_bb_cnt=2)

only_check_near_rets · bool · default: "True"

If true, skip blocks that are not near ret instructions. This significantly speeds up gadget finding.

max_block_size · int | None · default: "None"

Limits the size of blocks considered. Longer blocks are less likely to be good ROP gadgets.

max_sym_mem_access · int | None · default: "None"

Maximum number of symbolic memory accesses to allow in a gadget.

fast_mode · bool | None · default: "None"

When True, skip gadgets with conditional branches, floating point operations, and jumps. Allows smaller gadget size. If None, automatically decides based on binary size.

rebase · any · default: "None"

Deprecated. This parameter is no longer used in angrop.

is_thumb · bool · default: "False"

Execute ROP chain in ARM Thumb mode. Only affects ARM architecture. angrop does not switch modes within a chain.

kernel_mode · bool · default: "False"

Find kernel mode gadgets instead of user mode gadgets.

stack_gsize · int · default: "80"

Maximum allowable stack change for gadgets. Max stack_change = stack_gsize * arch.bytes.

cond_br · bool · default: "False"

Whether to support conditional branches. This option significantly impacts gadget finding speed.

max_bb_cnt · int · default: "2"

Maximum basic block count to consider in gadgets.

Attributes

After calling find_gadgets(), find_gadgets_single_threaded(), or load_gadgets(), the following attributes are populated:

rop_gadgets · list[RopGadget]

List of gadgets used for ROP operations (e.g., pop rax; ret).

pivot_gadgets · list[PivotGadget]

List of gadgets used for stack pivoting (e.g., mov rsp, rbp; ret).

syscall_gadgets · list[SyscallGadget]

List of gadgets used for invoking system calls (e.g., syscall; ret or int 0x80; ret).

badbytes · list[int]

List of bytes that should not appear in generated ROP chains.

roparg_filler · int | None

Integer value used when popping useless registers. If None, symbolic values are used.

arch · RopArch

Architecture object from the gadget finder.

Gadget Discovery Methods

find_gadgets

find_gadgets(optimize=True, **kwargs) -> list[RopGadget]

Finds all gadgets in the binary using multiple processes.

optimize · bool · default: "True"

Whether to run chain_builder.optimize(). This may take time but makes the chain builder more powerful.

processes · int · default: "4"

Number of processes to use for parallel gadget analysis.

show_progress · bool · default: "True"

Whether to display a progress bar during gadget finding.

Returns: List of discovered ROP gadgets.

find_gadgets_single_threaded

find_gadgets_single_threaded(show_progress=True, optimize=True) -> list[RopGadget]

Finds all gadgets in the binary using a single thread. Useful for debugging or when multiprocessing causes issues.

show_progress · bool · default: "True"

Whether to display a progress bar.

optimize · bool · default: "True"

Whether to run chain_builder.optimize().

Returns: List of discovered ROP gadgets.

analyze_gadget

analyze_gadget(addr) -> RopGadget | None

Analyzes a specific address to identify if it’s a valid ROP gadget. Filters out gadgets containing conditional branches.

addr · int · required

Address to analyze.

Returns: RopGadget object if valid, None otherwise.

analyze_addr

analyze_addr(addr) -> list[RopGadget] | None

Analyzes an address and returns all possible gadgets starting from that address. This includes gadgets with conditional branches.

addr · int · required

Address to analyze.

Returns: List of RopGadget objects or None.

analyze_gadget_list

analyze_gadget_list(addr_list, processes=4, show_progress=True, optimize=True) -> list[RopGadget]

Analyzes a list of addresses to identify ROP gadgets.

addr_list · list[int] · required

List of addresses to analyze.

processes · int · default: "4"

Number of processes to use.

show_progress · bool · default: "True"

Whether to show progress bar.

optimize · bool · default: "True"

Whether to optimize the chain builder.

Returns: List of discovered ROP gadgets.

Gadget Management Methods

save_gadgets

save_gadgets(path)

Saves discovered gadgets to a file using pickle serialization.

path · str · required

Path to the file where gadgets will be stored.

load_gadgets

load_gadgets(path, optimize=True)

Loads gadgets from a previously saved file.

path · str · required

Path to the file containing saved gadgets.

optimize · bool · default: "True"

Whether to optimize the chain builder after loading.

Configuration Methods

set_badbytes

set_badbytes(badbytes)

Define bytes that should not appear in the generated ROP chain.

badbytes · list[int] · required

List of 8-bit integers representing bad bytes (e.g., [0x00, 0x09] for null and tab).

get_badbytes

get_badbytes() -> list[int]

Returns: List of currently configured bad bytes.

set_roparg_filler

set_roparg_filler(roparg_filler)

Define the filler value used when ROP chains need to pop useless registers.

roparg_filler · int | None · required

Integer value to use as filler, or None to use symbolic values (constraint solver will choose, usually 0).

Chain Building Methods

All public methods from ChainBuilder are automatically exposed through the ROP instance after gadgets are found. These include:

• set_regs() - Set register values
• move_regs() - Move values between registers
• write_to_mem() - Write data to memory
• func_call() - Call a function with arguments
• do_syscall() - Invoke a system call
• execve() - Execute execve syscall
• pivot() - Perform stack pivot
• And more…

See the ChainBuilder documentation for details.

Example Usage

import angr

# Load binary
project = angr.Project('/bin/ls')

# Create ROP instance
rop = project.analyses.ROP()

# Find gadgets
rop.find_gadgets()

# Set bad bytes
rop.set_badbytes([0x00, 0x0a])

# Build a chain to set registers
chain = rop.set_regs(rax=0x1234, rbx=0x5678)

# Print the chain
chain.print_payload_code()

# Save gadgets for later use
rop.save_gadgets('gadgets.cache')

Internal Properties

chain_builder · ChainBuilder

Property that returns the ChainBuilder instance. Created lazily on first access. All ChainBuilder public methods are copied to the ROP instance.