AI Memory — Processes

AI-first map of process attachment and memory process readers.

Memory / Process Discovery Map

Reference map for core process readers, process memory access, pointer chains, pattern scanning, PE helpers, modules, code caves, and backend selection.

Optional package-specific readers belong in nuget/.

Select a process and read its modules

In an EyeAuras script with the Memory module loaded, list candidates first:

csharp
using EyeAuras.Memory;

foreach (var info in LocalProcess.GetProcesses())
    Log.Info($"{info.Id} {info.ProcessName}");

Pass the selected PID to this ordinary C# helper. The returned module snapshot outlives the reader; its addresses remain meaningful only while the target and its modules exist.

csharp
using System.Collections.Generic;
using EyeAuras.Memory;

static IReadOnlyList<ProcessModuleInformation> ReadModules(int processId)
{
    using var process = LocalProcess.ByProcessId(processId);
    return process.GetProcessModules();
}

ProcessModuleInformation supplies ModuleName, FilePath, BaseAddress (IntPtr) and Size in bytes. The reader owns its handles; process.Memory is borrowed. Keep the reader open for subsequent reads instead of returning its Memory from a using block. ByProcessName accepts names with or without .exe; use a PID to select a particular instance.

For an interactive script, obtain a window through the OSD picker:

csharp
using EyeAuras.Memory;
using EyeAuras.Shared.Osd;

var window = await GetService<IOsdSelectionService>().PickWindow();
{
    using var process = LocalProcess.ByProcessId(window.ProcessId);
    foreach (var module in process.GetProcessModules())
        Log.Info(module.ModuleName);
}

The window handle is borrowed. Picker cancellation exits through its cancellation exception; it does not provide a process to open. IsValid describes the reader, not a guarantee that the target will stay alive. See selection.

A helper with an open reader, an actual module name and a known byte offset of an int field can read it as follows:

csharp
using EyeAuras.Memory;
using EyeAuras.Memory.Scaffolding;

static int ReadModuleInt32(IProcess process, string moduleName, int offset)
{
    using var memory = process.MemoryOfModule(moduleName);
    return memory.Read<int>(memory.BaseAddress + offset);
}

GetProcessModule matches names without case sensitivity and throws ArgumentException when absent; TryFindProcessModule returns a Boolean. MemoryOfModule creates a view, but reads take absolute addresses and do not automatically enforce its bounds. Disposing the view does not dispose the process. For signatures use pattern scanners; for scalar, array and pointer-chain operations see the Memory reference.

In an embedded host, declare UseMemory() and await EnsureReadyAsync() with the runtime and Memory modules available. Metadata references alone do not register ILocalProcessBuilder; LocalProcess throws InvalidOperationException without it. See Embedded SDK.

User Intents

  • Attach to a process and read/write memory.
  • Choose local, native local, kernel-driver, or MPFS backend.
  • Attach from a PID selected via window picker.
  • Resolve modules, imports, exports, PE metadata.
  • Follow pointer chains.
  • Resolve a live local thread id or thread handle to its TEB address.
  • Enumerate processes through a kernel _EPROCESS list when the backend can read kernel virtual memory.
  • Read process parameters, threads, and VAD-backed memory regions through a trusted _EPROCESS address when the backend can read both kernel virtual memory and the target user-mode address space.
  • Build simple memory-backed entity/object wrappers.
  • Scan byte/string patterns.
  • Enumerate memory regions and protections.

Concept Model

  • IProcess is the top-level target process abstraction.
  • IProcessMemory exposes process memory facade.
  • IMemoryAccessor describes the memory context and range; IMemoryReader and IMemoryWriter supply reading and writing.
  • IMemoryBackend performs low-level operations.
  • RemoteMemoryObject is a small helper base for objects that represent a known address inside an IMemory view.
  • EyeAuras.Memory.Shared contains contracts.
  • EyeAuras.Memory.Metadata contains compile-time SDK-facing memory facades such as LocalProcess and public local-process contracts.
  • EyeAuras.Memory contains the local process implementation and registers the runtime provider for the EyeAuras.Memory.Metadata facade when loaded.
  • EyeAuras.Memory.KD contains kernel-driver-backed access.
  • EyeAuras.Memory.MPFS contains MemProcFS / LeechCore / VMM access.
  • Backends do not expose identical control capabilities.

API Details

  • IProcess - IsValid, ProcessName, ProcessId, Memory, GetProcessModules(), GetThreads(), VirtualQuery(...), GetMemoryRegions().
  • IProcessMemory - process memory facade.
  • IMemoryReader / IMemoryWriter - typed reads/writes and pointer-chain operations.
  • IMemory - memory view, often module-scoped through MemoryOfModule(...).
  • RemoteMemoryObject - base class for address-backed memory object wrappers.
  • IMemoryBackend - backend implementation contract.
  • IProcessControlApi - allocation, protection, CreateThread, synchronous ExecuteCode, suspend/resume, APC where supported.
  • IProcessSupportsManualMapping - opt-in marker for backends that can stage and synchronously execute manual-mapping code through IProcess plus IProcessControlApi.
  • LocalProcess - normal local user-mode reader. In embedded/package usage the public facade is available from metadata assemblies, but the implementation requires the EyeAuras.Memory module/package to be present and loaded. For embedded apps this means declaring UseMemory() and awaiting EnsureReadyAsync(...) before calling the static facade.
  • ILocalProcessBuilder - public builder contract registered by the loaded Memory module. LocalProcess forwards to this builder and fails clearly when the module was not loaded.
  • NativeLocalProcess - native local backend with permission tuning.
  • KDProcess - kernel-driver-backed reader.
  • LCProcess, ILCProcessBuilder - MPFS/LeechCore/VMM readers.
  • MemoryExtensionsForPatterns, BytePattern, StringPattern - signature scanning.
  • MemoryExtensionsForCodeCaves, CodeCaveEntry - module-scoped code-cave enumeration; default scanning targets readable executable sections and treats 0x00, 0xCC, and 0x90 runs as valid cave padding.
  • MemoryExtensionsForImports, ProcessExtensions.ReadExports, ProcessPEExtensions - PE helpers.
  • MemoryExtensionsForEprocess - backend-neutral helpers for reading high-level process, module, thread, process-parameter, and VAD-backed memory region facts from _EPROCESS, PEB, loader-list, thread-list, and VAD records through any IMemoryReader that can read the relevant virtual memory.
  • MemoryExtensionsForTebPeb - backend-neutral helpers for reading a PEB address from a TEB, loaded modules from PEB loader lists, and process startup parameters from RTL_USER_PROCESS_PARAMETERS through any IMemoryReader that can read the target user-mode address space. Local live-OS thread-to-TEB queries belong to the internal Win32NativeShared, not this public memory-reader surface.
  • ReadProcessInformation - reads PID and image-name information from an _EPROCESS address without exposing raw kernel structures.
  • ReadPebAddressViaEprocess - reads the PEB pointer referenced by _EPROCESS; for WOW64 processes it returns the WOW64 PEB when available.
  • ReadProcessModulesViaEprocess - reads loaded modules through the PEB referenced by _EPROCESS and returns ProcessModuleInformation.
  • ReadProcessParametersViaEprocess - reads startup metadata such as image path, command line, current directory, desktop/window metadata, and environment pointer through _EPROCESS -> PEB.
  • ReadProcessThreadsViaEprocess - walks _EPROCESS.ThreadListHead and returns high-level ProcessThreadInformation records.
  • ReadMemoryRegionsViaEprocess - walks _EPROCESS.VadRoot and returns allocated VAD-backed MemoryBasicInformation ranges sorted by base address.
  • ReadMemoryRegionViaEprocess - resolves a single address against the VAD-backed region snapshot.
  • Internal Win32NativeShared.ReadTebAddressViaThreadHandle - queries the live local OS for ThreadBasicInformation.TebBaseAddress from an already-open thread handle.
  • Internal Win32NativeShared.ReadTebAddressViaThreadId - opens a live local Windows thread by id, queries its TEB address, and closes the temporary handle.
  • ReadPebAddressViaTeb - reads TEB.ProcessEnvironmentBlock from a caller-supplied TEB address and explicit target architecture.
  • ReadProcessModulesViaPeb - reads loaded modules through a caller-supplied PEB address and explicit target architecture.
  • ReadProcessModulesViaTeb - composes TEB-to-PEB reading with PEB loader-list walking.
  • ReadProcessParametersViaPeb - reads command-line, image-path, current-directory, desktop/window metadata, and the environment pointer through a caller-supplied PEB address.
  • ReadProcessParametersViaTeb - composes TEB-to-PEB reading with RTL_USER_PROCESS_PARAMETERS reading.
  • ReadArchitectureViaEprocess - reads process architecture from kernel structure fields; this is the best path when the backend can read _EPROCESS.WoW64Process.
  • ReadArchitectureViaTeb - reads process architecture from a TEB self pointer; this is the preferred user-mode path when a TEB address is known.
  • ReadArchitectureViaPeb - reads architecture from PEB.ImageBaseAddress and the in-memory PE machine type; use when only a PEB address is known.

Common Flows

  • Attach from selected window:

    • pick or receive IWindowHandle.
    • read expected PID from ProcessId.
    • create reader by PID.
    • validate IsValid and ProcessId.
  • Read pointer chain:

    • get IMemoryAccessor.
    • call ReadPointerChain or ReadPointerChain32.
    • receive the final value of type T; these methods do not return the final field address.
  • Scan signature:

    • create BytePattern or StringPattern.
    • use pattern extension helpers.
    • scope to module/region when possible.
  • Find a code cave:

    • create module-scoped memory with MemoryOfModule(...).
    • call EnumerateCodeCaves(minBytes, alignment) for executable caves.
    • pass sectionFilter and acceptedFillBytes when the cave is for data placement or when only a specific padding byte is acceptable.
    • for scalar state near injected code, use Read<T> and Write<T>; use byte-span writes only for machine-code payloads or encoded strings.
  • Read entity list:

    • create module-scoped IMemory.
    • read entity-list pointer and entity count from known offsets.
    • iterate entity pointers.
    • wrap each address as a small memory object or immutable snapshot.
    • display/log values and handle null or stale pointers.
  • Enumerate processes from kernel memory:

    • use a backend that can read kernel virtual addresses, such as KDProcess or a VMM/MPFS-backed reader. The memory source can be another machine, a dump, or a live VMM acquisition.
    • obtain a valid _EPROCESS address from the backend/driver/acquisition.
    • call ReadProcessesViaEprocess(eprocessAddress).
    • call ReadProcessInformation(eprocessAddress) for a single process snapshot.
    • call ReadPebAddressViaEprocess(eprocessAddress) when a later flow needs to start from the process PEB.
    • call ReadProcessModulesViaEprocess(eprocessAddress) for module data when the backend can also read the target process user-mode address space.
    • call ReadProcessParametersViaEprocess(eprocessAddress) for image path, command line, current directory, and related startup metadata.
    • call ReadProcessThreadsViaEprocess(eprocessAddress) for thread metadata from the kernel thread list.
    • call ReadMemoryRegionsViaEprocess(eprocessAddress) or ReadMemoryRegionViaEprocess(eprocessAddress, address) for allocated VAD-backed ranges. These helpers intentionally do not synthesize free address-space holes or split regions by per-page state.
    • call ReadArchitectureViaEprocess(eprocessAddress) when architecture should be inferred from _EPROCESS.WoW64Process.
    • pass the source OS build when it differs from the current host; the current implementation is still layout-sensitive until the PDB offset resolver replaces hardcoded _EPROCESS, PEB, and loader-list offsets.
  • Enumerate modules from user-mode memory without OS snapshot APIs:

    • use a backend that can read the target process address space.
    • obtain a valid TEB or PEB address from the backend, thread metadata, or another trusted discovery path.
    • for live local window/hook flows, resolve the owner thread id and call ReadTebAddressViaThreadId; use ReadTebAddressViaThreadHandle when a suitable thread handle is already open.
    • call ReadPebAddressViaTeb(tebAddress, architecture) when starting from a TEB.
    • call ReadArchitectureViaTeb(tebAddress) first when the architecture is unknown and a TEB address is trusted.
    • call ReadArchitectureViaPeb(pebAddress) when the architecture is unknown and only a PEB address is trusted.
    • call ReadProcessModulesViaPeb(pebAddress, architecture) or ReadProcessModulesViaTeb(tebAddress, architecture) for module data.
    • call ReadProcessParametersViaPeb(pebAddress, architecture) or ReadProcessParametersViaTeb(tebAddress, architecture) for startup metadata such as image path, command line, and current directory.
    • pass the target layout architecture explicitly; this is especially important for WOW64 and acquired-memory scenarios.
  • Manual-map a DLL into a compatible target:

    • require an IProcess that also implements IProcessSupportsManualMapping.
    • compatible local backends include LocalProcess and NativeLocalProcess.
    • optional package backends may opt in; WHProcess supports x64 GUI targets when its WH control prerequisites are available.
    • use InjectDllViaManualMapping(...); the mapper relies on IProcessControlApi.ExecuteCode(...) for synchronous completion before it reads mapper return buffers or frees shellcode.
    • do not treat CreateThread(...) as a waitable completion primitive; it is the async/fire-and-forget thread start surface.

Prefer

  • Prefer IProcess as target contract.
  • Prefer LocalProcess for ordinary local access.
  • Prefer NativeLocalProcess for native handle/permission tuning.
  • Prefer KDProcess only when driver access is expected.
  • Prefer LCProcess / ILCProcessBuilder for acquisition/VMM scenarios.
  • Prefer validating PID before write-capable tooling.
  • Prefer explicit versioned layout structs for kernel/private structures: declare logical fields as [field: FieldOffset(...)] auto-properties, dispatch through a small typed interface, and use typed static offsets for list/link pointer arithmetic.
  • Prefer explicit target architecture when using TEB/PEB helpers. The memory source may not match the current process architecture.
  • Prefer ReadTebAddressViaThreadId or ReadTebAddressViaThreadHandle for live local Windows user-mode flows where a thread id/handle is already known, then validate the result with ReadArchitectureViaTeb.
  • Prefer IMemoryAccessor.Read<T> and IMemoryAccessor.Write<T> for unmanaged scalar/struct values in process memory. Use byte arrays/spans for actual byte payloads such as machine code, strings, file/protocol layouts, or bulk buffers.
  • Prefer MemoryOfModule(...).EnumerateCodeCaves(...) before writing local ad hoc code-cave scanners.

Avoid

  • Avoid starting with KD/MPFS without environment need.
  • Avoid assuming every backend supports allocation, APC, remote thread, synchronous execution, manual mapping, or module enumeration.
  • Avoid building manual mapping directly on CreateThread(...); use IProcessControlApi.ExecuteCode(...) or a backend that exposes IProcessSupportsManualMapping.
  • Avoid using ReadProcessesViaEprocess on ordinary user-mode process memory; it expects kernel virtual addresses and matching Windows kernel layouts.
  • Avoid treating VAD-backed region enumeration as a byte-for-byte VirtualQueryEx replacement. It reports allocated VAD ranges and does not enumerate free holes.
  • Avoid depending on raw _EPROCESS, PEB, or loader-list snapshots from the public API. The shared helpers intentionally return ProcessInformation, ProcessModuleInformation, ProcessParametersInformation, ProcessThreadInformation, MemoryBasicInformation, and Architecture; low-level readers can define their own structs when they need raw layout work.
  • Avoid inferring TEB or PEB layout from host bitness. Pass the layout architecture that matches the supplied TEB/PEB address.
  • Avoid using thread-to-TEB OS query helpers for dumps, VMM/KD snapshots, or cross-machine memory sources. Those need backend-supplied thread metadata or kernel thread-list walking.
  • Avoid string/reflection-based offset lookup for layouts that may ship through obfuscation. Do not rely on Marshal.OffsetOf<T>(nameof(...)), auto-property backing-field names, or member-name strings for pointer math in obfuscated assemblies; keep needed offsets as typed static members near matching [field: FieldOffset(...)] declarations.
  • Avoid writing a new scanner before checking pattern extensions.
  • Avoid BinaryPrimitives, MemoryMarshal, or manual byte packing as a thin wrapper around ordinary scalar process-memory reads/writes. Reserve those APIs for explicit byte-format work.

Research Anchors

  • IProcess, IProcessMemory, IMemoryAccessor, IMemoryBackend, IProcessControlApi, IProcessControlApi.ExecuteCode, IProcessSupportsManualMapping, LocalProcess, NativeLocalProcess, KDProcess, LCProcess, ILCProcessBuilder, ReadPointerChain, VirtualQuery, BytePattern, StringPattern, MemoryExtensionsForPatterns, ProcessPEExtensions, MemoryExtensionsForEprocess, MemoryExtensionsForTebPeb, ReadPebAddressViaTeb, ReadProcessModulesViaPeb, ReadProcessModulesViaTeb, ReadProcessParametersViaPeb, ReadProcessParametersViaTeb, ReadTebAddressViaThreadHandle, ReadTebAddressViaThreadId, ReadProcessesViaEprocess, ReadProcessInformation, ReadPebAddressViaEprocess, ReadProcessModulesViaEprocess, ReadProcessParametersViaEprocess, ReadProcessThreadsViaEprocess, ReadMemoryRegionsViaEprocess, ReadMemoryRegionViaEprocess, ReadArchitectureViaEprocess, ReadArchitectureViaTeb, ReadArchitectureViaPeb, MemoryExtensionsForCodeCaves, EnumerateCodeCaves, CodeCaveEntry, ModuleSectionEntry, MemoryOfModule, RemoteMemoryObject, ReadString.

Search Synonyms

  • memory
  • process memory
  • process reader
  • local process
  • native process
  • kernel driver
  • KD process
  • EPROCESS
  • ActiveProcessLinks
  • WoW64Process
  • ReadArchitectureViaEprocess
  • ReadArchitectureViaTeb
  • ReadArchitectureViaPeb
  • ReadTebAddressViaThreadHandle
  • ReadTebAddressViaThreadId
  • TebBaseAddress
  • ThreadBasicInformation
  • ReadProcessInformation
  • ReadProcessesViaEprocess
  • ReadPebAddressViaEprocess
  • ReadProcessModulesViaEprocess
  • ReadProcessParametersViaEprocess
  • ReadProcessThreadsViaEprocess
  • ReadMemoryRegionsViaEprocess
  • ReadMemoryRegionViaEprocess
  • ReadPebAddressViaTeb
  • ReadProcessModulesViaPeb
  • ReadProcessModulesViaTeb
  • ReadProcessParametersViaPeb
  • ReadProcessParametersViaTeb
  • TEB
  • PEB
  • ProcessEnvironmentBlock
  • RTL_USER_PROCESS_PARAMETERS
  • process parameters
  • command line
  • PEB_LDR_DATA
  • LDR_DATA_TABLE_ENTRY
  • process list
  • kernel process list
  • thread list
  • ThreadListHead
  • ETHREAD
  • CLIENT_ID
  • VAD
  • VadRoot
  • MMVAD
  • MMVAD_SHORT
  • MemProcFS
  • LeechCore
  • pointer chain
  • signature scan
  • memory region
  • module
  • PE
  • code cave
  • entity list
  • memory object
  • remote memory object
  • manual mapping
  • ExecuteCode
  • IProcessSupportsManualMapping
  • radar
  • player list

Kernel and snapshot boundaries

At EyeAuras c8b2304, EPROCESS helpers select a curated x64 Windows layout using osBuild; omission uses the controller OS build. For a dump or another machine, pass the build of the memory source. The reader must resolve kernel virtual addresses and, for modules/parameters, the target process user address space. These helpers do not install a driver or switch address spaces for the caller.

TEB/PEB readers support explicit x86/x64 layouts; choose the layout of the supplied address, including the chosen WOW64 view. EPROCESS architecture detection uses WoW64Process, whereas TEB detection checks its self pointer. None of these walks freezes the target: the returned lists are collected reads, not atomic snapshots. Traversal limits stop runaway walks rather than returning a complete list beyond the limit.

VAD enumeration returns sorted allocated ranges, without free holes or per-page state. Its MemoryBasicInformation.State is set to Commit; it is not a live VirtualQueryEx result proving every page is committed/resident. Backend-specific control operations and native compatibility remain separate from these shared readers. See the backend maps before selecting a provider.