@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, get/set thread context, suspend/resume, and track exit codes.
• Module Helper: Easy access to loaded modules (kernel32.dll, msvcrt.dll, etc.) and function addresses.
• Low-level FFI: Direct access to Kernel32Impl and MsvcrtImpl for advanced Win32 API calls.
• Safe Handles: Automatic handle cleanup using FinalizationRegistry.
• Integrated Logging: Scoped 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

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