Skip to main content
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us