@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 } from '@cheatron/native';

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

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

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

// Create a thread in the target process
const thread = proc.createThread(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.

• readMemory(address: bigint, size: number): Buffer
• writeMemory(address: bigint, buffer: Buffer): void
• createThread(startAddress: bigint, ...): Thread
• virtualQuery(address: bigint): MemoryBasicInformation

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: Pre-defined instances.
• getProcAddress(name: string): bigint
• Retrieve memory size via MODULEINFO querying.

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).
• process.findPatternFromModules(sig, ['kernel32.dll']) — Module-scoped scan.
• process.findPatternInRange(sig, start, size) — Arbitrary range scan.
• All of the above have findAll* variants that return every match.

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