ntoseye
This package lets you control the ntoseye Windows kernel debugger from Python and run it from the command line.
For address-space-bound views and run control, see
docs/scripting/sdk.md.
The package also installs the ntoseye command, which gives you the REPL,
ntoseye mcp, dap, and gdbserver, and runs Python custom commands from
~/.ntoseye/commands/. To install the command in its own environment, run
uv tool install ntoseye or pipx install ntoseye.
Install
pip install ntoseye
Or build from source into a virtualenv with maturin:
cd python
python3 -m venv .venv
source .venv/bin/activate
pip install maturin
maturin develop --release
Or build a wheel and install it:
cd python
maturin build --release --out dist
pip install dist/ntoseye-*.whl
Quick start
import ntoseye
with ntoseye.attach() as dbg: # defaults to the kd backend
print(dbg.inspect.version())
for proc in dbg.processes:
print(proc.pid, proc.name)
For read-only inspection of a paused VM, select backend="memory".
dbg.processes holds process handles keyed by PID (dbg.processes[pid]), and
each process gives its own memory and modules through proc.memory and
proc.modules.
Type stubs
PyO3 introspection generates ntoseye/_ntoseye.pyi from the extension, taking
the signatures from the Rust types and the docstrings from the doc comments.
CI fails when the stub in the repository differs from a newly generated one, so after you change the Rust surface, regenerate the stub and commit the result:
maturin develop --release --generate-stubs
Tests
pip install pytest mypy
pytest tests # target-free surface tests
mypy --strict -p ntoseye # the stub and package type-check
NTOSEYE_TEST_BACKEND=kd NTOSEYE_TEST_CONNECT=/tmp/ntoseye-kd.sock pytest tests
NTOSEYE_TEST_BACKEND=gdb NTOSEYE_TEST_CONNECT=127.0.0.1:1234 pytest tests
The last two commands also run tests/test_live.py and
tests/test_stub_types.py on a guest, over KD or QEMU's GDB stub. They break
in, step, set breakpoints on hot kernel functions, and resume the guest. The
tests of breakpoints in the Windows hypervisor, the secure kernel, and guest
partitions need the gdb backend, and skip on kd.
By default (auto), the tests read guest memory from the VM process when they
can. Add NTOSEYE_TEST_MEMORY_SOURCE=kd to read it over KD instead, which
needs no root for UTM on macOS and is required for a remote target.
Releasing portable wheels
The workflow .github/workflows/release.yml builds the release wheels with PyO3/maturin-action on native GitHub runners:
- The Linux x86-64 and ARM64 wheels build on
ubuntu-22.04andubuntu-24.04-arminside thequay.io/pypa/manylinux_2_28_*images, which makes themmanylinux_2_28wheels. - The Apple Silicon wheel builds on the native ARM64
macos-14runner.
Before the upload, each wheel must pass twine check and the target-free tests (tests/test_surface.py) in a clean virtual environment.
To make a Linux release wheel locally, run this from the repository root (Docker is required):
docker run --rm -e CARGO_TARGET_DIR=/tmp/target -e HOST_IDS="$(id -u):$(id -g)" \
-v "$PWD":/io -w /io/python quay.io/pypa/manylinux_2_28_$(uname -m) bash -c '
dnf install -y clang &&
curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal &&
source ~/.cargo/env &&
/opt/python/cp312-cp312/bin/pip install maturin &&
/opt/python/cp312-cp312/bin/maturin build --release --out dist --compatibility manylinux_2_28 &&
chown -R "$HOST_IDS" dist'
1 maintainer
Metadata
1 maintainer
Release files for ntoseye 0.50.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ntoseye-0.50.0-cp39-abi3-manylinux_2_28_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ x86-64 | Details |
| ntoseye-0.50.0-cp39-abi3-manylinux_2_28_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ ARM64 | Details |
| ntoseye-0.50.0-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 48.1 MB
Release files / ntoseye-0.50.0-cp39-abi3-manylinux_2_28_x86_64.whl
| Download URL | ntoseye-0.50.0-cp39-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 16.2 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
d7056e685e24cf38f2df9d0810fe77a53f20e25ae8b3182bad8526d41a63e9b9
|
|
BLAKE2b-256 checksum How to use checksums |
dd1e0befaeacc87defc9897764023c3a971812263b56e388862bf66041b609dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / ntoseye-0.50.0-cp39-abi3-manylinux_2_28_aarch64.whl
| Download URL | ntoseye-0.50.0-cp39-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 16.9 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
49bfeda4f7d40ae2d39ea475bc9cea0051fe549debf92af2bbb528dea3aadb32
|
|
BLAKE2b-256 checksum How to use checksums |
e4ebc7d17f63aa47dc0fbb85a99a774d5396ca29487c85bfa49dcd8af52c1170
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / ntoseye-0.50.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | ntoseye-0.50.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.9 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
27d05e38c985161286ee2d07fe4f0593197de798e9f20d9cc122e55ccf23b9f5
|
|
BLAKE2b-256 checksum How to use checksums |
6e7e4378dc952eef85f0cf578da236e74f042ae46314db129d0d9efb1688414f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency log
