memoryjs

The Debugger wrapper class simplifies hardware breakpoint management by handling register selection and event listening automatically.

Key Advantages:

• No need to manually pick a hardware register (DR0-DR3).
• No need to pass the size parameter for strings (the wrapper attempts to read the string to determine size).
• Debug events are handled via standard event listeners.
• setHardwareBreakpoint returns the specific register used for the breakpoint.

Trigger Types:

• memoryjs.TRIGGER_ACCESS: Breakpoint occurs when the address is accessed.
• memoryjs.TRIGGER_WRITE: Breakpoint occurs when the address is written to.

const hardwareDebugger = memoryjs.Debugger;

// 1. Attach
hardwareDebugger.attach(processId);

// 2. Set breakpoint
const address = 0xDEADBEEF;
const trigger = memoryjs.TRIGGER_ACCESS;
const dataType = memoryjs.INT;
const register = hardwareDebugger.setHardwareBreakpoint(processId, address, trigger, dataType);

// 3. Listen for events
hardwareDebugger.on('debugEvent', ({ register, event }) => {
  console.log(`Hardware Register ${register} breakpoint`);
  console.log(event);
});

// Or listen to a specific register returned by setHardwareBreakpoint
hardwareDebugger.on(register, (event) => {
  console.log(event);
});

If you choose not to use the Debugger wrapper, you must manually manage registers, data sizes, and the debug event loop.

Constraints:

• Only 4 hardware registers are available (memoryjs.DR0 through memoryjs.DR3). Only 4 breakpoints can be set at any given time.
• You must manually provide the size of the variable in bytes (e.g., 4 for int32). For strings, use the string length.
• You must implement a loop to call awaitDebugEvent and handleDebugEvent to process triggers.

Return Values:

• memoryjs.setHardwareBreakpoint returns a boolean indicating success.

const hardwareDebugger = memoryjs.Debugger;

// 1. Attach
hardwareDebugger.attach(processId);

// 2. Set breakpoint manually
const register = memoryjs.DR0;
const size = 4; // e.g. int32
const address = 0xDEADBEEF;
const trigger = memoryjs.TRIGGER_ACCESS;
const dataType = memoryjs.INT;

const success = memoryjs.setHardwareBreakpoint(processId, address, register, trigger, size);

// 3. Manual event loop
const timeout = 100;
setInterval(() => {
  const debugEvent = memoryjs.awaitDebugEvent(register, timeout);
  if (debugEvent) {
    memoryjs.handleDebugEvent(debugEvent.processId, debugEvent.threadId);
  }
}, timeout);

For custom data structures, you can use standard Node.js Buffer objects or the structron library.

Using structron for std::string

To read a std::string using structron, use the memoryjs.STRUCTRON_TYPE_STRING helper. This requires the process handle, the base address of the structure, and the target architecture ('32' or '64').

const stringType = memoryjs.STRUCTRON_TYPE_STRING(processObject.handle, structAddress, '64');

const Struct = require('structron');
const Player = new Struct()
  .addMember(stringType, 'name');

// To create the type, we need to pass the process handle, base address of the
// structure, and the target process architecture (either "32" or "64").
const stringType = memoryjs.STRUCTRON_TYPE_STRING(processObject.handle, structAddress, '64');

// Create a custom structure using the custom type, full example in /examples/buffers.js
const Struct = require('structron');
const Player = new Struct()
  .addMember(stringType, 'name');

The library allows you to open and map file mappings into a process's memory space.

API

• openFileMapping(fileName): Opens a file mapping object. Returns a handle.
• mapViewOfFile(processHandle, fileHandle, [offset], [viewSize], [pageProtection]):
  • Maps the file to the target process memory.
  • offset: Must be a multiple of 64KB.
  • viewSize: If 0, the entire file is mapped.
  • pageProtection: Defaults to memoryjs.PAGE_READONLY if not provided.

To map a file to the current Node process instead of a target process, use process.pid as the processHandle.

const processObject = memoryjs.openProcess("example.exe");
const fileHandle = memoryjs.openFileMapping("MappedFooFile");

// read entire file
const baseAddress = memoryjs.mapViewOfFile(processObject.handle, fileHandle.handle);
const data = memoryjs.readMemory(processObject.handle, baseAddress, memoryjs.STR);

// read 10 bytes after 64KB
const baseAddressOffset = memoryjs.mapViewOfFile(processObject.handle, fileHandle.handle, 65536, 10, memoryjs.PAGE_READONLY);
const buffer = memoryjs.readBuffer(processObject.handle, baseAddressOffset, 10);
const dataString = buffer.toString();

const success = memoryjs.closeHandle(fileHandle);

Search for byte patterns across modules or memory regions.

• findPattern(handle, pattern, flags, patternOffset): Scans all modules and memory regions.
• findPattern(handle, moduleName, pattern, flags, patternOffset): Scans a specific module.
• findPattern(handle, baseAddress, pattern, flags, patternOffset): Scans a specific memory region or module at the provided baseAddress.

// sync: pattern scan all modules and memory regions
const address = memoryjs.findPattern(handle, pattern, flags, patternOffset);

// async: pattern scan all modules and memory regions
memoryjs.findPattern(handle, pattern, flags, patternOffset, (error, address) => {});

// sync: pattern scan a given module
const address = memoryjs.findPattern(handle, moduleName, pattern, flags, patternOffset);

// async: pattern scan a given module
memoryjs.findPattern(handle, moduleName, pattern, flags, patternOffset, (error, address) => {});

// sync: pattern scan a memory region or module at the given base address
const address = memoryjs.findPattern(handle, baseAddress, pattern, flags, patternOffset);

// async: pattern scan a memory region or module at the given base address
memoryjs.findPattern(handle, baseAddress, pattern, flags, patternOffset, (error, address) => {});