live-kernel
Skill21 starsChanged 11 days agoMITView on GitHub
Reach and drive a live kernel target from this bench - KDNET and serial wiring and their traps, loading and walking a driver's IOCTL dispatch (HEVD), what `.reload` does to the module inventory, and where symbols must live. Use when attaching to a kernel target, debugging a driver over KD, or diagnosing an attach that parked or symbols that will not resolve.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- eval-benchSkill
- handoffSkill
- live-hypervisorSkill
- merge-dependabot-prsSkill
- release-rust-crates-ioSkill
- review-roundSkill
- tiersSkill
- msrc-patch-diffSkill
- windbg-debuggingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
KDNET: Check the target is reachable *before* starting the tier, not by starting it — an attach that finds nothing parks its worker in …
- Very specific: line 93
Every trigger is wrapped in __try/__except, so a kernel-mode access violation is caught and returned as a status: the null dereference …
- Very specific: line 240
After a target reboot, the settling KD link shows repeated break-ins in kdnic.sys (the KD NIC transport: nt!DbgBreakPointWithStatus ← …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Live kernel and driver IOCTL work
Two ways a target is reached, and neither is "the" procedure
KDNET. Check the target is reachable before starting the tier, not by starting it — an attach
that finds nothing parks its worker in WaitForEvent(INFINITE) for the whole run and reports a
timeout that measures the environment rather than the code. What settles it is not "can I reach the
guest" but does the guest's bcdedit /dbgsettings hostip equal this debugger host's current IP,
on the port the profile names; the host IP moves between sessions. Compare the key by hash rather
than printing it.
Finding the guest is topology-specific. Where the debugger host is also the Hyper-V host for the
target, Get-VM is exactly the right instrument — it finds the guest and reports its state, and
nothing below replaces it. It does not start one: a guest listed Off needs Start-VM before any
probe below means anything, which is a second step and not a flag on the listing.
What it cannot do is answer for a guest somebody else hypervises: it enumerates the VMs this
host hypervises, so a sibling is neither found nor ruled out. Under KDNET the target dials this
host over the network, so who hypervises it does not enter into whether the link can work. The trap
is therefore a negative read of a listing: measured 2026-10-10, a six-VM listing with no target
in it was taken as "there is no guest to dial in", and the target was a sibling the whole time.
A listing that does not contain your target tells you nothing; one that does is authoritative.
Reach for the neighbour table below only once Get-VM has come back without it.
What finds it is the neighbour table (Get-NetNeighbor -AddressFamily IPv4 | ? LinkLayerAddress
-like '00-15-5D*') plus a TCP probe of 5985 on those addresses alone — the guest answers WinRM
and nothing else, ICMP and 445 being closed, so a failed ping proves nothing. Probe the neighbours
the table names, never the subnet: a sweep is slower and is refused on this bench as network
scanning. A State of Stale is an entry nothing has spoken to lately, not a dead host. With
several neighbours the table will happily validate the wrong guest, which is what the hostip
comparison is for.
Serial, which is what the Parallels bench uses — and there KDNET is not merely unconfigured but
impossible: guests get a Parallels VirtIO Ethernet Adapter (PCI\VEN_1AF4), and 1AF4 is not
in the Debugging Tools' VerifiedNICList.xml. prlctl set <vm> --device-set net0 --adapter-type
e1000 is accepted and silently ignored on ARM, leaving the guest with no network at all. Do not
spend an afternoon on it. The wiring that works is a TCP socket between two guests:
- target
serial0→tcp://localhost:2020, client;bcdedit /dbgsettings serial debugport:1 baudrate:115200 - debugger
serial0→tcp://:2020, server — thenprlctl set <vm> --device-connect serial0, or it staysstate=disconnectedand nothing binds the port, and a VM restart, or the guest never sees a COM port netstat -an | grep 2020on the Mac: a LISTEN and an ESTABLISHED pair means the wire is up- on the target,
ARM PL011 Serial Port Device (COM1)inErrorstate with no name fromGetPortNames()is correct — that is the kernel debugger owning the port
Three traps on that bench, each of which cost real time:
kd -bis no longer supported — the docs say so in those words, and it is silently a no-op, so akd -k … -bprobe sits atno_debuggeeagainst a running target and looks like a dead link. Use-bonc. windbg-mcp itself is unaffected; DbgEng issues a proper break-in.- Parallels
Pause idleis on by default, and a target broken into the debugger burns no CPU, so the hypervisor suspends the whole VM mid-run and every later call times out with nothing to explain it.prlctl listthen shows itpaused, which is not a kernel halt.prlctl set "<vm>" --pause-idle off. - A worker killed while holding a broken-in kernel leaves the guest frozen —
prlctl exechangs on it. Attaching and detaching properly is the fix:kd -k com:port=COM1,baud=115200 -c ".time;qd". - Do not hard-reset the debuggee to clear a corrupted kernel pool. Two
prlctl resets in a row put it into WinRE ("Your device ran into a problem and couldn't be repaired"), which wants console inputprlctlcannot send andprlctl execcannot see past — a third reset happened to boot through it, but nothing guarantees that. Let a bug check reboot the machine itself (AutoReboot=1is already set there), and expect a file written just before a reset to come back whitespace-filled.
A pool walk will not finish over 115200 baud. It reads every committed pool page and times out at 240s, so on a serial bench "x64-only" and "too slow over this wire" cannot be told apart.
Live kernel + driver IOCTL gotchas (learned driving HEVD over KDNET)
Loading HEVD on an ARM64 bench takes two things, and the error names neither.
StartService FAILED 577 ("cannot verify the digital signature") means both bcdedit /set
testsigning on (a reboot) and the driver's signing certificate imported into
Cert:\LocalMachine\Root — test signing has nothing to chain to otherwise, and an unexpired cert
that is simply untrusted looks identical to an expired one. TrustedPublisher refuses with
E_ACCESSDENIED and is not needed for sc start of a non-PnP driver. Check HVCI
((Get-CimInstance Win32_DeviceGuard -Namespace root\Microsoft\Windows\DeviceGuard).SecurityServicesRunning)
before blaming signing; 0 means it is not the cause.
A crash out of an exploit client is usually not a driver bug. HEVD's stack-overflow client on
this bench bug-checks 0xFC with the kernel faulting at the user-mode payload — its ROP chain
never disables privileged execution of a user page — so the stack is nt-only and carries no
HEVD frame at all. A fixture that needs a driver frame wants a path that faults inside the
driver, not a failed exploit.
Getting HEVD to bug-check at all is harder than it looks, because it is written to survive.
Every trigger is wrapped in __try/__except, so a kernel-mode access violation is caught and
returned as a status: the null dereference answers STATUS_ACCESS_VIOLATION with the machine still
running, the non-paged pool overflow answers success and quietly corrupts the pool, and the UAF
double free answers success twice and surfaces minutes later on a heap-maintenance worker thread as
a 0x13A whose stack is nt-only — the one shape a driver-attribution fixture must not have.
What SEH cannot catch is a fail fast. HEVD_IOCTL_BUFFER_OVERFLOW_STACK_GS compiles its trigger
with /GS, so overrunning the buffer corrupts the cookie and the driver's own __report_gsfailure
runs mov w0, #2; brk #0xf003 — 0x139 KERNEL_SECURITY_CHECK_FAILURE, raised inside the driver.
That is how docs/samples/082126-7015-01.dmp was made (issue #154); docs/smoke-test.md has the
one-line recipe.
DbgEng's module inventory is the debugger's, not the target's, and .reload is two operations
wearing one name. A kernel attach starts from what it can read at connect time, so a driver
loaded before the debugger dialled in is in the target and absent from lm — which is
#85, where a running challenge driver read as
"not loaded". The gap is not small: measured on the CTF guest 2026-08-30, a fresh attach held
1 module and a refresh found 158. IDebugSymbols::Reload("") resynchronises the list and leaves symbols deferred;
/f additionally fetches every PDB. modules { "refresh": true } is the first half on its own
(worker::resynchronise). Four things bite when editing it:
- The refresh costs the symbol state, on a live target and not on a dump. Measured both ways
(2026-08-30, engine DLLs bundled): a launched
cmd.exegoes all-five-pdbafter a.reload /fand comes back with fourdeferredandntdllstillpdb, while the checked-in kernel dump keepsntatpdbacross a refresh and discards nothing. A live reload re-reads the module list and the entries are rebuilt; a dump's list is its own header. So the note says on a live target and most modules, and anything that refreshes after a live symbol load has undone it. The first attempt at this measurement was taken on a host whose engine had nosymsrv.dllormsdia140.dll— the five modules could only reachexportfallback, so the effect read as smaller than it is and the dump half was never asked. Check the engine is bundled before measuring anything symbol-shaped here. - Order is the whole of the CTF tier's claim.
a_messagemanager_ctf_fixture_is_visible_through_mcpasksmodules { "refresh": true }beforeload_kernel_symbols, deliberately: that helper's unqualified.reload /fresynchronises the inventory as a side effect, so amodulescall after it passes whether or notrefreshdoes anything at all. Moving it back below the symbol setup keeps the test green and deletes what it is for. - The refresh is bounded, and a refresh the bound stops makes the inventory smaller. Measured
on the ARM64 bench over 115200-baud serial (2026-10-13, dbgscope's
examples/reload_interrupt_probe.rs): the first refresh after an attach read 181 modules in 3.9s, and one stopped at 0.5s, 1s and 2s left 20, 43 and 91 — the engine discards its list and rebuilds it. A repeat took 57ms from the engine's cache, so to measure a stop again you need a fresh attach or a.cache flushallfirst. And a break left pending — raised with nothing bounded running to read it — used to make the next refresh return success with 0 modules; dbgscope drains it now, and that is the first thing to suspect if a refresh ever reports an empty inventory again. - A failed refresh is reported, not raised, and the note goes above the tables. A caveat under a listing arrives after the conclusion it was there to prevent, which is the exact failure the issue is about.
Read a driver's IOCTL codes out of its own dispatch — do not take them from a published list.
This build's are not the ones HEVD's widely-quoted table gives, and the code that table calls the
null dereference is FREE_UAF_OBJECT here. Sending the wrong one is not always harmless: several
of them corrupt the kernel silently. The dispatch walk earlier in this section and decode_ioctl
are how to read them; on ARM64 the switch is a chain of sub wN, wM, #0x222, lsl #12 against a
literal, and each case block's DbgPrintEx format string names the handler.
Also: HEVD returns STATUS_UNSUCCESSFUL from handlers that succeeded. AllocateUaFObject*
initialises its status to 0xC0000001 and never sets it on the success path, so sc-style error 31
out of the harness means nothing. Trust the resulting state, not the status.
Attach by profile, not by connection string — always, for any live target. attach_kernel
{ "profile": "<name>" } resolves the connection inside the server (src/kdconn.rs), so the
target's debug key never lands in a tool argument — and therefore never in the client's
transcript, where one key previously ended up replicated across hundreds of records.
attach_kernel {} lists the profiles this host has. Configure one with
WINDBG_MCP_PROFILE_<NAME> or %USERPROFILE%\.windbg-mcp\profiles.json; raw connection still
works for a target nothing is configured for, and is the last resort rather than the quick option.
A raw connection now also reaches a second place: with recording on (.claude/rules/transcripts.md) it is written to the
server's own transcript file, scrubbed to key=<redacted>. That backstop is not a reason to pass
one. A profile keeps the key out of the request, so there is nothing for either transcript to
redact, and redaction is a thing that has to keep working while a key never sent cannot leak.
The live smoke tier (.claude/skills/tiers/SKILL.md) is the one sanctioned exception: WINDBG_MCP_SMOKE_KERNEL is a raw
connection string, passed straight to attach_kernel { "connection": … }, and is deliberately
not a profile — the tier has to exercise the explicit path, and it is a variable in a developer's
own shell rather than something a client ever sees.
A worker process does not inherit WINDBG_MCP_PROFILE_* (engine::spawn_worker strips them):
it is told the one connection it is opening over its private pipe, and a launched debuggee would
otherwise inherit every configured key on the host.
A live kernel detached in the first second of boot stops again, and it is not end_session's
fault. Measured 2026-09-15 on the CTF guest, and worth reading closely because the first three
readings of it here were wrong.
What happened: a session attached at System Uptime: 0 days 0:00:00.437 with one processor up,
worked while the guest sat at that break, and ended cleanly (released: true). Re-attaching found
0:00:00.453. That looks like a freeze and is not one -- the guest ran for 16 milliseconds and
stopped again. A resume that failed advances zero. Sixteen milliseconds is the guest resuming,
reaching the next KD break-in, and halting there with no debugger left to continue it: the
kdnic.sys settling break-ins described above, which is why that paragraph says to go through
them until boot proceeds.
It does not reproduce once the guest is up. Thirteen teardowns at ~6s, 16s, 17.9s, 24s,
31s, 38.9s and 42 minutes of uptime all left it running, with uptime advancing across the gap
each time -- and eleven runs of the live-kernel tier's attach/detach test reported "resumed and
detached, and is running" eleven times out of eleven, never the halted disposition. So the window
is sub-second, not "early boot", and reproducing it needs an attach already parked when the
guest dials in rather than one that finds it already connected.
The remedy is therefore not in the teardown. Either go through the settling break-ins before
ending the session, or accept that a guest detached inside that window waits for the next debugger
-- and a fresh attach plus qd releases it.
Two things the incident is still good for.
end_session genuinely could not say which happened, and now can. dbgscope::end_session resumes
and actively detaches a live kernel on purpose -- its comment is explicit that a passively detached
one "stays FROZEN, one CPU halted, the rest spinning" -- but it discarded the resume's answer, and
the worker filled target_left_running from attached_to_a_live_process(), which reads the
attached-process table and is false for a kernel. A resumed kernel and a closed dump therefore
gave the same answer. Both are fixed; a kernel now reports true or false and says qd when it
is the latter. That defect is real and was never what this incident showed -- the resume here
succeeded.
And do not read worker_terminated as the tell: it is !matches!(outcome, AlreadyGone | Stale),
so it is true after an ordinary successful release too. An earlier draft of this note said the
opposite, and DONE.md's own entry on DEBUG_END_PASSIVE had already said it correctly.
So after ending a live-kernel session there are two questions, and the result answers one of them.
A resume that failed is now in the result: target_left_running is false and the text names
qd, and a supervisor teardown with no caller logs the same at error!. What the result cannot
separate is ran-on from resumed-and-re-broke -- both are true, because both resumed, and only the
guest's uptime across the gap tells them apart. A guest found at almost the uptime it was left
at resumed and stopped again; one found seconds later ran on.
KDNET attach is a blocking wait, by design. A live kernel needs WaitForEvent(INFINITE) (a finite
timeout returns E_NOTIMPL and never drives the link). So if the target isn't reachable, the
attach_kernel MCP call reports a timeout while its worker process can remain parked in the
wait. The session becomes kernel_unresolved; late completion does not reopen it. Consequences:
- The park costs that session only. Other sessions and every other tool keep working, so an
attach that is going nowhere is no longer a reason to restart the server.
session_statussays how long it has been waiting and whether that is past the point a healthy link takes; ordinaryend_sessionpreserves it and reportsrecovery_required. Never send ACTIVE as a timeout-recovery attempt. Inspect target health out of band before an explicit session ID andkernel_handoff_pidauthorizes termination of the exact owned worker. This is NOT resume/detach. - Do not re-run the attach while it is still waiting. The connection was already claimed, so a
retry risks a second controller. Supervisor-local endpoint reservations block it, but another
server/native debugger is outside that registry. Verify the old worker has exited and the
endpoint is free before starting one recovery controller. Supervisor-loss orphans need manual
recovery; restarting the server does not adopt them. See
docs/sessions.md. - Diagnosing why nothing dialed in is still out-of-band work (PowerShell): check the debugger is
listening (
Get-NetUDPEndpoint -LocalPort 50000→ owned bywindbg-mcp.exe, which will be the worker process) and whether any VM is running. - The target must dial this host: on the target,
bcdedit /dbgsettings net hostip:<debugger-ip> port:50000 key:<key>— colons, not=.hostipmust be the debugger host's current IP. Symbols are not pulled over the KD wire (see below). - After a target reboot, the settling KD link shows repeated break-ins in
kdnic.sys(the KD NIC transport:nt!DbgBreakPointWithStatus←kdnic!TXTransmitQueuedSends). These are not real stops —gothrough them until boot proceeds.
Walking a service-loaded driver's IOCTLs live. sxe ld:<drv>.sys breaks on module load, which is
before DriverEntry runs — so the driver object's MajorFunction table is not populated yet
(driver_object shows defaults / "is not a driver object"). To let DriverEntry run and populate it:
- Compute the PE entry point from the header:
? <base> + dwo(<base> + dwo(<base>+0x3c) + 0x28). bpit,go. At entry,@rcx=DriverObject,poi(@rsp)= return addr (intont!PnpCallDriverEntry).bpthat return,go— now the table is populated.MajorFunction[0x0e](IRP_MJ_DEVICE_CONTROL, the IOCTL dispatch) is atDriverObject+0xe0. In the dispatch, theIoControlCodeisIO_STACK_LOCATION+0x18; the current stack location isIRP+0xB8.ufthe dispatch to read the (usually binary-search) IOCTL switch,decode_ioctleach code, and read each case'sDbgPrintExstring (da) for the human name.
That recipe assumes a WDM driver, and most in-box drivers here are not one. A KMDF driver's
table is ordinarily the framework's — ordinarily, because a client passing
WdfDriverInitNoDispatchOverride keeps its own, so read the module name on the entries rather than
assuming either: Wdf01000!FxDriver::Initialize writes FxDevice::Dispatch or
FxDevice::DispatchWithLock into all 28 slots from DRIVER_OBJECT+0x70 onwards, so step 3 hands
you framework code and the uf in it has no IOCTL switch — correctly, because the codes are
compared somewhere in the driver's own code that this server cannot yet resolve, and not
necessarily in any callback the framework registered
(FOLLOWUPS.md item 108 step 2). driver_surface now says so in a framework field rather than
leaving you to read 28 identical pointers, and driver_hazards reports the driver-side tell — an
import of WdfVersionBind from WdfLdr.sys. Check that before concluding a driver dispatches
nothing, which is the detour this note exists to save: 132 of the 445 driver images in
System32\drivers on this bench are KMDF clients, including most of the in-box Hyper-V device
drivers (Vid, vmbus, vpci, storvsp, vmstorfl) — though not all of them, vmswitch,
winhv, winhvr, hvsocket and vmbkmcl carrying no bind import at all. UMDF
(WUDFx02000.dll, user mode) is a third case and is recognised nowhere here.
Symbols must be on the debugger host. PDBs are never fetched from the target over KD. Find the
exact PDB identity the engine wants with !sym noisy; .reload /f <mod> (it prints <pdb>\<GUID>\...),
then get that PDB onto this host. Gotcha: .sympath / .sympath+ swallow the rest of the command
line — they ignore ;, so anything chained after them (; .reload ...) is parsed as path text.
Issue .sympath alone, or use the set_symbol_path tool (goes through the DbgEng
AppendSymbolPath/SetSymbolPath API, immune to the quirk; appends + reloads). When a driver's
module!Symbol names don't resolve, ask the user for the PDB folder and apply it with that tool.
Nothing resolves at all without msdia140.dll beside the engine — symsrv.dll finds a PDB and
that one parses it, so without it every module reports Symbol Type: EXPORT - PDB not found even
when the identity was known and the file was downloaded. symsrv.dll is the other half, and
System32 usually does not ship it: on a machine with neither, a srv* path downloads nothing.
Usually, because it is not a constant and this repo believed it was — probing both CI runners
(issue #153) found one in windows-latest's System32 and none in the ARM64 image windows-11-arm
named at the time, so check the host in front of you (where.exe symsrv.dll) rather than assuming
either way. That qualifier is load-bearing: GitHub migrated that label onto a different image on
2026-09-23 and nobody has probed the new one, so the reading is about a machine, never a label. Worth
knowing because of how that presents on a dump — not as missing symbols but as a memory read
failing (0x8007001E), since a kernel dump's virtual addresses are translated through structures
the engine locates with nt's symbols. That symptom was read as an ARM64 engine limitation for a
while (issue #142); it is not one, and an engine with symbols reads x64 and ARM64 dumps alike. It is not store-package-only, which
this repo believed for a while: Visual Studio Build Tools ships it, including an ARM64 build, at
…\BuildTools\DIA SDK\bin\arm64\msdia140.dll. Copy it next to the exe (target\release, and
target\debug for the smoke tiers — and target\debug\deps if a unit test loads the engine,
which is where libtest's binaries actually run from; this guidance said target\debug alone until a
2026-08-26 test met System32's engine and failed with an error about something else entirely).
Warm the cache once afterwards — attach and .reload /f nt
— because the first fetch takes minutes and everything around it times out, which reads convincingly
as the parser having made things worse.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

