@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 Pattern Scanning: Memory scanning powered by chunked processing and an assembly-injected memmem for wildcard-free patterns. Supports full process scan via VirtualQuery, module-scoped scan, or arbitrary range scan.
• 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, ...): FixedNativePointer
• 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(sig): ScanResult — scan within this module's memory range.
• Module.scan(sig, moduleNames?): ScanResult — scan across multiple modules (default: all static modules).

Scanner & Pattern

High-performance memory pattern matching — no wildcards uses an assembly-injected memmem (faster than any JS-side byte loop), wildcard patterns use chunked byte comparison. Scanning is generator-based so it yields immediately on first match without loading all results into memory.

• new Pattern("55 8B EC ?? 56") — Create signatures with wildcard support.
• process.findPattern(sig) — Full process scan via VirtualQuery (all committed readable regions).
• Module.scan(sig, ['kernel32.dll']) — Module-scoped scan (static method on Module).
• process.findPatternInRange(sig, start, size) — Arbitrary range scan.
• ScanResult is lazy and generator-backed: use .first() to stop after one match, .all() to exhaust.

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