windbgskill

WinDbg HTTP 桥接

通过 windbgskill.dll 控制 WinDbg，并提供本地 HTTP 服务。 对于转储分析，请在一条命令中启动 WinDbgX、打开转储并初始化桥接。对于已有的交互式调试会话，请在该会话中加载并启动桥接。初始化后，可通过 HTTP（curl、curl.exe、Python 或任何 HTTP 客户端）进行通信。

三种调试模式共用同一插件接口——唯一的区别是发送的 WinDbg 命令。

快速开始

打开转储

当用户提供转储路径且桥接尚未运行时，请在同一次 WinDbgX 调用中打开转储并初始化桥接：

WinDbgX.exe -z "pathtodmp" -c ".load D:\All\project\mycode\windbgskill\windbgskill\x64\Release\windbgskill.dll; !windbgskill start 127.0.0.1 23333"

将 pathtodmp 替换为转储的绝对路径。传递给 .load 的 DLL 路径也必须是绝对路径；仅传入文件名可能会失败，因为 WinDbg 无法可靠地从 PATH 或其扩展搜索路径中解析扩展。如果 DLL 安装在其他位置，请先找到该文件，再替换为其绝对路径。除非用户选择了其他端口，否则请使用端口 23333。

这条命令就是打开转储的工作流：-z 打开转储，-c 则在 WinDbg 初始化后加载扩展并启动 HTTP 桥接。

初始化现有调试会话

对于已打开的实时内核或用户模式会话，请在 WinDbg 中运行以下命令，仍需使用 DLL 的绝对路径：

.load D:\All\project\mycode\windbgskill\windbgskill\x64\Release\windbgskill.dll

# Default: listen on 127.0.0.1:9090 (local access only)
!windbgskill start

# Specify port only (still binds to 127.0.0.1)
!windbgskill start 9090

# Specify IP and port (use 0.0.0.0 to allow remote machine access)
!windbgskill start 0.0.0.0 9090

用户告知端口（例如“windbgskill 插件运行在端口 9090”）：

curl.exe -s http://127.0.0.1:9090/api/status
curl.exe -s -X POST http://127.0.0.1:9090/api/exec -d "!analyze -v"

务必先检查 /api/status。如果状态为 running，请在发送任何命令前调用 /api/break。

调试器状态

状态	含义	操作
broken	目标已暂停，调试器提示符处于活动状态	可自由发送命令
running	目标正在执行	先调用 /api/break
no_target	未打开调试会话	如果有转储路径，请使用上面的 WinDbgX 命令启动；否则询问用户要附加到哪个目标
stepping	单步模式	按 broken 状态处理

状态转换：running → POST /api/break → broken → POST /api/go → running

场景判断

如果用户未指定模式，请先根据上下文推断，再进行询问。

信号	可能的场景
提到了 .dmp / .mdmp 文件路径	转储分析
“BSOD”、“bugcheck”、“蓝屏”、内核转储	内核转储分析
“attached kernel”、“KDNET”、“VM debug”、“local kernel”	实时内核调试
“attached process”、“process hang”、“application crash”	用户模式调试
!analyze -v 输出包含 BUGCHECK_CODE	内核转储
!analyze -v 输出包含 EXCEPTION_CODE，但不包含 bugcheck	进程转储或用户模式调试
!process 0 0 返回进程列表	实时内核调试

如果场景不明确，且无法根据上下文推断，请询问： “这是转储分析、实时内核调试，还是用户模式进程调试？”

API 参考

基础 URL：http://127.0.0.1:{PORT}

端点	方法	用途
/api/help	GET	API 文档（供大模型自行发现）
/api/status	GET	调试器状态、端口和当前命令信息
/api/exec	POST	执行 WinDbg 命令
/api/break	POST	中断正在运行或卡住的目标
/api/go	POST	恢复目标执行
/api/shutdown	POST	远程停止 HTTP 服务

# Self-discovery
curl.exe -s http://127.0.0.1:{PORT}/api/help

# Check state - also shows which command is currently running
# {"state":"broken","port":9090,"exec":{"busy":false}}
# {"state":"broken","port":9090,"exec":{"busy":true,"cmd":"!analyze -v","elapsed_s":47}}
curl.exe -s http://127.0.0.1:{PORT}/api/status

# Execute a command (body = raw WinDbg command, response = raw output)
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/exec -d "k"
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/exec -d "!analyze -v"

# Custom timeout via query param (default 60 s)
curl.exe -s -X POST "http://127.0.0.1:{PORT}/api/exec?timeout=180" -d "!analyze -v"

# Interrupt / resume
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/break
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/go

# Stop server remotely
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/shutdown

按场景分类的常用命令

转储分析（进程转储或内核转储）

目标	命令
自动崩溃分析	!analyze -v
切换到故障线程上下文	.ecxr
调用堆栈	k / kb / kn
所有线程／处理器的堆栈	~*k
切换到线程／处理器 N	~Ns
寄存器	r
已加载模块	lm
重新加载模块的符号	.reload <module>
强制重新加载所有符号	.reload /f
详细符号诊断	!sym noisy then .reload
显示类型／结构	dt <type> [addr]
内存布局	!address
进程环境块	!peb
线程环境块	!teb
堆概览	!heap -s

符号问题：如果输出显示 ??? symbols 或 symbol file could not be found，请运行 .reload <module> 或 .reload /f。运行 .reload 前使用 !sym noisy，以诊断符号加载失败的原因。

实时内核调试

内核上下文中的 ~N = 切换到处理器／核心 N（不是线程）。使用 !process / !thread 浏览线程。

目标	命令
列出所有进程	!process 0 0
显示线程详情的进程	!process 0 7
检查特定进程	!process <addr> 7
切换到处理器／核心 N	~Ns
当前线程信息	!thread
驱动程序对象	!drvobj <name> 7
设备对象	!devobj <addr>
池标记分析	!pool <addr> / !poolused
页表项	!pte <addr>
显示 EPROCESS	dt nt!_EPROCESS <addr>
列出驱动程序／模块	lm
在内核符号处设置断点	bp nt!NtCreateFile
虚拟内存统计信息	!vm
重新加载驱动程序符号	.reload <driver.sys>

用户模式进程调试

用户模式上下文中的 ~N = 切换到线程 N（例如 ~0s、~1s）。

目标	命令
列出线程	~
所有线程的调用堆栈	~*k
切换到线程 N	~Ns
调用堆栈	k / kb
显示局部变量	dv
搜索符号	x <module>!<pattern>
句柄表	!handle
堆概览	!heap -s
进程环境块	!peb
设置断点	bp <module>!<function>
列出断点	bl

工作流

崩溃转储分析

# 1. If the bridge is not running yet, open the dump and initialize it in one command
WinDbgX.exe -z "pathtodmp" -c ".load D:\All\project\mycode\windbgskill\windbgskill\x64\Release\windbgskill.dll; !windbgskill start 127.0.0.1 23333"

# 2. Confirm state (a loaded dump is in broken state)
curl.exe -s http://127.0.0.1:23333/api/status

# 3. Automated analysis (can take 60-120 s if downloading symbols)
curl.exe -s -X POST "http://127.0.0.1:23333/api/exec?timeout=180" -d "!analyze -v"

# 4. Switch to faulting context and inspect stack
curl.exe -s -X POST http://127.0.0.1:23333/api/exec -d ".ecxr"
curl.exe -s -X POST http://127.0.0.1:23333/api/exec -d "k"

实时内核调试

# 1. Break in
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/break

# 2. Explore system state
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/exec -d "!process 0 0"

# 3. Set breakpoint and resume
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/exec -d "bp nt!NtCreateFile"
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/go

# 4. When breakpoint hits, inspect
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/exec -d "k"
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/exec -d "r"

用户模式进程调试

# 1. Break in
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/break

# 2. Overview
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/exec -d "~*k"
curl.exe -s -X POST "http://127.0.0.1:{PORT}/api/exec?timeout=120" -d "!analyze -v"

# 3. Set breakpoint and resume
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/exec -d "bp MyModule!MyFunction"
curl.exe -s -X POST http://127.0.0.1:{PORT}/api/go

规则

• 使用任何可用的 HTTP 客户端（curl、curl.exe、Python requests 等）。
• 对于尚未打开的转储，请使用 WinDbgX.exe -z "pathtodmp" -c ".load <absolute-dll-path>; !windbgskill start 127.0.0.1 <port>"；不要将打开转储和初始化桥接拆分成互不相关的手动步骤。
• 始终为 .load 传入绝对 DLL 路径。不要依赖 PATH、当前目录或 WinDbg 的扩展搜索路径。
• /api/exec 请求体是纯文本——直接发送 WinDbg 命令，不要用 JSON 包装。
• 对于耗时较长的命令（!analyze -v、.reload /f、符号下载），请追加 ?timeout=180；默认值为 60 s。
• 如果目标正在运行，/api/exec 会返回 HTTP 409——请先调用 /api/break。
• 如果引擎卡住，/api/exec 会返回 HTTP 503——请诊断并恢复：
  1. GET /api/status → exec.busy、exec.cmd、exec.elapsed_s 会显示阻塞的内容和持续时间。
  2. POST /api/break → 发送被动中断以解除卡住的命令。
  3. 重试原命令或调查原因。
• 执行恢复命令（g、p、t、pt、tt）后，状态会变为 running；执行下一个命令前请检查 /api/status。
• ~N 在用户模式中表示线程 N，在内核模式和内核转储中表示处理器／核心 N。
• 如果调试场景不明确，请先根据上下文推断；只有在无法推断时才询问用户。