Shifter

Stack shifting chain builder for adjusting stack pointer by specific amounts

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