From 23847b21ac7c382ec56df11dd71565580b3132c8 Mon Sep 17 00:00:00 2001 From: Andrew Haberlandt Date: Thu, 26 Dec 2024 04:18:15 -0500 Subject: [PATCH] docs: improve readme api docs --- README.md | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 234187d..aaaf8d6 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,9 @@ pyda examples/ltrace.py -- ls ``` ### API -You can view all of the available APIs in [process.py](https://github.com/ndrewh/dynamorio-tool/blob/master/lib/pyda/process.py), but in summary: +You can view all of the available APIs in [process.py](https://github.com/ndrewh/pyda/blob/master/lib/pyda/process.py), but in summary: + +Read/Modify Memory and Registers: ```py # Read memory @@ -138,13 +140,11 @@ p.regs.rax # (int) # Write registers p.regs.rax = 0x1337133713371337 +``` -# Get process base -p.maps["libc.so.6"].base # (int) - -# Get current thread id (valid in hooks and thread entrypoint) -p.tid # (int), starts from 1 +Hooks: +```py # Hooks (functions called before executing the instruction at the specified PC) p.hook(0x100000, lambda p: print(f"rsp={hex(p.regs.rsp)}")) @@ -162,6 +162,29 @@ p.syscall_pre(1, lambda p, syscall_num: print(f"write about to be called with {p p.syscall_post(1, lambda p, syscall_num: print(f"write called with {p.regs.rdx} bytes")) ``` +Debugger-style "blocking" APIs: +```py +# Resumes the process until completion +p.run() + +# Resumes the process until `pc` is reached +p.run_until(pc) + +# pwntools tube APIs are overloaded: +# recvuntil(x) resumes the process until it reaches a "write" syscall +# that writes matching data +p.recvuntil(bstr) +``` + +Misc +```py +# Get process base +p.maps["libc.so.6"].base # (int) + +# Get current thread id (valid in hooks and thread entrypoint) +p.tid # (int), starts from 1 +``` + ### FAQ **Why should I use this over GDB or other ptrace-based debuggers?**