Skip to content
Back to search

windbg-mcp

An MCP (Model Context Protocol) server that turns all pybag Windows debugger functions into native MCP tools. It lets MCP-compatible clients (Claude Desktop, Claude Code, Cowork, OpenAI Codex CLI, Cursor, and custom agents) control user-mode processes, kernel sessions, and crash dump analysis via structured JSON calls.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gengstah--windbg-mcp/badge.svg)](/listings/gengstah--windbg-mcp)

HTML

<a href="/listings/gengstah--windbg-mcp"><img src="/api/listings/gengstah--windbg-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Clone the repository

git clone https://github.com/your-username/windbg-mcp.git
cd windbg-mcp

2. Install Python dependencies

pip install pybag mcp

3. Install Microsoft Debugging Tools

Download the Windows SDK and select **Debugging Tools for Windows** during setup: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 701 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # WinDbg MCP
  2. An MCP (Model Context Protocol) server that exposes every pybag Windows debugger
  3. function as a native MCP tool. It gives any MCP-compatible client (Claude Desktop,
  4. Claude Code, Cowork, OpenAI Codex CLI, Cursor, and custom agents) full control over
  5. user-mode processes, kernel sessions, and crash dump analysis — all through typed
  6. tool calls with structured JSON responses.
  7. ---
  8. ## Requirements
  9. - **Windows only** — pybag requires Microsoft Debugging Tools for Windows
  10. - Python 3.10+
  11. - Microsoft Debugging Tools for Windows (part of the Windows SDK)
  12. ---
  13. ## Installation
  14. ### 1. Clone the repository
  15. ```bat
  16. git clone https://github.com/your-username/windbg-mcp.git
  17. cd windbg-mcp
  18. ```
  19. ### 2. Install Python dependencies
  20. ```bat
  21. pip install pybag mcp
  22. ```
  23. ### 3. Install Microsoft Debugging Tools
  24. Download the Windows SDK and select **Debugging Tools for Windows** during setup:
  25. https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
  26. ---
  27. ## Connecting to LLM IDEs and Clients
  28. The server runs as a local stdio process. All clients below launch it the same way —
  29. `python <path-to>/windbg_mcp.py` — but each has its own config format.
  30. ---
  31. ### Claude Desktop
  32. Edit the Claude Desktop configuration file and add the `windbg-mcp` entry:
  33. **Config file location:**
  34. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  35. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  36. ```json
  37. {
  38. "mcpServers": {
  39. "windbg-mcp": {
  40. "command": "python",
  41. "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
  42. }
  43. }
  44. }
  45. ```
  46. Restart Claude Desktop. All 55 debugger tools will appear automatically.
  47. ---
  48. ### Claude Code (CLI)
  49. Run the following command once to register the server. Claude Code stores the entry
  50. in its own MCP config and makes the tools available in every subsequent session.
  51. ```bash
  52. claude mcp add windbg-mcp python C:\path\to\windbg-mcp\windbg_mcp.py
  53. ```
  54. To verify the server was registered:
  55. ```bash
  56. claude mcp list
  57. ```
  58. To remove it later:
  59. ```bash
  60. claude mcp remove windbg-mcp
  61. ```
  62. ---
  63. ### Claude Cowork
  64. There are two ways to add WinDbg MCP to Cowork: via JSON configuration (quick) or
  65. by installing it as a `.mcpb` plugin bundle (portable, shareable).
  66. #### Option A — JSON Configuration
  67. 1. Open the Claude desktop app and go to **Settings → MCP Servers**.
  68. 2. Click **Add Server** and paste the following:
  69. ```json
  70. {
  71. "windbg-mcp": {
  72. "command": "python",
  73. "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
  74. }
  75. }
  76. ```
  77. 3. Save and restart Cowork. The tools will be available in your next session.
  78. #### Option B — Install as a `.mcpb` Plugin Bundle
  79. A `.mcpb` file is a zip archive of the plugin directory that Cowork can install
  80. directly. This is the recommended approach when sharing the server with a team or
  81. across machines.
  82. **Step 1 — Build the `.mcpb` file**
  83. From the root of the cloned repository, run:
  84. ```bat
  85. powershell -Command "Compress-Archive -Path '.\*' -DestinationPath 'windbg-mcp.zip'; Rename-Item 'windbg-mcp.zip' 'windbg-mcp.mcpb'"
  86. ```
  87. This creates `windbg-mcp.mcpb` in the current directory, bundling `windbg_mcp.py`,
  88. `manifest.json`, and any other project files.
  89. **Step 2 — Install in Cowork**
  90. 1. Open the Claude desktop app.
  91. 2. Go to **Settings → Plugins** (or **Extensions**).
  92. 3. Click **Install Plugin** and select `windbg-mcp.mcpb`.
  93. 4. Cowork reads `manifest.json` from the bundle, registers the MCP server, and
  94. makes all tools available immediately — no manual path configuration required.
  95. The `manifest.json` bundled in this repo is already configured correctly:
  96. ```json
  97. {
  98. "manifest_version": "0.2",
  99. "name": "windbg-mcp",
  100. "version": "1.0.0",
  101. "description": "WinDbg MCP — full Windows debugger control via MCP tools",
  102. "server": {
  103. "type": "python",
  104. "entry_point": "windbg_mcp.py",
  105. "mcp_config": {
  106. "command": "python",
  107. "args": ["${__dirname}/windbg_mcp.py"]
  108. }
  109. }
  110. }
  111. ```
  112. `${__dirname}` is resolved at install time to the directory where Cowork unpacked
  113. the bundle, so you do not need to hard-code any paths.
  114. ---
  115. ### OpenAI Codex CLI
  116. Add the server to your Codex CLI configuration file. The file is typically located at
  117. `~/.codex/config.json` (Linux/macOS) or `%USERPROFILE%\.codex\config.json` (Windows).
  118. ```json
  119. {
  120. "mcpServers": {
  121. "windbg-mcp": {
  122. "command": "python",
  123. "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
  124. }
  125. }
  126. }
  127. ```
  128. Once saved, start a new Codex session. The WinDbg tools will be available for the
  129. model to call.
  130. ---
  131. ### Cursor
  132. 1. Open **Cursor → Preferences → Cursor Settings**.
  133. 2. Navigate to the **MCP** tab.
  134. 3. Click **Add new global MCP server** and use this configuration:
  135. ```json
  136. {
  137. "windbg-mcp": {
  138. "command": "python",
  139. "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
  140. }
  141. }
  142. ```
  143. 4. Save. Cursor will connect to the server on its next Composer session.
  144. ---
  145. ### Continue.dev
  146. Add the following to your `~/.continue/config.json` (or the workspace-level
  147. `.continue/config.json`):
  148. ```json
  149. {
  150. "experimental": {
  151. "modelContextProtocolServers": [
  152. {
  153. "transport": {
  154. "type": "stdio",
  155. "command": "python",
  156. "args": ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"]
  157. }
  158. }
  159. ]
  160. }
  161. }
  162. ```
  163. Reload the Continue extension. The 55 debugger tools will appear in the tool list.
  164. ---
  165. ### Custom Agents and the MCP SDK
  166. If you are building your own agent or automation pipeline, connect to WinDbg MCP
  167. over the standard MCP stdio transport. The server speaks JSON-RPC 2.0 over stdin/stdout.
  168. #### Python (using the `mcp` SDK)
  169. ```python
  170. import asyncio
  171. from mcp import ClientSession, StdioServerParameters
  172. from mcp.client.stdio import stdio_client
  173. server_params = StdioServerParameters(
  174. command="python",
  175. args=[r"C:\path\to\windbg-mcp\windbg_mcp.py"],
  176. )
  177. async def main():
  178. async with stdio_client(server_params) as (read, write):
  179. async with ClientSession(read, write) as session:
  180. await session.initialize()
  181. # List all available tools
  182. tools = await session.list_tools()
  183. print([t.name for t in tools.tools])
  184. # Load a crash dump
  185. result = await session.call_tool(
  186. "load_dump",
  187. arguments={"path": r"C:\crashes\crash.dmp"},
  188. )
  189. print(result.content)
  190. # Read 64 bytes at RSP
  191. result = await session.call_tool(
  192. "read_mem",
  193. arguments={"addr": "0x00000000001FF000", "size": 64},
  194. )
  195. print(result.content)
  196. asyncio.run(main())
  197. ```
  198. #### TypeScript / Node.js (using the `@modelcontextprotocol/sdk` package)
  199. ```typescript
  200. import { Client } from "@modelcontextprotocol/sdk/client/index.js";
  201. import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
  202. const transport = new StdioClientTransport({
  203. command: "python",
  204. args: ["C:\\path\\to\\windbg-mcp\\windbg_mcp.py"],
  205. });
  206. const client = new Client({ name: "my-agent", version: "1.0.0" }, {});
  207. await client.connect(transport);
  208. // Call a tool
  209. const result = await client.callTool({
  210. name: "load_dump",
  211. arguments: { path: "C:\\crashes\\crash.dmp" },
  212. });
  213. console.log(result.content);
  214. await client.close();
  215. ```
  216. #### LangChain / LangGraph
  217. ```python
  218. from langchain_mcp_adapters.tools import load_mcp_tools
  219. from mcp import ClientSession, StdioServerParameters
  220. from mcp.client.stdio import stdio_client
  221. server_params = StdioServerParameters(
  222. command="python",
  223. args=[r"C:\path\to\windbg-mcp\windbg_mcp.py"],
  224. )
  225. async def get_tools():
  226. async with stdio_client(server_params) as (read, write):
  227. async with ClientSession(read, write) as session:
  228. await session.initialize()
  229. return await load_mcp_tools(session)
  230. ```
  231. #### Direct JSON-RPC over stdio (language-agnostic)
  232. The server communicates via newline-delimited JSON-RPC 2.0 messages. You can drive
  233. it from any language by writing to the process's stdin and reading from stdout:
  234. ```
  235. → {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}
  236. ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{"name":"WinDbg MCP","version":"1.0.0"}}}
  237. → {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"load_dump","arguments":{"path":"C:\\crashes\\crash.dmp"}}}
  238. ← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"status\": \"ok\", ...}"}]}}
  239. ```
  240. ---
  241. ## Available Tools (55 total)
  242. ### Session Management
  243. | Tool | Parameters | Returns |
  244. |------|-----------|---------|
  245. | `status` | — | `{connected, type, pid, bitness}` |
  246. | `list_processes` | — | `[{pid, name, description}]` |
  247. | `create` | `path` (required), `args`, `initial_break` | `{status, pid, bitness}` |
  248. | `attach` | `pid` **or** `name` (not both), `initial_break` | `{status, pid, bitness}` |
  249. | `kernel_attach` | `connect_string` (required), `initial_break` | `{status, type, connect_string}` |
  250. | `load_dump` | `path` (required) | `{status, bitness, rip, symbol_at_rip}` |
  251. | `connect` | `options` (required) | `{status, options}` |
  252. | `detach` | — | `{status}` |
  253. | `terminate` | — | `{status}` |
  254. **`create`** — Launches a new process under the debugger. Set `initial_break=True` (default) to break at the process entry point.
  255. **`attach`** — Attaches to a running process. Provide either `pid` (integer) or `name` (process filename). Do not provide both.
  256. **`kernel_attach`** — Connects to a remote kernel debugger. `connect_string` uses KD syntax, e.g. `"net:port=55000,key=1.2.3.4"`.
  257. **`load_dump`** — Opens a `.dmp` file for post-mortem analysis. Returns the crash address and nearest symbol immediately.
  258. **`connect`** — Connects to a process server for remote user-mode debugging. `options` uses DbgEng connection syntax, e.g. `"tcp:server=192.168.1.10,port=5555"`.
  259. ---
  260. ### Execution Control
  261. | Tool | Parameters | Returns |
  262. |------|-----------|---------|
  263. | `go` | `timeout` (ms, default 30000) | `{status, rip, symbol, new_captures, captures}` |
  264. | `step_into` | `count` (default 1) | `{rip, instruction, symbol}` |
  265. | `step_over` | `count` (default 1) | `{rip, instruction, symbol}` |
  266. | `step_out` | — | `{rip, instruction, symbol}` |
  267. | `goto` | `expr` (required) | `{rip, symbol}` |
  268. | `trace` | `count` (default 10) | `{instructions: [{rip, instruction, symbol}], count}` |
  269. **`go`** — Resumes execution and blocks until the next debug event (breakpoint, exception, or timeout). Returns the new RIP and any captures collected while running.
  270. **`step_into`** — Steps into the next instruction, following calls into called functions.
  271. **`step_over`** — Steps over the next instruction, treating calls as a single step.
  272. **`step_out`** — Runs until the current function returns.
  273. **`goto`** — Runs until a specific symbol or hex address is reached, e.g. `"Kernel32!ExitProcess"` or `"0x7fff12340000"`.
  274. **`trace`** — Performs N single-step iterations and records each instruction visited.
  275. ---
  276. ### Breakpoints
  277. | Tool | Parameters | Returns |
  278. |------|-----------|---------|
  279. | `bp` | `expr` (required), `capture`, `action`, `oneshot`, `passcount` | `{id, expr, addr, capture}` |
  280. | `hw_bp` | `addr` (required), `size`, `access`, `capture`, `action`, `oneshot` | `{id, addr, size, access}` |
  281. | `list_bps` | — | `[{id, expr, type, capture, action, ...}]` |
  282. | `remove_bp` | `id` (required) | `{status, id}` |
  283. | `enable_bp` | `id` (required) | `{status, id}` |
  284. | `disable_bp` | `id` (required) | `{status, id}` |
  285. **`bp`** — Sets a software (code) breakpoint at a symbol or address.
  286. - `expr`: symbol (`"ntdll!NtCreateFile"`) or hex address (`"0x7ff800001234"`)
  287. - `capture`: when `true` (default), automatically saves full state — registers, stack, memory — to the capture buffer each time this breakpoint fires
  288. - `action`: `"go"` (default) continues execution after capture; `"break"` halts
  289. - `oneshot`: removes the breakpoint after it fires once
  290. - `passcount`: fires only after N passes through the location
  291. **`hw_bp`** — Sets a hardware / data breakpoint (watchpoint).
  292. - `addr`: hex address to watch
  293. - `size`: watch width in bytes — `1`, `2`, `4`, or `8` (default `4`)
  294. - `access`: `"e"` execute, `"w"` write (default), `"r"` read/write
  295. - `capture`, `action`, `oneshot`: same semantics as `bp`
  296. **`list_bps`** — Returns all currently active breakpoints with their IDs, expressions, types, and settings.
  297. **`remove_bp` / `enable_bp` / `disable_bp`** — Manage breakpoints by the `id` returned from `bp` or `hw_bp`.
  298. ---
  299. ### State Captures
  300. Breakpoints with `capture: true` (the default) automatically save a full debugger
  301. snapshot every time they fire. The snapshot includes all registers, the call stack,
  302. 64 bytes of stack memory at RSP, and 32 bytes of code at RIP. Snapshots accumulate
  303. in a buffer and can be retrieved at any time with `get_captures`.
  304. | Tool | Parameters | Returns |
  305. |------|-----------|---------|
  306. | `get_captures` | — | `{count, captures: [{bp_id, expr, timestamp, registers, rip, symbol_at_rip, instruction, stack, context_memory}]}` |
  307. | `clear_captures` | — | `{status}` |
  308. | `capture_state` | — | `{timestamp, registers, rip, symbol_at_rip, instruction, disasm_5, stack_at_rsp, call_stack}` |
  309. **`get_captures`** — Returns all captures collected since the last `clear_captures`. Each capture contains:
  310. - `registers` — all register values as `{name: "0x..."}` hex strings
  311. - `rip` — instruction pointer at the moment of capture
  312. - `symbol_at_rip` — nearest symbol to RIP
  313. - `instruction` — disassembly of the instruction at RIP
  314. - `stack` — top 10 call stack frames with addresses and return addresses
  315. - `context_memory.stack_at_rsp` — 64 bytes at RSP as hex, formatted, and ASCII
  316. - `context_memory.code_at_rip` — 32 bytes at RIP as hex and formatted
  317. **`clear_captures`** — Clears the capture buffer. Useful before starting a new run.
  318. **`capture_state`** — Takes an immediate on-demand snapshot of the current state. Use this when already broken in, rather than waiting for a breakpoint to fire.
  319. ---
  320. ### Memory
  321. | Tool | Parameters | Returns |
  322. |------|-----------|---------|
  323. | `read_mem` | `addr` (required), `size` (default 16) | `{addr, size, hex, formatted, ascii}` |
  324. | `write_mem` | `addr` (required), `data` (required, hex string) | `{status, addr, bytes_written}` |
  325. | `read_ptr` | `addr` (required), `count` (default 1) | `{addr, values: ["0x..."]}` |
  326. | `poi` | `addr` (required) | `{addr, value}` |
  327. | `read_str` | `addr` (required), `wide` (default false) | `{addr, value, wide}` |
  328. | `dump_mem` | `addr` (required), `count` (default 8) | `{addr, output}` |
  329. | `mem_info` | `addr` (required) | `{addr, info}` |
  330. | `mem_list` | — | `[region_description_strings]` |
  331. **`read_mem`** — Reads `size` raw bytes from `addr`. Returns the data as `hex` (compact), `formatted` (space-separated bytes), and `ascii` (printable characters, `.` for non-printable).
  332. **`write_mem`** — Writes bytes to memory. `data` is a hex string — spaces and `\x` prefixes are stripped automatically, e.g. `"90909090"`, `"\\x90\\x90\\x90\\x90"`, or `"90 90 90 90"`.
  333. **`read_ptr`** — Reads `count` consecutive pointer-sized values (4 bytes on 32-bit, 8 bytes on 64-bit) starting at `addr`.
  334. **`poi`** — Dereferences a single pointer at `addr` (pointer-of-interest).
  335. **`read_str`** — Reads a null-terminated string. Set `wide=true` for UTF-16LE (Windows WCHAR).
  336. **`dump_mem`** — Formatted dword/pointer dump, equivalent to `dd`/`dp` in WinDbg.
  337. **`mem_info`** — Returns the memory region properties for the page containing `addr`: base address, size, type, state, and protection flags.
  338. **`mem_list`** — Lists all virtual memory regions in the target process address space.
  339. ---
  340. ### Registers
  341. | Tool | Parameters | Returns |
  342. |------|-----------|---------|
  343. | `get_regs` | — | `{rax, rbx, rcx, rdx, rsi, rdi, rbp, rsp, rip, r8–r15, eflags, ...}` |
  344. | `get_reg` | `name` (required) | `{name, value}` |
  345. | `set_reg` | `name` (required), `value` (required) | `{status, name, value}` |
  346. | `get_pc` | — | `{value, symbol, instruction}` |
  347. | `get_sp` | — | `{value}` |
  348. **`get_regs`** — Returns every available register as `{name: "0x..."}`. The exact set depends on the target architecture (x86 vs x64).
  349. **`get_reg`** — Returns a single register, e.g. `name="rax"`, `name="eflags"`.
  350. **`set_reg`** — Overwrites a register. `value` accepts hex strings (`"0x1234"`) or decimal integer strings.
  351. **`get_pc`** — Returns the instruction pointer with symbol resolution and the decoded instruction text at that address.
  352. **`get_sp`** — Returns the current stack pointer value.
  353. ---
  354. ### Symbols & Disassembly
  355. | Tool | Parameters | Returns |
  356. |------|-----------|---------|
  357. | `resolve` | `name` (required) | `{name, addr}` or `{name, addr: null, error}` |
  358. | `find_symbols` | `pattern` (required) | `[symbol_strings]` |
  359. | `addr_to_symbol` | `addr` (required) | `{addr, symbol}` |
  360. | `disasm` | `addr` (default: current RIP), `count` (default 10) | `{addr, output}` |
  361. | `whereami` | `addr` (optional, default: current RIP) | `{description}` |
  362. **`resolve`** — Resolves a symbol name to its virtual address. Use `Module!Function` format, e.g. `"Kernel32!WriteFile"`, `"ntdll!NtCreateFile"`.
  363. **`find_symbols`** — Wildcard symbol search, e.g. `"ntdll!*Alloc*"`, `"kernel32!*File*"`. Returns all matching symbol strings.
  364. **`addr_to_symbol`** — Reverse-resolves a virtual address to the nearest symbol name.
  365. **`disasm`** — Disassembles `count` instructions starting at `addr`. Defaults to the current RIP if no address is given.
  366. **`whereami`** — Returns a human-readable description of the module, function, and offset at the given address.
  367. ---
  368. ### Modules
  369. | Tool | Parameters | Returns |
  370. |------|-----------|---------|
  371. | `list_modules` | — | `[{name, base, size}]` |
  372. | `module_info` | `name` (required) | `{name, entry_point, sections}` |
  373. | `get_exports` | `name` (required) | `[export_strings]` |
  374. | `get_imports` | `name` (required) | `[import_strings]` |
  375. **`list_modules`** — Lists all modules loaded in the target, with their base address and size.
  376. **`module_info`** — Returns the entry point and section list (name, virtual address, size) for a specific module, e.g. `"kernel32.dll"`, `"ntdll.dll"`.
  377. **`get_exports`** — Returns the full export table of a module as a list of strings.
  378. **`get_imports`** — Returns the full import table of a module as a list of strings.
  379. ---
  380. ### Threads & Stack
  381. | Tool | Parameters | Returns |
  382. |------|-----------|---------|
  383. | `list_threads` | — | `[thread_description_strings]` |
  384. | `get_thread` | — | `{current_thread}` |
  385. | `set_thread` | `id` (required) | `{status, thread}` |
  386. | `get_stack` | `frames` (default 20) | `{frames: [{frame, addr, return_addr, frame_ptr}], count}` |
  387. | `get_teb` | — | `{addr}` |
  388. | `get_peb` | — | `{addr}` |
  389. **`list_threads`** — Lists all threads in the target process.
  390. **`get_thread`** — Returns the currently active thread context.
  391. **`set_thread`** — Switches the active thread context by thread ID (from `list_threads`).
  392. **`get_stack`** — Returns the call stack as structured data. Each frame includes the instruction address, return address, and frame pointer.
  393. **`get_teb`** — Returns the address of the Thread Environment Block for the current thread.
  394. **`get_peb`** — Returns the address of the Process Environment Block.
  395. ---
  396. ### Process & Utility
  397. | Tool | Parameters | Returns |
  398. |------|-----------|---------|
  399. | `get_handles` | — | `[handle_description_strings]` |
  400. | `get_bitness` | — | `{bits}` |
  401. | `raw` | `cmd` (required) | `{output}` |
  402. **`get_handles`** — Lists all open handles in the target process.
  403. **`get_bitness`** — Returns `32` or `64` depending on the target architecture.
  404. **`raw`** — Executes any WinDbg command string and returns the output as text. Use this as an escape hatch for anything not covered by the other tools:
  405. ```
  406. raw(cmd="!heap -stat")
  407. raw(cmd="dt _PEB @$peb")
  408. raw(cmd="!locks")
  409. raw(cmd="lm")
  410. raw(cmd="!address @rsp")
  411. ```
  412. ---
  413. ## Typical Workflows
  414. ### Exploit verification
  415. ```
  416. 1. create(path="C:/target/vuln.exe", args="exploit_input.bin")
  417. 2. bp(expr="vuln!processInput+0x2A", action="break")
  418. 3. go(timeout=15000)
  419. 4. get_captures()
  420. ```
  421. In `get_captures`, inspect `captures[0].registers.rip`:
  422. - `"0x4141414141414141"` — you control RIP with 'A' bytes
  423. - Any value matching your pattern — controlled
  424. - A valid-looking address — crash but not yet controlled
  425. Check `captures[0].context_memory.stack_at_rsp.formatted` to see padding, return addresses, or shellcode bytes on the stack.
  426. ---
  427. ### Crash dump analysis
  428. ```
  429. 1. load_dump(path="C:/crashes/crash.dmp")
  430. 2. get_regs() → full register state at crash time
  431. 3. get_stack(frames=30) → call stack at crash
  432. 4. get_sp() → read RSP value
  433. 5. read_mem(addr=<rsp>, size=64) → stack contents
  434. 6. disasm() → instructions at the crash address
  435. ```
  436. ---
  437. ### Heap spray verification
  438. ```
  439. 1. attach(name="target.exe")
  440. 2. hw_bp(addr="0x1001F000", size=8, access="w", action="break")
  441. 3. go()
  442. 4. get_captures() → see what wrote to the spray address
  443. 5. read_mem(addr="0x1001EFC0", size=128) → surrounding memory context
  444. ```
  445. ---
  446. ### ASLR check
  447. ```
  448. 1. create(path="C:/target/target.exe")
  449. 2. resolve(name="kernel32!WriteFile") → record base address
  450. 3. terminate()
  451. 4. create(path="C:/target/target.exe")
  452. 5. resolve(name="kernel32!WriteFile") → compare: changed = ASLR on, same = ASLR off
  453. ```
  454. ---
  455. ### Remote kernel debugging
  456. ```
  457. 1. kernel_attach(connect_string="net:port=55000,key=1.2.3.4")
  458. 2. list_modules() → all loaded kernel modules
  459. 3. module_info(name="ntoskrnl.exe") → entry point and sections
  460. 4. raw(cmd="!process 0 0") → list all processes from kernel context
  461. 5. raw(cmd="!pcr") → processor control region
  462. ```
  463. ---
  464. ### Thread inspection
  465. ```
  466. 1. attach(pid=1234)
  467. 2. list_threads() → all thread IDs
  468. 3. set_thread(id=2) → switch context
  469. 4. get_stack(frames=20) → call stack for that thread
  470. 5. get_regs() → registers for that thread
  471. 6. get_teb() → TEB address
  472. ```
  473. ---
  474. ## Tips
  475. **Symbol path** — If symbol resolution returns no results, configure the Microsoft symbol server:
  476. ```
  477. raw(cmd=".sympath srv*C:\\symbols*https://msdl.microsoft.com/download/symbols")
  478. raw(cmd=".reload")
  479. ```
  480. **Timeout tuning** — `go()` defaults to 30 seconds. For targets that run longer before hitting a breakpoint:
  481. ```
  482. go(timeout=120000) # 2 minutes
  483. go(timeout=300000) # 5 minutes
  484. ```
  485. **Address format** — All `addr` parameters accept hex strings (`"0x1234abcd"`, `"7fff12340000"`) or plain integers. The `0x` prefix is optional for hex values.
  486. **Shellcode verification** — After a capture, use `read_mem` and `disasm` on the address where your shellcode should land. If `disasm` shows your intended instructions, the payload arrived intact.
  487. **After `terminate` or `detach`** — All captures and breakpoints are cleared automatically. Call `create` or `attach` to begin a new session.
  488. **`capture_state` vs `get_captures`** — Use `capture_state` for an on-demand snapshot when already stopped at a breakpoint. Use `get_captures` to retrieve state that was automatically saved each time a breakpoint fired during a `go` call.
  489. **Kernel `raw` commands** — Common kernel debugging extensions that work well through `raw`:
  490. ```
  491. raw(cmd="!process 0 0") → list all processes
  492. raw(cmd="!thread") → current thread details
  493. raw(cmd="!irql") → current IRQL
  494. raw(cmd="!pcr") → processor control region
  495. raw(cmd="!pte <addr>") → page table entry for an address
  496. raw(cmd="dt nt!_EPROCESS @$proc") → dump EPROCESS structure
  497. ```
  498. ---
  499. ## License
  500. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.