240 lines
9.6 KiB
Markdown
240 lines
9.6 KiB
Markdown
# llmdbg
|
||
|
||
A scriptable, stateful debugger REPL with JavaScript as the interface language.
|
||
Built from the spec in [`SPEC.md`](./SPEC.md). This repo holds the v0.1–v0.6
|
||
implementation: enough to actually drive a debugged process from an agent
|
||
harness with breakpoints, disassembly, and symbol-aware addresses.
|
||
|
||
The premise: existing debuggers optimise for humans at a terminal. An LLM
|
||
agent is a different user — it wants terse output it can parse, lazy state
|
||
access, and a scripting layer rich enough that "describe what you want to see
|
||
each step" is the natural interface. The full motivation is in `SPEC.md`.
|
||
|
||
## Status
|
||
|
||
| Version | What landed |
|
||
|---|---|
|
||
| v0.1 | Spawn, step, continue, basic state (pc/sp/regs/memory), persistent `ctx`, `print()`, JS prelude loaded via `include_str!` |
|
||
| v0.2 | `prev` register snapshot before each resume; refactored register accessors |
|
||
| v0.3 | ELF symbol parsing of main exe; `sym(addr)` / `addr(name)` / `symbols()`; `addrstr` / `here` prelude helpers |
|
||
| v0.4 | INT3 software breakpoints with by-name/by-id ops; auto disarm-step-rearm; RIP rewind on hit |
|
||
| v0.5 | x86-64 disassembly via `iced-x86`; `read_mem_pristine()` overlays original bytes through active INT3s; branch targets get symbolised |
|
||
| v0.6 | `state.stack`; `until(loc)`; `finish()`; `show.{disasm,bp,regs}` prelude helpers |
|
||
|
||
Each `vN` corresponds to one git commit. See `git log --oneline`.
|
||
|
||
## Not yet implemented
|
||
|
||
The spec calls for these; they're deliberately deferred:
|
||
|
||
- Event listener system (`addEventListener('step', ...)` etc.) — current model
|
||
is synchronous send-script-get-output; events come next.
|
||
- `attach(pid)` — only `spawn` works today.
|
||
- Hardware watchpoints.
|
||
- Source-level debugging via DWARF (`gimli`).
|
||
- Multi-threaded targets; shared-library symbol resolution.
|
||
- Browser visualisation / DOM API.
|
||
- Conditional breakpoints.
|
||
- The `--summary` mode for batch stepping.
|
||
- Reverse execution.
|
||
|
||
The complete "what not yet" list is in `SPEC.md`.
|
||
|
||
## Build
|
||
|
||
Requires a Linux x86-64 host with `ptrace` permitted (no yama `ptrace_scope`
|
||
restriction in the way) and a recent stable Rust toolchain (1.87+).
|
||
|
||
```bash
|
||
cargo build # debug
|
||
cargo build --release # ~3-5x faster
|
||
```
|
||
|
||
QuickJS builds via `rquickjs-sys`'s pre-generated bindings; no `libclang` or
|
||
`bindgen` needed on the supported platforms.
|
||
|
||
## Run
|
||
|
||
The binary is a daemon. It reads JS scripts from stdin and writes results to
|
||
stdout, with sentinels separating turns:
|
||
|
||
```
|
||
$ ./target/debug/llmdbg <<'EOF'
|
||
spawn("/tmp/testprog")
|
||
bp.set("main")
|
||
cont()
|
||
show.disasm(5)
|
||
---END---
|
||
EOF
|
||
```
|
||
|
||
Protocol:
|
||
|
||
- Read lines until a line containing exactly `---END---`.
|
||
- Evaluate the accumulated buffer as one JS script in the persistent context.
|
||
- Print: any `print()` output, then the final expression's value (when not
|
||
`undefined`), or `error: ...` if the eval threw.
|
||
- Print `---DONE---` and flush.
|
||
- Repeat.
|
||
- EOF on stdin exits cleanly. If a target is still alive, it gets SIGKILL'd.
|
||
|
||
## Quick tour
|
||
|
||
A representative session against a small C program:
|
||
|
||
```js
|
||
spawn("/tmp/testprog")
|
||
bp.set("main")
|
||
bp.set("add", "add_bp")
|
||
show.bp()
|
||
// #1 0x55ca2862c1e8 (main) hits=0 enabled
|
||
// #2 "add_bp" 0x55ca2862c149 (add) hits=0 enabled
|
||
---END---
|
||
|
||
cont() // -> "breakpoint:1"
|
||
here() // -> 0x55ca2862c1e8 (main)
|
||
show.disasm(5)
|
||
// 0x55ca2862c1e8 f30f1efa endbr64
|
||
// 0x55ca2862c1ec 55 push rbp
|
||
// ...
|
||
---END---
|
||
|
||
cont() // -> "breakpoint:2"
|
||
here() // -> 0x55ca2862c149 (add)
|
||
show.regs(["rip","rdi","rsi"]) // (rdi, rsi are the first two args)
|
||
// rip=0x55... rdi=0x5 rsi=0x1
|
||
---END---
|
||
|
||
step(5)
|
||
finish() // -> "breakpoint:N", back at caller
|
||
state.registers.rax & 0xffffffffn // -> 0x6 (the eax return value)
|
||
---END---
|
||
|
||
cont() // -> "exited:0"
|
||
---END---
|
||
```
|
||
|
||
## The native surface
|
||
|
||
Everything below is installed in the global scope by the Rust side. The JS
|
||
prelude (`src/prelude.js`) adds the helpers listed at the bottom.
|
||
|
||
```js
|
||
// Process control
|
||
spawn(path, ...args) // -> { pid, status: "stopped_at_entry" }
|
||
step(n = 1) // -> stop-reason string
|
||
cont() // -> stop-reason string (NOT `continue` — JS keyword)
|
||
|
||
// Stop reasons (returned as strings):
|
||
// "step", "breakpoint:N", "signal:SIGSEGV", "exited:0", "killed:SIGKILL"
|
||
|
||
// Live state (each property re-reads via ptrace on access)
|
||
state.pc // -> BigInt
|
||
state.sp // -> BigInt
|
||
state.registers // -> { rax, rbx, ..., r15, eflags } all BigInt
|
||
state.memory(addr) // -> { u8(), u32(), u64(), i64(), bytes(n) }
|
||
state.disasm(n = 8) // -> [{addr, bytes, text, target?, target_sym?}]
|
||
state.stack // -> { top, usable_base, guard_size }
|
||
|
||
// Snapshot before the most recent step/cont — same shape as state for regs.
|
||
// Throws if no step has happened yet.
|
||
prev.pc / prev.sp / prev.registers
|
||
|
||
// Symbols (main exe only; shared libs deferred)
|
||
sym(addr) // -> "name+0xN" | "name" | null
|
||
addr(name) // -> BigInt | null
|
||
symbols() // -> { count, load_base, path }
|
||
disasm(addr, n = 8) // -> same shape as state.disasm
|
||
|
||
// Breakpoints (`breakpoint` and `bp` are the same object)
|
||
bp.set(addr_or_symbol, name?) // -> id
|
||
bp.remove(id_or_name)
|
||
bp.list() // -> [{id, addr, name, hits, enabled}]
|
||
|
||
// User scratchpad (persistent across all evals)
|
||
ctx.something = whatever
|
||
```
|
||
|
||
## Prelude (`src/prelude.js`)
|
||
|
||
Pure JS, loaded last so it can reference the natives. Edit it freely; it gets
|
||
re-embedded into the binary on every `cargo build` via `include_str!`.
|
||
|
||
```js
|
||
hex(v) // -> "0x..." for Number or BigInt
|
||
unhex(s) // -> BigInt (handles "0x", case, sign)
|
||
dump(label, v) // -> print one terse "label\tvalue" line
|
||
repr(v) // -> string form; hex for numerics, JSON for objects
|
||
addrstr(v) // -> "0xN (sym+0xoff)" when sym is known, else "0xN"
|
||
here(label?) // -> print addrstr(state.pc), optionally labelled
|
||
|
||
until(loc) // one-shot bp at addr-or-symbol, cont, cleanup
|
||
finish() // until([rbp+8]) — assumes frame pointer
|
||
|
||
show.disasm(n=8, [at])
|
||
show.bp()
|
||
show.regs([keys])
|
||
```
|
||
|
||
## Architecture
|
||
|
||
```
|
||
src/
|
||
├── main.rs ─ stdin read loop, ---END--- framing, SIGKILL on exit
|
||
├── target.rs ─ ptrace child management: spawn, step, cont, regs,
|
||
│ process_vm_readv, breakpoint patching (read-byte+poke-byte
|
||
│ via PEEKDATA/POKEDATA word RMW)
|
||
├── symbols.rs ─ ELF parsing via `object`; PIE load-base from /proc/maps;
|
||
│ StackRegion from /proc/maps
|
||
├── breakpoint.rs ─ BreakpointSet storage (by id, by addr, by name)
|
||
├── disasm.rs ─ thin wrapper around iced-x86 FastFormatter; emits records
|
||
│ with branch_target for caller symbolisation
|
||
├── js.rs ─ Runtime + Context + Rc<RefCell<Option<Target>>>;
|
||
│ installs all native globals, then evals prelude.js
|
||
└── prelude.js ─ embedded at compile time
|
||
```
|
||
|
||
### A few decisions worth knowing
|
||
|
||
- **BigInt for u64.** A JS Number above 2⁵³ loses precision, which is exactly
|
||
the range we live in. `state.pc`, `addr(...)`, anything 64-bit goes in and
|
||
out as BigInt. `state.memory(addr).u8()` and `.u32()` stay as Number.
|
||
- **Lazy state.** Every access to `state.pc` does a fresh `PTRACE_GETREGS`;
|
||
every `state.memory(...)` does a fresh `process_vm_readv`. A script that
|
||
touches three fields makes three syscalls, not 20. Worth it for scripts; the
|
||
cache would just be a footgun once you have multi-threaded targets.
|
||
- **`continue()` doesn't exist.** `continue` is a reserved keyword in JS, so
|
||
the natural name is a parse error. The spec's `continue()` is `cont()` here.
|
||
- **Single QuickJS context for the daemon's lifetime.** `ctx` (the JS
|
||
scratchpad), registered listeners (when they land), and any user-defined
|
||
helpers all persist. Only resets on daemon restart.
|
||
- **Read-modify-write breakpoint patching.** `ptrace::write` writes a full
|
||
word. We `ptrace::read` first, modify byte 0, write the word back. The other
|
||
seven bytes stay unchanged because we just read them.
|
||
- **`read_mem_pristine`.** Used by the disassembler so it sees the *original*
|
||
byte, not 0xCC, at active breakpoints. Without this, a `disasm` over a bp'd
|
||
function shows `int3; ...` at the first byte.
|
||
- **PIE load base.** Computed as `mapping_base - mapping_file_offset` of the
|
||
*first* mapping of the executable in `/proc/<pid>/maps`. Earlier versions
|
||
used the first executable mapping and dropped the file offset, which is
|
||
wrong on toolchains that split read-only header pages.
|
||
|
||
## Caveats
|
||
|
||
- Linux x86-64 only. No multi-arch, no other OSes.
|
||
- Single-threaded debuggees. A pthread'd binary will behave oddly the moment a
|
||
non-main thread does anything.
|
||
- Symbols only cover the main executable. Shared-library functions (e.g.
|
||
`printf`, `malloc`) resolve to `null` until ld.so awareness lands.
|
||
- `finish()` assumes a frame pointer (`-fno-omit-frame-pointer`, which is the
|
||
default on most distros). It will throw if `rbp == 0`.
|
||
- The sandbox guard-page detection in `state.stack.guard_size` returns 0 on
|
||
Linux configurations where the kernel handles guard implicitly without an
|
||
anonymous `---p` mapping below the stack. That's most modern setups.
|
||
- No `attach(pid)` yet — only spawn.
|
||
|
||
## License
|
||
|
||
Personal experiment, no license declared. Treat as all-rights-reserved by the
|
||
author until otherwise noted.
|