phnt-rs

Rust bindings for the Windows NT Native API headers from the phnt project.

Copyright (c) 2025 Magnet Forensics

Overview

This crate provides comprehensive Rust FFI bindings for the Windows NT Native API. The bindings are generated from the phnt project, which is the most complete and up-to-date collection of Native API definitions maintained by the System Informer team.

What is the NT Native API?

The Windows NT Native API is the lowest-level user-mode API available on Windows. It sits below the Win32 API and provides direct access to kernel services. While largely undocumented by Microsoft, it's essential for:

• Low-level system programming
• Security research and forensics
• Debugging and instrumentation tools
• System monitoring and analysis

Features

• Pre-generated Bindings: No LLVM/clang required for normal use
• Multi-architecture: Supports x86_64, x86 (32-bit), and aarch64 (ARM64)
• Comprehensive Coverage: Includes all phnt headers with thousands of types, functions, and constants
• Type Compatibility: Re-exports windows_sys and nt_string for ecosystem compatibility
• Helper Extensions: Includes NtCurrentTeb(), NtCurrentPeb(), and other convenience functions
• Maintained Upstream: Tracks the actively-maintained phnt project via git submodule

Installation

Add this to your Cargo.toml:

[dependencies]
phnt-rs = "0.1"

The pre-generated bindings include all definitions (PHNT_WINDOWS_NEW), so no feature flags are needed for most use cases.

Usage

⚠️ Warning: This is a low-level FFI binding crate. All functions are unsafe and call into undocumented Windows APIs. Improper use can cause system instability or crashes.

Linking

This crate does not automatically link to any DLL. You must explicitly link against the appropriate DLLs:

DLL	Functions
ntdll.dll	Nt*, Zw*, Rtl*, Ldr*, Etw*, Dbg*
win32u.dll	NtUser*, NtGdi*

#[link(name = "ntdll")]
extern "C" {}

Example: Using TEB/PEB

use phnt_rs::*;

// Link against ntdll.dll
#[link(name = "ntdll")]
extern "C" {}

fn main() {
    unsafe {
        // Get current TEB (Thread Environment Block)
        let teb = phnt_rs::ext::NtCurrentTeb();

        // Get process/thread IDs
        let pid = phnt_rs::ext::NtCurrentProcessId();
        let tid = phnt_rs::ext::NtCurrentThreadId();
        println!("PID: {}, TID: {}", pid, tid);

        // Access PEB (Process Environment Block)
        let peb = phnt_rs::ext::NtCurrentPeb();
        println!("Image base: {:?}", (*peb).ImageBaseAddress);
    }
}

Re-exports

This crate re-exports useful companion crates:

// Access nt_string types for UNICODE_STRING handling
use phnt_rs::nt_string::unicode_string::NtUnicodeString;

// Access windows_sys types
use phnt_rs::windows_sys::Win32::Foundation::HANDLE;

Building from Source

Prerequisites

For normal use, only a Rust toolchain is required. The crate ships with pre-generated bindings.

To regenerate bindings, you additionally need:

• LLVM/Clang (for bindgen)
• Windows SDK

Build

git clone --recursive https://github.com/magnetforensics/phnt-rs.git
cd phnt-rs
cargo build

Regenerating Bindings

To regenerate bindings (requires LLVM/clang):

# Regenerate for current architecture
cargo build --features regenerate

# Regenerate for specific architecture
cargo build --features regenerate --target x86_64-pc-windows-msvc
cargo build --features regenerate --target i686-pc-windows-msvc
cargo build --features regenerate --target aarch64-pc-windows-msvc

Then copy the generated bindings from target/<arch>/debug/build/phnt-rs-*/out/bindings.rs to src/ffi/<arch>.rs.

PHNT Version Features

When regenerating, you can control which Windows version's definitions are included:

cargo build --features "regenerate,phnt-windows-10"

Available version features: phnt-windows-xp through phnt-windows-11-24h2, and phnt-windows-new (default, all definitions).

Project Structure

phnt-rs/
├── Cargo.toml          # Project manifest
├── build.rs            # Build script (bindgen when regenerate feature enabled)
├── deps/
│   └── phnt/           # Git submodule: winsiderss/phnt
├── src/
│   ├── lib.rs          # Main library with documentation
│   ├── convert.rs      # Conversion utilities for UNICODE_STRING types
│   ├── wrapper.h       # C header wrapper for bindgen
│   ├── cty/            # C type definitions
│   ├── ext/            # Extension functions (NtCurrentTeb, etc.)
│   └── ffi/            # Pre-generated bindings per architecture
│       ├── x86_64.rs
│       ├── x86.rs
│       └── aarch64.rs
└── README.md

Development

Updating to Latest phnt

cd deps/phnt
git pull origin master
cd ../..
# Regenerate bindings for all architectures
cargo build --features regenerate --target x86_64-pc-windows-msvc
cargo build --features regenerate --target i686-pc-windows-msvc
cargo build --features regenerate --target aarch64-pc-windows-msvc
# Copy generated files to src/ffi/

Testing

cargo test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Magnet Forensics

The original phnt headers are also licensed under the MIT License. Copyright (c) System Informer project

Attribution

This project uses the phnt headers maintained by the System Informer team. These headers have been meticulously maintained since 2009 and represent the most comprehensive collection of NT Native API definitions available.

Disclaimer

This crate provides bindings to undocumented Windows APIs. Microsoft does not officially support these APIs, and they may change without notice between Windows versions. Use at your own risk.

Contributing

Contributions are welcome! Please note that the bindings themselves are automatically generated, so most contributions should focus on:

• Improving the build process
• Adding examples
• Improving documentation
• Reporting issues with binding generation

Resources

• phnt project
• System Informer
• Windows Internals