litclaude-ai 0.2.2

package/plugins/litclaude/skills/debugging/references/tools/pwndbg.md

@@ -0,0 +1,263 @@
+# pwndbg — GDB With the Useful Views Always On
+
+**https://github.com/pwndbg/pwndbg**
+
+pwndbg is a GDB plugin that turns GDB into something humans can actually use for binary debugging. It's strictly a superset of plain GDB — every vanilla GDB command still works, and pwndbg adds views and commands that make you productive.
+
+**If you'd reach for plain `gdb`, reach for pwndbg instead.** The only reason not to is if pwndbg isn't installed on the machine, and that's a 2-minute fix.
+
+---
+
+## Install
+
+```bash
+# macOS
+brew install pwndbg
+# Or from source:
+git clone https://github.com/pwndbg/pwndbg
+cd pwndbg && ./setup.sh
+
+# Linux
+# Most distros: apt/dnf/pacman install pwndbg (check availability)
+# Or the same git + ./setup.sh
+
+# Verify
+gdb --version
+gdb ./any-binary
+# At gdb prompt, you should see pwndbg banner + colorful context view
+```
+
+Once installed, pwndbg auto-loads every time you start `gdb`. You don't source anything manually.
+
+---
+
+## The `context` view — the one feature that changes everything
+
+Plain GDB: you run `info registers`, then `bt`, then `x/10xw $rsp`, then `disas`. Four commands to see what's going on.
+
+pwndbg: `context` (or it auto-shows at every break). One command. Everything on screen:
+
+```
+──── registers ────
+ RAX  0x0
+ RBX  0x7ffffffde158
+ RCX  0x7fffff7abf10
+ ...
+──── disasm ────
+ ► 0x401234  mov rdi, rax
+   0x401237  call 0x401190
+   ...
+──── stack ────
+ 00:0000│ rsp 0x7ffffffde0a0 → 0x7fffff7c4000
+ 01:0008│     0x7ffffffde0a8 → 0x0
+ ...
+──── backtrace ────
+ ► f 0  0x401234 parse_input+0x3c
+   f 1  0x401180 main+0x120
+   f 2  0x7fffff7a5083 __libc_start_main+0xf3
+```
+
+You always know where you are, what the CPU state is, what's on the stack, and how you got here. This is why pwndbg is the default.
+
+---
+
+## Launch recipes
+
+```bash
+# Debug an existing binary
+gdb ./target
+
+# With args
+gdb --args ./target arg1 arg2
+
+# Attach to a running process
+gdb -p $(pgrep target)
+
+# With a core dump
+gdb ./target ./core
+
+# Headless / remote (for automation or IDE attach)
+gdbserver :2345 ./target                  # on the target box
+gdb ./target                              # on your box
+(gdb) target remote <host>:2345
+```
+
+At the pwndbg prompt:
+
+---
+
+## Essential commands (pwndbg additions)
+
+### Layout / view
+
+```
+context                        # reprint the context view (usually auto)
+context regs stack              # only show registers + stack sections
+tel $rsp 20                     # telescope — walk pointers at $rsp for 20 slots (KEY COMMAND)
+tel $rdi 10                     # walk pointers at $rdi (e.g. to dump a struct)
+stack 20                        # 20 entries of stack
+vmmap                           # virtual memory map of the process
+```
+
+**`telescope` is pwndbg's killer command.** Given an address, it walks pointers recursively:
+```
+00:0000│   0x7ffd... → 0x601010  (heap) → 0x2a (unknown, i.e. a number 42)
+01:0008│   0x7ffd... → 0x7fff... (stack) → 'hello world'
+```
+This single view resolves 80% of "what is at this address" questions.
+
+### Heap debugging
+
+```
+heap                            # overview of chunks
+bins                            # tcache / fastbin / unsorted / smallbin / largebin state
+malloc_chunk <addr>             # inspect a specific chunk
+find_fake_fast <addr>           # (exploit context) find fake-fast overlap candidates
+vis_heap_chunks                 # visualize heap layout
+```
+
+For use-after-free / double-free / heap overflow hypotheses, `heap` + `bins` is usually sufficient to see the corruption.
+
+### Exploitation-adjacent (useful for bug understanding too)
+
+```
+checksec                        # NX, PIE, RELRO, canary status
+rop --grep 'pop rdi'            # find ROP gadgets
+nx                              # step over (aliased nicely)
+ni                              # step over single instruction
+si                              # step into single instruction
+```
+
+### Search
+
+```
+search -t byte 0x41             # find byte 0x41 anywhere in memory
+search -t string "admin"        # find string
+search -p <addr>                # find pointers to <addr>
+```
+
+---
+
+## Standard GDB commands still work
+
+pwndbg doesn't replace GDB; it augments it. Everything you know still works:
+
+```
+break main                      # breakpoint at function
+b *0x401234                     # breakpoint at address
+b file.c:42                     # breakpoint at file:line
+c                               # continue
+n                               # next (source-level step over)
+s                               # step (source-level step into)
+finish                          # step out
+info breakpoints                # list breakpoints
+delete <n>                      # delete breakpoint
+watch <var>                     # break on write to variable
+rwatch <var>                    # break on read
+awatch <var>                    # break on access
+p <expr>                        # print expression
+p/x <expr>                      # print in hex
+x/20xw <addr>                   # examine 20 words as hex
+bt                              # backtrace
+frame <n>                       # switch frame
+info registers                  # registers (but `context` is better)
+disassemble <func>              # disasm a function
+```
+
+---
+
+## Python scripting inside GDB
+
+pwndbg exposes a full Python API. Useful for automating observations across many breakpoints:
+
+```python
+(gdb) python
+import gdb
+def on_break():
+    frame = gdb.selected_frame()
+    pc = frame.read_register('pc')
+    print(f'hit at {hex(int(pc))}')
+    # Dump args, locals, anything
+end
+```
+
+Or scripted runs from outside:
+```bash
+gdb -batch -ex 'source script.gdb' -ex 'run' ./target
+```
+
+---
+
+## Common workflows by bug type
+
+### Segfault / crash
+
+```bash
+gdb ./target
+(gdb) run <args>
+# ... crash ...
+(gdb) context                    # see the crash site
+(gdb) bt                         # how did we get here?
+(gdb) info registers             # what state
+(gdb) tel $rsp 20                # what's on the stack
+```
+
+### "Function returns wrong value"
+
+```bash
+gdb ./target
+(gdb) break <function>
+(gdb) run <args>
+# At breakpoint:
+(gdb) finish                     # let it run to the return
+# pwndbg shows RAX (return value) in context
+```
+
+### "Variable has unexpected value at point X"
+
+```bash
+gdb ./target
+(gdb) break <point-X>
+(gdb) run
+# At breakpoint:
+(gdb) p <var>                    # its value
+(gdb) watch <var>                # set a watchpoint — break when it changes
+(gdb) c                          # continue; next stop is where it was modified
+```
+
+### "Memory corruption / heap bug"
+
+```bash
+gdb ./target
+(gdb) run
+# Crash at free():
+(gdb) heap                       # heap state
+(gdb) bins                       # bin state — often shows corruption here
+(gdb) vis_heap_chunks            # visualize
+(gdb) malloc_chunk <suspicious-addr>
+```
+
+---
+
+## Gotchas
+
+- **`bt` looks weird on stripped binaries** — function names become offsets. Use Ghidra's function labels to map back (see [ghidra.md](ghidra.md)).
+- **PIE binaries have randomized base addresses.** Addresses you see in Ghidra are unslid; addresses in pwndbg are slid. The `vmmap` command shows the base, and pwndbg's `piebase` command gives you the offset.
+- **Optimized builds inline functions.** You'll set a breakpoint on `my_function` and it won't hit because the function was inlined. Either disable optimizations or break on callers.
+- **Stack canaries trigger `__stack_chk_fail`.** If you see that in a backtrace, the bug caused a stack-smash; look one frame up.
+
+---
+
+## Phase 9 cleanup specifics
+
+```bash
+# Kill gdb / pwndbg sessions
+pkill -f 'gdb' || true
+pkill -f 'gdbserver' || true
+
+# Remove core dumps generated during session
+rm -f ./core ./core.* ~/core.*
+
+# Remove any scripted GDB files
+rm -f /tmp/debug-*.gdb
+```

package/plugins/litclaude/skills/debugging/references/tools/pwntools.md

@@ -0,0 +1,265 @@
+# 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)
+```