whitemagic/README.md

WhiteMagic

WhiteMagic is a .NET 8 process-introspection library for Windows that provides managed wrappers over Win32 debugging APIs. It enables reading/writing memory, executing code remotely, hooking functions, and injecting DLLs into target processes.

Overview

WhiteMagic is designed for diagnostic tools, debuggers, profilers, and automation clients that need to attach to and manipulate desktop applications. It unifies the best features from four legacy libraries (BlackMagic, MemorySharp, GreyMagic, and BlackMagic-old) into a modern, bitness-agnostic .NET 8 library with a crash-safe execution model.

Key Features

• Dual memory access: External (ReadProcessMemory/WriteProcessMemory) and in-process readers over an abstract MemoryBase
• Three-tier execution model: Remote thread, crash-safe main-thread pump, and in-process delegates
• Function hooking: Reversible inline detours (DetourManager) and named byte patches (PatchManager) with auto-restore on dispose
• Pattern scanning: Memory pattern discovery with caching
• Assembly seam: IAssembler abstraction with hand-emitted stubs (default) and optional Iced backend
• DLL injection: CreateThread and thread-hijack strategies for x86 and x64
• High-level API: Ergonomic RemotePointer indexer, module/function access, PEB/TEB, window mutation, and input simulation

Quick Start

Installation

dotnet add package WhiteMagic

Basic Memory Read/Write

using WhiteMagic;
using var magic = Magic.Open(Process.GetProcessById(1234));

// Read an integer at an address
int health = magic.Memory.Read<int>(0x12345678);

// Write using the RemotePointer indexer
magic[0x12345678].Write(999);

// Read a string
string name = magic.Memory.ReadString(0x12345680, Encoding.UTF8);

Remote Function Execution

using WhiteMagic.Assembly;

// Resolve a function by module and export name
var msgBox = magic["user32"]["MessageBoxA"];

// Execute with calling convention and arguments
int result = msgBox.Execute<int>(
    CallConvention.Stdcall, 
    IntPtr.Zero,    // hWnd
    "Hello World",  // Text
    "Caption",      // Caption
    0               // Type
);

Crash-Safe Execution (Main-Thread Pump)

// Create a pump that hooks a per-frame function
var pump = magic.CreateMainThreadPump(frameAddress);

// Enqueue work that runs on the target's main thread
int result = await pump.ExecuteAsync(() =>
{
    // Safe to touch target's single-threaded state here
    return magic.Memory.Read<int>(stateAddress);
});

Function Hooking

// Apply an inline detour (in-process only)
var detour = magic.DetourManager.Create(
    "my_hook",
    targetFunctionAddress,
    myHookDelegate
);

detour.Apply();
// ... use the hook
detour.Remove(); // Automatically restored on dispose

Pattern Scanning

// Scan for a byte pattern in the target's memory
byte[] pattern = { 0x48, 0x8B, 0x05, 0x00, 0x00, 0x00, 0x00 };
string mask = "xxx????";
IntPtr found = PatternScanner.FindInModule(
    magic.Memory,
    pattern,
    mask,
    process.MainModule
);

Documentation

• API Reference: See inline XML documentation in your IDE; generate with DocFX
• Conceptual Guides: docs/ directory
• Examples: WhiteMagic.Examples with 5 comprehensive example files
• Architecture: openspec/changes/whitemagic-foundation/

Execution Models

WhiteMagic provides three execution strategies, each designed for specific payload safety requirements:

1. RemoteThreadExecutor (CreateRemoteThread)

Use for thread-agnostic payloads only:

• Pure WinAPI calls
• Self-contained computations
• DLL injection (LoadLibrary)

Avoid for single-threaded target state (scripting engines, render operations, object traversal).

2. MainThreadPump (Crash-Safe)

Use for state-sensitive calls that touch the target's main-thread-affinity data:

• Game state modifications
• UI interactions
• Script engine calls

3. InProcessInvoker (Direct Delegates)

Use when injected into the target process:

• Direct native-delegate calls via CreateFunction<T>
• Zero thread crossing overhead

Architecture

WhiteMagic is built in layers:

Magic (high-level facade)
├── Core: MemoryBase (abstract reader/writer)
│   ├── ExternalReader (RPM/WPM on target)
│   └── InProcessReader (in-process delegate access)
├── Discovery: PatternScanner, PeHeaderParser
├── Assembly: IAssembler → {StubAssembler | IcedAssembler}
├── Execution: RemoteThreadExecutor, MainThreadPump, InProcessInvoker
├── Hooking: DetourManager, PatchManager
└── High-level: RemotePointer, RemoteModule, RemoteWindow

Platform Support

• Target Framework: .NET 8.0-windows
• Architecture: x86 and x64 (host and target)
• Operating System: Windows 10+
• Dependencies: None (default); optional Iced NuGet package for arbitrary assembly

Safety

• All operations use SafeMemoryHandle for proper handle cleanup
• Detours and patches auto-restore on Dispose
• MainThreadPump prevents crashes from thread-affinity violations
• Prologue validation before detour splicing (optional Iced backend)

Comparison to Reference Libraries

Library	Platform	Execution	Hooking	Assembler
WhiteMagic	.NET 8, x86+x64	3-tier	✅	IAssembler (Iced opt.)
BlackMagic	.NET 8, x86+x64	Remote thread	❌	Hand stubs
MemorySharp	.NET FW, x86	Remote thread	❌	FASM (required)
GreyMagic	.NET FW, x86	In-process	✅	FASM

WhiteMagic is not a drop-in replacement for these libraries—it's a modern synthesis with a different API design and a crash-safe execution model.

License

[Specify your license here]

Contributing

Contributions are welcome! Please read our contributing guidelines (coming soon).

Acknowledgments

WhiteMagic builds upon concepts and techniques from:

• BlackMagic (current) — Modern .NET 8 base, x64, pattern scanning, DLL injection
• MemorySharp — High-level ergonomics, PEB/TEB, window/input simulation
• GreyMagic — Dual memory model, detours/patches, marshal cache, in-process delegates
• Iced — Modern x86/x64 assembler (optional backend)

See docs/memory-library-comparison.md for a detailed analysis.