Skip to main content
The Shifter class builds ROP chains that shift the stack pointer by specific byte amounts, enabling precise stack manipulation and ret-sled construction.

​
Overview

Accessed through the ROP instance as rop.shift() and rop.retsled(), Shifter automatically:
  • Finds pop chains that shift SP by exact amounts
  • Constructs ret-sleds of arbitrary length
  • Manages stack value placement
  • Supports custom next PC positioning
  • Verifies stack shifts

​
Class Definition

class Shifter(Builder)
Located in angrop/chain_builder/shifter.py

​
Public Methods

​
shift

shift(length, preserve_regs=None, next_pc_idx=-1) -> RopChain
Builds a chain that shifts the stack pointer by a specific number of bytes.
​
length
int
required
Number of bytes to shift the stack (must be word-aligned).
​
preserve_regs
set | None
default:"None"
Set of register names that should not be modified.
​
next_pc_idx
int
default:"-1"
Index (in words) where the next PC should be placed. Supports negative indexing.
  • -1: Next PC at end (default)
  • 0: Next PC at start
  • Positive: Absolute position
Returns: A RopChain that shifts the stack. Raises: RopException if shift cannot be performed.

​
retsled

retsled(size, preserve_regs=None) -> RopChain
Builds a ret-sled of specified size (chain of ret gadgets).
​
size
int
required
Total size in bytes for the ret-sled (must be word-aligned).
​
preserve_regs
set | None
default:"None"
Set of register names that should not be modified.
Returns: A RopChain consisting only of ret gadgets. Raises: RopException if ret-sled cannot be built.

​
verify_shift

verify_shift(chain, length, preserve_regs) -> bool
Verifies that a chain correctly shifts the stack.
​
chain
RopChain
required
Chain to verify.
​
length
int
required
Expected shift amount.
​
preserve_regs
set
required
Registers that should not be modified.
Returns: True if verification passes, False otherwise.

​
verify_retsled

verify_retsled(chain, size, preserve_regs) -> bool
Verifies that a ret-sled has the correct size.
​
chain
RopChain
required
Chain to verify.
​
size
int
required
Expected size in bytes.
​
preserve_regs
set
required
Registers that should not be modified.
Returns: True if verification passes, False otherwise.

​
ROP Instance Methods

rop.shift(length, preserve_regs=None, next_pc_idx=-1)
rop.retsled(size, preserve_regs=None)

​
Implementation Details

​
Shift Gadget Dictionary

Shifter maintains a dictionary mapping stack changes to gadgets: From source code (shifter.py:140-159): 
def filter_gadgets(self, gadgets):
    # Only self-contained gadgets with no memory access
    gadgets = [
        x for x in gadgets
        if x.num_sym_mem_access == 0 and x.self_contained
    ]
    
    gadgets = self._filter_gadgets(gadgets)
    
    # Group by stack_change
    d = defaultdict(list)
    for g in gadgets:
        d[g.stack_change].append(g)
    
    # Sort each group by number of changed registers
    for x in d:
        d[x] = sorted(d[x], key=lambda g: len(g.changed_regs))
    
    return d
Example dictionary: 
{
    8: [pop rax; ret, pop rbx; ret, ...],
    16: [pop rax; pop rbx; ret, pop rdi; pop rsi; ret, ...],
    24: [pop rax; pop rbx; pop rcx; ret, ...],
    ...
}

​
Shift Implementation

From source code (shifter.py:62-110): 
def shift(self, length, preserve_regs=None, next_pc_idx=-1):
    preserve_regs = set(preserve_regs) if preserve_regs else set()
    arch_bytes = self.project.arch.bytes
    
    # Validate alignment
    if length % arch_bytes != 0:
        raise RopException("Cannot shift misaligned sp change")
    
    # Find gadget with exact stack change
    if length not in self.shift_gadgets or \
       all(preserve_regs.intersection(x.changed_regs) 
           for x in self.shift_gadgets[length]):
        raise RopException("Cannot find suitable shift gadget")
    
    # Calculate word count and normalize index
    g_cnt = length // arch_bytes
    next_pc_idx = (next_pc_idx % g_cnt + g_cnt) % g_cnt
    
    # Find compatible gadget
    for g in self.shift_gadgets[length]:
        if preserve_regs.intersection(g.changed_regs):
            continue
        if g.transit_type != 'pop_pc':
            continue
        if g.pc_offset != next_pc_idx * arch_bytes:
            continue
        
        # Build chain with symbolic stack values
        chain = RopBlock(self.project, self)
        state = chain._blank_state
        chain.add_gadget(g)
        
        for idx in range(g_cnt):
            if idx != next_pc_idx:
                # Symbolic stack value
                tmp = claripy.BVS(f"symbolic_stack_{idx}", arch_bits)
                chain.add_value(tmp)
            else:
                # Next PC value
                next_pc_val = rop_utils.cast_rop_value(
                    claripy.BVS("next_pc", arch_bits),
                    self.project
                )
                chain.add_value(next_pc_val)
        
        if self.verify_shift(chain, length, preserve_regs):
            return chain

​
Retsled Implementation

From source code (shifter.py:112-130): 
def retsled(self, size, preserve_regs=None):
    preserve_regs = set(preserve_regs) if preserve_regs else set()
    arch_bytes = self.project.arch.bytes
    
    if size % arch_bytes != 0:
        raise RopException("retsled size must be word aligned")
    
    if not self.shift_gadgets[arch_bytes]:
        raise RopException("Cannot find ret-equivalent gadget")
    
    # Use minimal ret gadget
    for g in self.shift_gadgets[arch_bytes]:
        chain = RopChain(self.project, self.chain_builder)
        for _ in range(size // arch_bytes):
            chain.add_gadget(g)
        
        if self.verify_retsled(chain, size, preserve_regs):
            return chain

​
Usage Examples

​
Basic Stack Shift

import angr
import angrop

proj = angr.Project("/bin/bash")
rop = proj.analyses.ROP()
rop.find_gadgets()

# Shift stack by 32 bytes
chain = rop.shift(32)
chain.pp()
Output: 
0x0000000000410b23: pop rax; pop rbx; pop rcx; pop rdx; ret
                    <symbolic>
                    <symbolic>
                    <symbolic>
                    <symbolic>

​
Shift with Custom Next PC Position

# Next PC at the beginning (index 0)
chain = rop.shift(32, next_pc_idx=0)

# Next PC at position 2 (third word)
chain = rop.shift(32, next_pc_idx=2)

# Next PC at the end (default)
chain = rop.shift(32, next_pc_idx=-1)

​
Stack Arguments for Function Calls

Used internally by FuncCaller for stack arguments: From source code context: 
# Function with stack arguments
if stack_arguments:
    shift_bytes = (len(stack_arguments) + 1) * arch_bytes
    cleaner = rop.shift(shift_bytes, next_pc_idx=-1, 
                       preserve_regs=preserve_regs)
    chain.add_gadget(cleaner._gadgets[0])
    for arg in stack_arguments:
        chain.add_value(arg)
    chain.add_value(next_pc)

​
Ret-Sled

# Create 64-byte ret-sled
chain = rop.retsled(64)
chain.pp()
Output: 
0x0000000000400123: ret
0x0000000000400123: ret
0x0000000000400123: ret
0x0000000000400123: ret
0x0000000000400123: ret
0x0000000000400123: ret
0x0000000000400123: ret
0x0000000000400123: ret

​
NOP Sled Equivalent

# Ret-sled as timing/alignment mechanism
alignment_sled = rop.retsled(24)
main_chain = rop.set_regs(rax=0x1337)
full_chain = alignment_sled + main_chain

​
Preserving Registers During Shift

# Don't clobber rax during shift
chain = rop.shift(32, preserve_regs={'rax'})

​
Stack Cleanup After Function

# Call function with 5 stack args
# Then clean up stack
chain = rop.func_call("big_func", [1, 2, 3, 4, 5, 6, 7])
chain += rop.shift(40)  # Clean up 5 args (5 * 8 bytes)

​
Shift Gadget Patterns

​
Common Patterns by Stack Change

​
8 bytes (1 word)

ret                    ; Minimal shift
pop rax; ret          ; Shift with pop

​
16 bytes (2 words)

pop rax; pop rbx; ret
pop rdi; pop rsi; ret

​
24 bytes (3 words)

pop rax; pop rbx; pop rcx; ret
pop rdi; pop rsi; pop rdx; ret

​
32 bytes (4 words)

pop rax; pop rbx; pop rcx; pop rdx; ret
pop rdi; pop rsi; pop rdx; pop rcx; ret

​
PC Offset Importance

The pc_offset determines where ret pops from: 
; pop rax; pop rbx; ret
; pc_offset = 16 (2 * 8 bytes)
; Stack: [rax][rbx][ret_addr]
;         0    8    16 <- PC here

; For next_pc_idx=0:
; Stack: [ret_addr][rax][rbx]
;         0 <- PC here

​
Verification

From source code (shifter.py:26-42): 
def verify_shift(self, chain, length, preserve_regs):
    arch_bytes = self.project.arch.bytes
    init_sp = chain._blank_state.regs.sp.concrete_value
    state = chain.exec()
    
    # Check SP shifted correctly (+arch_bytes for ret)
    if state.regs.sp.concrete_value != init_sp + length + arch_bytes:
        return False
    
    # Check preserved registers
    for act in state.history.actions:
        if act.type != 'reg' or act.action != 'write':
            continue
        offset = act.offset
        offset -= act.offset % arch_bytes
        reg_name = arch.translate_register_name(offset)
        if reg_name in preserve_regs:
            return False
    
    return True

​
Effect and Comparison Tuples

From source code (shifter.py:132-138): 
def _effect_tuple(self, g):
    v1 = g.stack_change
    v2 = g.pc_offset
    return (v1, v2)

def _comparison_tuple(self, g):
    return (len(g.changed_regs), g.stack_change, 
            rop_utils.transit_num(g), g.isn_count)
This ensures:
  1. Gadgets grouped by stack_change and pc_offset
  2. Within groups, prefer fewer register changes
  3. Then prefer smaller stack changes
  4. Then simpler transit types
  5. Finally fewer instructions

​
Error Handling

​
”Currently, we do not support shifting misaligned sp change”

Raised when length is not word-aligned. Solution: Use multiples of word size: 
# x64: multiples of 8
chain = rop.shift(8)   # OK
chain = rop.shift(16)  # OK
chain = rop.shift(12)  # ERROR

# x86: multiples of 4
chain = rop.shift(4)   # OK
chain = rop.shift(7)   # ERROR

​
“Encounter a shifting request that requires chaining multiple shifting gadgets”

Raised when exact shift amount isn’t available. Solutions:
  1. Try a different shift amount
  2. Use fast_mode=False for more gadgets
  3. Manually chain multiple shifts: 
    chain = rop.shift(32)
chain += rop.shift(16)  # Total: 48 bytes

​
“the size of a retsled must be word aligned”

Raised when retsled size is not aligned. Solution: Use word-aligned sizes.

​
”fail to find a ret-equivalent gadget”

Raised when no simple ret gadget exists. Solution: Very rare; binary likely has unusual structure.

​
Performance Considerations

  • Gadget dictionary is pre-built during bootstrap
  • Shifts are fast (single gadget)
  • Retsleds may be long but simple
  • Verification adds small overhead

​
Architecture Support

  • x86/x86_64: Full support, many pop patterns
  • ARM/ARM64: Full support
  • MIPS: Full support
  • PowerPC: Basic support

​
Advanced Techniques

​
Precise Stack Control

# Need exactly 48 bytes of stack space
chain = rop.shift(48)

# Or combine shifts
chain = rop.shift(32)
chain += rop.shift(16)

​
Custom Stack Layouts

# Place next PC at specific position
# For custom stack frame layouts
chain = rop.shift(40, next_pc_idx=3)
# Stack: [val][val][val][next_pc][val]

​
Ret-Sled for Alignment

# Ensure 16-byte alignment
if (current_offset % 16) != 0:
    padding = 16 - (current_offset % 16)
    chain += rop.retsled(padding)

​
Best Practices

  1. Use for exact amounts: When you need precise stack shifts
  2. Prefer simpler shifts: Fewer words = fewer clobbered registers
  3. Check alignment: Always use word-aligned values
  4. Verify shifts: Use chain.pp() to inspect
  5. Consider alternatives: Sometimes pivot() is better

​
See Also

  • Pivot - Stack pivoting to arbitrary locations
  • FuncCaller - Uses shift for stack arguments
  • ChainBuilder - Main chain building interface

Build docs developers (and LLMs) love

Get started for freeTalk to us