@cheatron/native

Ergonomic Win32 process and memory management API for Cheatron, powered by Bun and Koffi.

Important

64-bit Windows only. This project exclusively targets 64-bit Windows environments.

Features

• Process Management: Open processes by PID, access the current process, and query memory information.
• Memory Operations: Read and write memory buffers from/to target processes.
• Thread Management: Create local/remote threads (supports CREATE_SUSPENDED flags), get/set thread context, suspend/resume, and track exit codes.
• Module Helper: Easy access to loaded modules, complete MODULEINFO retrieval, module dimension sizing, and function addresses.
• High-Performance Async Pattern Scanning: Memory scanning powered by async * generators and an assembly-injected memmem. Supports full process scan via VirtualQuery, module-scoped scan, or arbitrary range scan. (Wildcards are no longer supported for performance reasons).
• Assembly Generation: Test x86 assembly scripts and integrate safely with @cheatron/keystone.
• Low-level FFI: Direct access to Kernel32Impl, psapi, and MsvcrtImpl (includes memcmp and memmem) for advanced Win32 API calls.
• Safe Handles: Automatic handle cleanup using FinalizationRegistry.
• Integrated Logging: Centralized, shared static logging powered by @cheatron/log.

Installation

bun add @cheatron/native

Quick Start

import { Process, currentProcess, NativePointer } from '@cheatron/native';

// Open a process by ID
const proc = Process.open(1234);

// Read memory
const buffer = proc.memory.read(new NativePointer(0x10000000n), 1024);
console.log(buffer.toString('hex'));

// Write memory
proc.memory.write(
  new NativePointer(0x20000000n),
  Buffer.from([0x90, 0x90, 0x90]),
);

// Create a thread in the target process
const thread = proc.createThread(new NativePointer(0x30000000n));
thread.wait();
console.log(`Thread exited with: ${thread.getExitCode()}`);

proc.close();

Core Components

Process

The Process class provides methods for interacting with Windows processes. Use Process.open(pid) or Process.current() to get an instance. All address parameters accept any IPointer — wrap raw bigint values with new NativePointer(addr).

• memory.read(address: IPointer, size: number): Buffer
• memory.write(address: IPointer, buffer: Buffer): void
• createThread(startAddress: IPointer, ...): Thread
• memory.query(address: IPointer): MemoryBasicInformation
• memory.alloc(size, address?: IPointer | null, ...): NativePointer
• memory.free(address: IPointer): boolean
• memory.protect(address: IPointer, size, newProtect): number | null

Thread

Manage execution flow within processes.

• suspend() / resume(): number
• getContext(flags?: number): ThreadContext
• setContext(ctx: ThreadContext): void
• getExitCode(): number
• wait(timeoutMs?: number): WaitReturn

Module

Enumerate and interact with loaded DLLs.

• Module.get(name: string): Module
• Module.kernel32 / Module.crt / Module.ntdll / Module.kernelbase: Pre-defined lazy-cached instances.
• getProcAddress(name: string): NativePointer
• findPattern(pattern: Pattern): ScanResult — scan within this module's memory range.
• Module.scan(pattern: Pattern, moduleNames?): ScanResult — scan across multiple modules (default: all static modules).
• All results are returned via ScanResult which is an AsyncIterable.

Scanner & Pattern

High-performance memory pattern matching using an assembly-injected memmem (faster than any JS-side byte loop). Wildcards are not supported. Scanning is an async * generator-based process so it yields immediately on first match and prevents blocking the event loop.

• new Pattern("55 8B EC 56") — Create signatures (hex strings or byte arrays).
• process.findPattern(pattern: Pattern) — Full process scan via VirtualQuery (all committed readable regions).
• Module.scan(pattern: Pattern, ['kernel32.dll']) — Module-scoped scan (static method on Module).
• process.findPatternInRange(pattern: Pattern, memory: NativeMemory) — Arbitrary range scan.
• ScanResult is an AsyncIterable: Use for await (const entry of result), or await result.first(), await result.all().
• Access properties via async methods: await result.getLength(), await result.getAddresses(), etc.

Advanced FFI

For tasks not covered by the ergonomic API, you can use the raw implementations directly:

import { Kernel32Impl, MsvcrtImpl } from '@cheatron/native';

const hProcess = Kernel32Impl.GetCurrentProcess();
const ptr = MsvcrtImpl.malloc(1024);
MsvcrtImpl.free(ptr);

Development

This project uses Bun. To run tests on Linux, you need wine.

# Install dependencies
bun install

# Run tests (runs natively or via wine depending on environment)
bun test

# Build the project
bun run build

License

MIT