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

# Python SDK

Drive the debugger from Python with the `ntoseye` module: the same introspection and run-control surface as the REPL, with Python owning the loop. The wheel is self-contained, so this needs neither the `ntoseye` CLI nor a build with the embedded interpreter. The module ships type stubs, so an editor shows every method and its docstring; the outline below maps REPL commands to methods.

Data watchpoints currently require KD (KDCOM or KDNET), apply globally across guest address spaces, and at most four can be active at a time.

## Install via pip

```sh
pip install ntoseye
```

## Usage

```python
import ntoseye

# defaults to backend="kd", connect="/tmp/ntoseye-kd.sock"
dbg = ntoseye.attach()

# KDNET listens on 0.0.0.0:50000 unless connect= is supplied.
# memory_source accepts "auto" (default), "host", or "kd".
# dbg = ntoseye.attach(backend="kdnet", key="1.2.3.4", memory_source="kd")

for proc in dbg.processes():  # _EPROCESS cursors
    print(proc.UniqueProcessId, proc.ImageFileName, hex(proc.addr))

fun = dbg.eval("nt!KeBugCheckEx")
print(hex(fun), dbg.read(fun, 16).hex())

# any REPL command, returned as text (styling stripped)
print(dbg.run_command("!analyze -v"))
```

The module is a native extension built with [maturin](https://www.maturin.rs/); see [`ntoseye-py/README.md`](../ntoseye-py/README.md) for build info and [`examples/standalone/`](../examples/standalone/) for standalone scripts.

# Custom commands

In addition to the standalone [Python SDK](#python-sdk), `ntoseye` can run Python commands inside the live REPL; the same SDK, but bound to the session you're already debugging rather than a separate attach. This requires a build with the embedded interpreter, which is enabled by default for Cargo and source builds. Prebuilt release archives omit it for portability.

Drop any `*.py` file in `~/.ntoseye/commands/`; they're auto-loaded at REPL startup. Run `reload-scripts` in the REPL to pick up edits without restarting.

Custom commands need no `pip install ntoseye` as the module is served by the embedded interpreter. However, it may be worth installing to get LSP completions and type diagnostics while you write them.

```python
import ntoseye.repl as repl

# repl.Process is the completion type for processes, so the user can make use of `> hide ..<TAB>`
@repl.command("hide", "Unlink a process.\n(usage: hide <pid|name>)", target=repl.Process)
def hide(dbg: repl.Debugger, target=None):
    p = dbg.process(target)
    ...
```

See [`examples/commands/`](../examples/commands/) for more examples.