windbgskill

WinDbg HTTP Bridge

windbgskill.dll を通じて WinDbg を制御し、ローカル HTTP サーバーを公開します。 ダンプ解析の場合は、ダンプとブリッジの初期化を 1 つのコマンドで指定して WinDbgX を起動します。既存の対話型デバッグセッションの場合は、そのセッションでブリッジを読み込んで起動します。初期化後は、HTTP（curl、curl.exe、Python、または任意の HTTP クライアント）経由で通信します。

3 つのデバッグモードはすべて同じプラグインインターフェースを共有します。違いは、送信する 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 ブリッジを起動します。

既存のデバッグセッションを初期化する

すでに開かれているライブカーネルまたはユーザーモードのセッションでは、引き続き DLL の絶対パスを使用して、WinDbg 内でコマンドを実行します。

.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 を確認してください。state が 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 の出力に bugcheck なしで EXCEPTION_CODE がある	プロセスダンプまたはユーザーモード
!process 0 0 がプロセスリストを返す	ライブカーネルデバッグ

シナリオが曖昧でコンテキストから推測できない場合は、次のように尋ねます: 「これはダンプ解析、ライブカーネルデバッグ、ユーザーモードプロセスデバッグのどれですか？」

API リファレンス

ベース URL: http://127.0.0.1:{PORT}

エンドポイント	メソッド	目的
/api/help	GET	API ドキュメント（LLM の自己検出）
/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 の後に .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 秒です。
• ターゲットが実行中の場合、/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 を意味します。
• デバッグのシナリオが不明確な場合は、まずコンテキストから推測してください。推測できない場合にのみユーザーに尋ねてください。