Warning
The documentation for VDB hasn’t been touched yet! If you want to contribute (or have ideas for better documentation), feel free to send me a pull request or email me.
Bases: envi.cli.EnviMutableCli, vtrace.notifiers.Notifier, vtrace.util.TraceManager
A VDB object is a debugger object which may be used to embed full debugger like functionality into a python application. The Vdb object contains a CLI impelementation which extends envi.cli>
Act as a remote debugging client to the server running on the specified host/ip.
Usage: remote <host>
Allocate a chunk of memory in the target process. It will be allocated with rwx permissions.
Usage: alloc <size expr>
Attach to a process by PID or by process name. In the event of more than one process by a given name, attach to the last (most recently created) one in the list.
Usage: attach [<pid>,<name>]
NOTE: This is not a regular expression. The given string must be found as a substring of the process name...
Manipulate the auto-continue behavior for the trace. This will cause particular event types to automagically continue execution.
Usage: autocont [event name]
Return the “best name” string for an address.
Usage: bestname <vtrace expression>
Show, add, and enable/disable breakpoints USAGE: bp [-d <addr>] [-a <addr>] [-o <addr>] [[-c pycode] <address> [vdb cmds]] -C - Clear All Breakpoints -c “py code” - Set the breakpoint code to the given python string -d <id> - Disable Breakpoint -e <id> - Enable Breakpoint -r <id> - Remove Breakpoint -o <addr> - Create a OneTimeBreak -L <libname> - Add bp’s to all functions in <libname> -F <filename> - Load bpcode from file -W perms:size - Set a hardware Watchpoint with perms/size (ie -W rw:4) -f - Make added breakpoints from this command into “fastbreaks” -S <libname>:<regex> - Add bp’s to all matching funcs in <libname>
<address>... - Create Breakpoint
be run with the following objects mapped into it’s namespace automagically:
vtrace - the vtrace package trace - the tracer bp - the breakpoint object
Manipulcate the python code that will be run for a given breakpoint by ID. (Also the way to view the code).
Usage: bpedit <id> [“optionally new code”]
NOTE: Your code must be surrounded by “s and may not contain any “s
Set the python code for a breakpoint from the contents of a file.
Usage: bpfile <bpid> <filename>
Send the break signal to the target tracer to stop it’s execution.
Usage: break
Allows a C-like syntax for calling functions inside the target process (from his context). Example: call printf(“yermom %d”, 10)
Print out the opcodes for a given address expression
Usage: dis <address expression> [<size expression>]
Cli interface to the “stack doping” api inside recon. BETA
(Basically, set all un-initialized stack memory to V’s to tease out uninitialized stack bugs)
Usage: dope [ options ] -E Enable automagic thread stack doping on all continue events -D Disable automagic thread stack doping on all continue events -A Dope all current thread stacks
Execute a program with the given command line and attach to it. Usage: exec </some/where and some args>
Show all the open Handles/FileDescriptors for the target process. The “typecode” shown in []’s is the vtrace typecode for that kind of fd/handle.
Usage: fds
Continue the target tracer. -I go icount linear instructions forward (step over style) -U go out of fcount frames (step out style) <until addr> go until explicit address
Usage: go [-U <fcount> | -I <icount> | <until addr expression>]
Parse and display a Global Unique Identifier (GUID) from memory (eventually, use GUID db to lookup the name/meaning of the GUID).
Usage: guid <addr_exp>
Add the specified signal id (exception id for windows) to the ignored signals list for the current trace. This will make the smallest possible performance impact for that particular signal but will also not alert you that it has occured.
Usage: ignore [options] [-c | <sigcode>...] -d - Remove the specified signal codes. -c - Include the current signal in the sigcode list -C - Clear the list of ignored signals
Save and compare snapshots of memory to enumerate changes.
Usage: memdiff [options] -C Clear all current memory diff snapshots. -A <va:size> Add the given virtual address to the list. -M <va> Add the entire memory map which contains VA to the list. -D Compare currently tracked memory with the target process
and show any differences.
Load a file into memory. (straight mapping, no parsing)
Usage: memload <filename>
Cli front end to the vdb recon subsystem which allows runtime analysis of known API calls.
Usage: recon [options] -A <sym_expr>:<recon_fmt> - Add a recon breakpoint with the given format -C - Clear the current list of recon breakpoint hits. -H - Print the current list of recon breakpoint hits. -Q - Toggle “quiet” mode which prints nothing on bp hits. -S <sym_expr>:<argidx> - Add a sniper break for arg index
Recon Format: C - A character I - A decimal integer P - A pointer (display symbol if possible) S - An ascii string (up to 260 chars) U - A unicode string (up to 260 chars) X - A hex number
Show the current register values. Additionally, you may specify name=<expression> to set a register
Usage: reg [regname=vtrace_expression]
Restart the current process.
Usage: restart
NOTE: This only works if the process was exec’d to begin with!
TODO: Plumb options for persisting bp’s etc...
Start a vtrace server on the local box. If the server is already running, show which processes are being remotely debugged.
Usage: server
Take a process snapshot of the current (stopped) trace and save it to the specified file.
Usage: snapshot <filename>
Cli front end to the VDB code coverage subsystem. FIXME MORE DOCS!
Usage: stalker [options] -C - Cleanup stalker breaks and hit info -c - Clear the current hits (so you can make more ;) -E <addr_expr> - Add the specified entry point for tracking -H - Show the current hits -L <lib>:<regex> - Add stalker breaks to all matching library symbols -R - Reset all breakpoints to enabled and clear hit info
Single step the target tracer. Usage: stepi [ options ]
| -A <addr> |
|
| -B |
|
-C <count> - Step <count> instructions -R - Step to return from this function -V - Show operand values during single step (verbose!)
Break out a strcuture from memory. You may use the command “vstruct” to show the known structures in vstruct.
Usage: struct <StructName> <vtrace expression>
List symbols and by file.
Usage: syms [-s <pattern>] [filename]
With no arguments, syms will self.vprint(the possible libraries with symbol resolvers. Specify a library to see all the symbols for it.
List the current threads in the target process or select the current thread context for the target tracer. Usage: threads [thread id]
Set a variable in the expression parsing context. This allows for scratchspace names (python compatable names) to be used in expressions.
Usage: var <name> <addr_expression>
NOTE: The address expression must resolve at the time you set it.
List the available structure modules and optionally structure definitions from a particular module in the current vstruct.
Usage: vstruct [modname]
Run the target process until the specified library (by normalized name such as ‘kernel32’ or ‘libc’) is loaded. Disable waiting with -D.
Usage: waitlib [ -D | <libname> ]
Load up any extensions which are relevant for the current tracer’s platform/arch/etc...
Generate a new trace for this vdb instance. This fixes many of the new attach/exec data munging issues because tracer re-use is very sketchy...
Return a string representing the best known name for the given address
A home for the vdb specific memory renderers.