pwntools-debug-operator

name	pwntools-debug-operator
description	Use this when a Codex agent needs to debug a pwn challenge by writing or editing a pwntools exploit script, inserting gdb.attach() at chosen points, and operating the autopwn-session CLI to start, bind, observe, debug, release, and stop tmux-backed pwndbg sessions.
metadata	{"short-description":"Operate autopwn-session for pwntools debugging"}

Pwntools Debug Operator

Use this skill when the task is to actually debug a binary with the installed autopwn-session tool, not to redesign the platform.

Core workflow

1. Start with references/quickstart.md for the minimal end-to-end flow.
2. Before writing the script, confirm the real execution target with ldd and readelf -l. If the binary is already patched to local ld or libc, prefer running the binary directly instead of wrapping it manually.
3. If you need to write or patch the exploit script, copy the pattern from assets/autopwn_bridge.py and the marker contract from references/script-contract.md. Default to an early attach point: gdb.attach() first, then hold("pre"), then drive scripted actions, then hold("post") for inspection.
4. Start the exploit with autopwn-session start.
5. Wait until the script reaches the early attach point, then run autopwn-session bind-debug.
6. Use autopwn-session observe to inspect both tmux panes before sending more commands.
7. Set PIE breakpoints with *$rebase(offset) after the process is live instead of guessing absolute addresses.
8. Use autopwn-session debug-cmd for targeted gdb/pwndbg commands, but prefer stage boundaries and autopwn-session release over long chains of live interactive steering.
9. Use autopwn-session release to unblock hold(tag) gates in the script.
10. Stop the session with autopwn-session stop when the task is done.

What to read when

• Read references/cli-reference.md when you need exact subcommands or output fields.
• Read references/script-contract.md when you need to add emit_pid(), stage(), before_attach(), after_attach(), or hold().
• Read references/failure-modes.md when bind-debug fails, the gdb pane dies, or the script races past the breakpoint.
• Read references/multi-codex.md when several Codex agents share the same challenge directory.
• Read references/runtime-layout.md when you need repository-local paths for the bridge template, session state, or implementation entrypoints.

Extension rule

Do not keep piling logic into repeated debug-cmd calls when the same observation pattern is needed over and over.

Promote it to a structured command when:

• Codex repeatedly sends the same gdb command sequence
• downstream reasoning only needs parsed fields, not raw pane text
• a command should return stable JSON such as registers, memory words, backtrace frames, or current stop location

Prefer adding a new CLI subcommand or session action over teaching every Codex instance to parse free-form gdb text again.