ntoseye 0.32.0

WinDbg-like kernel debugger for Windows, from Linux and macOS
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

# Driver replacement map (`.kdfiles`)

`.kdfiles` makes the target load a driver image **from the host filesystem** instead of from its own disk, so a driver can be rebuilt and reloaded without copying the `.sys` into the VM on every iteration.

When the kernel debugger is enabled, `nt!MmLoadSystemImage` asks the debugger for the image before falling back to the copy on the target's disk. `ntoseye` answers that request from the map; an unmapped name is refused, and the target silently uses its own copy.

This feature works over KDCOM and KDNET. The `capabilities` command reports it as `host-served target files`. On the GDB, memory, and dump backends `.kdfiles` warns that the map will never be consulted.

## Usage

```
.kdfiles                        show the map and what it has served
.kdfiles <map-file>             load a WinDbg driver replacement map file
.kdfiles -m <target> <host>     add one mapping
.kdfiles -d <target>            remove one mapping
.kdfiles -c                     clear the map
```

The quick form takes the driver name and the host path.

```
kd:p1.1> .kdfiles -m mydriver.sys /home/me/build/mydriver.sys
Mapped mydriver.sys -> /home/me/build/mydriver.sys.
```

Then reload the driver in the guest (`sc stop mydriver` / `sc start mydriver`, or the loader of your choice). The debugger reports each image it serves.

```
note: kdfiles: target opened \??\C:\Users\me\source\repos\mydriver\x64\Debug\mydriver.sys
      -> /home/me/build/mydriver.sys (7920 bytes)
```

`.kdfiles` with no argument shows the map and serving totals. Use these to check whether the mapping matched and served the image.

```
kd:p1.1> .kdfiles
mydriver.sys  ->  /home/me/build/mydriver.sys

served 1 open, 7920 bytes read, 0 refused
```

Quote host paths containing spaces with either `'` or `"`.

```
kd:p1.1> .kdfiles -m mydriver.sys '/home/me/my builds/mydriver.sys'
Mapped mydriver.sys -> /home/me/my builds/mydriver.sys.
```

After rebuilding, reload the driver in the guest. The mapping does not need to be reloaded.

## Name matching

The target requests the path passed to `MmLoadSystemImage`, typically the image path recorded in the Service Control Manager database. This can differ from the host path.

Matching is case-insensitive, separator-insensitive, and suffix-based, mirroring WinDbg on Windows 10 and later.

| Map target | Matches |
| --- | --- |
| `mydriver.sys` | any directory, including `\SystemRoot\System32\drivers\mydriver.sys` and `\??\C:\build\mydriver.sys` |
| `drivers\probe.sys` | `\SystemRoot\System32\drivers\probe.sys`, but not `...\mydrivers\probe.sys` |
| `\SystemRoot\System32\drivers\probe.sys` | only that full path |

Use a bare filename to match any directory. Matching requires a `\`-delimited boundary, so `probe.sys` never matches `xprobe.sys`.

## Map files

`.kdfiles <map-file>` reads WinDbg's driver replacement map format. Each three-line record contains the literal word `map`, the target name, and the host path. Blank lines and `;` / `//` comments are ignored. Relative host paths resolve against the map file's directory.

```
; drivers.map
map
mydriver.sys
build/mydriver.sys

map
OtherDriver.sys
/home/me/other/OtherDriver.sys
```

Loading a map replaces the previous one after validating every host path.

## Behaviour and limits

- **Read-only.** The map serves driver images; target-driven writes to a host path are refused with `STATUS_ACCESS_DENIED`.
- **Takes effect on the next load.** An already-loaded image is not replaced; unload and reload the driver.
- **Signature enforcement still applies.** The served bytes go through the same validation as an on-disk image, so a test-signed driver still needs test signing enabled on the target.
- **Unmapped names fall back to the target's disk copy.**
- Handles do not survive a reboot or a reconnect; the target re-opens what it needs.
- At most 64 host files can be open at once.

## Troubleshooting

Set `NTOSEYE_KD_TRACE=1` to see every request, including the name the target asked for and the exact byte ranges it read.

```
kd: kdfiles: serving /home/me/build/mydriver.sys as \??\C:\...\mydriver.sys (7920 bytes, handle 0x1, ...)
kd: kdfiles: read handle 0x1 offset 0x0 want 3936 -> 3936 bytes
kd: kdfiles: read handle 0x1 offset 0xf60 want 3936 -> 3936 bytes
kd: kdfiles: read handle 0x1 offset 0x1ec0 want 48 -> 48 bytes
kd: kdfiles: close handle 0x1 (known: true)
```

If a driver load produces no `kdfiles` trace, check that the kernel debugger is enabled in the guest (`bcdedit /debug on`) and that the driver is being loaded by `MmLoadSystemImage` rather than already resident.

If it traces `no mapping for <name>`, compare that name against the map target; the bare-file-name form matches any directory.