Unicorn

The Unicorn API exposes a lightweight CPU + memory emulation layer to AngelScript. It supports two modes:

Local emulation (uc_create) — fully sandboxed memory you map/write yourself.
Process-backed emulation (uc_create_process) — unmapped reads/fetches can be paged-in from a proc_t target, enabling “emulate code that reads target memory”.

Notes (Important)

Always call uc_close(handle) when done.
You should use uc_setup_stack for setting up stack.
If you modify code bytes at the same address and re-run, call uc_flush_code(handle) (TB cache flush) or run the updated code at a different address.
Memory addresses are Unicorn virtual addresses:
- Low “sandbox” memory (e.g. 0x1000 / 0x2000) is local/emulator-owned.
- Real target VAs (user-mode addresses) are process-backed when running in process mode.

Constants

Memory Protection Flags

Copy

const uint32 UC_PROT_READ
const uint32 UC_PROT_WRITE
const uint32 UC_PROT_EXEC
const uint32 UC_PROT_ALL

Use these with uc_mem_map.

Register IDs (x86_64)

Copy

// General purpose registers
const int UC_X86_REG_RAX;
const int UC_X86_REG_RBX;
const int UC_X86_REG_RCX;
const int UC_X86_REG_RDX;
const int UC_X86_REG_RSI;
const int UC_X86_REG_RDI;
const int UC_X86_REG_RBP;
const int UC_X86_REG_RSP;

const int UC_X86_REG_R8;
const int UC_X86_REG_R9;
const int UC_X86_REG_R10;
const int UC_X86_REG_R11;
const int UC_X86_REG_R12;
const int UC_X86_REG_R13;
const int UC_X86_REG_R14;
const int UC_X86_REG_R15;

// Instruction pointer & flags
const int UC_X86_REG_RIP;
const int UC_X86_REG_EFLAGS;

// Segment registers
const int UC_X86_REG_CS;
const int UC_X86_REG_DS;
const int UC_X86_REG_ES;
const int UC_X86_REG_FS;
const int UC_X86_REG_GS;
const int UC_X86_REG_SS;

// Segment bases
const int UC_X86_REG_FS_BASE;
const int UC_X86_REG_GS_BASE;

// SIMD control
const int UC_X86_REG_MXCSR;

// XMM registers
const int UC_X86_REG_XMM0;
const int UC_X86_REG_XMM1;
const int UC_X86_REG_XMM2;
const int UC_X86_REG_XMM3;
const int UC_X86_REG_XMM4;
const int UC_X86_REG_XMM5;
const int UC_X86_REG_XMM6;
const int UC_X86_REG_XMM7;
const int UC_X86_REG_XMM8;
const int UC_X86_REG_XMM9;
const int UC_X86_REG_XMM10;
const int UC_X86_REG_XMM11;
const int UC_X86_REG_XMM12;
const int UC_X86_REG_XMM13;
const int UC_X86_REG_XMM14;
const int UC_X86_REG_XMM15;

// YMM registers
const int UC_X86_REG_YMM0;
const int UC_X86_REG_YMM1;
const int UC_X86_REG_YMM2;
const int UC_X86_REG_YMM3;
const int UC_X86_REG_YMM4;
const int UC_X86_REG_YMM5;
const int UC_X86_REG_YMM6;
const int UC_X86_REG_YMM7;
const int UC_X86_REG_YMM8;
const int UC_X86_REG_YMM9;
const int UC_X86_REG_YMM10;
const int UC_X86_REG_YMM11;
const int UC_X86_REG_YMM12;
const int UC_X86_REG_YMM13;
const int UC_X86_REG_YMM14;
const int UC_X86_REG_YMM15;

Hook Types

const int UC_HOOK_CODE
const int UC_HOOK_MEM_UNMAPPED

UC_HOOK_CODE — Hook every instruction executed.
UC_HOOK_MEM_UNMAPPED — Hook unmapped memory access (read/write/fetch).

Engine Handles

Create (Local)

Copy

uint64 uc_create()

Creates a new Unicorn context (local emulation). Returns a handle, or 0 on failure.

Create (Process-backed)

Copy

uint64 uc_create_process(proc_t proc, bool allow_writes = true)

Creates a Unicorn context that can page-in unmapped reads/fetches from proc. Use allow_writes=false for safe read-only emulation.

A synthetic TEB is created with the real PEB address written at offset 0x60. For correct and stable emulation, you should override the FS and GS base registers to point to a real TEB instance.

Returns a handle, or 0 on failure.

Close

Copy

void uc_close(uint64 handle)

Destroys the Unicorn context and releases all internal resources.

Memory

Map Memory

Copy

bool uc_mem_map(uint64 handle, uint64 addr, uint64 size, uint32 perms)

Maps a memory region in the emulator.

addr must be page-aligned.
size must be page-aligned (or a multiple of page size).

Returns true on success.

Write Memory

Copy

bool uc_mem_write(uint64 handle, uint64 addr, const array<uint8> &in data)

Writes bytes into emulator memory at addr.

Read Memory

Copy

bool uc_mem_read(uint64 handle, uint64 addr, uint32 size, array<uint8> &out data)

Reads bytes from emulator memory at addr into data.

In process-backed mode, this may succeed if the page was already paged-in (or if your integration supports paging-in for external reads).

Registers

Write 64-bit Register

Copy

bool uc_reg_write64(uint64 handle, int reg, uint64 value)

Read 64-bit Register

Copy

uint64 uc_reg_read64(uint64 handle, int reg)

Write 128-bit Register (XMM)

Copy

bool uc_reg_write128(uint64 handle, int reg, const array<uint8> &in data)

data must be exactly 16 bytes.

Read 128-bit Register (XMM)

Copy

bool uc_reg_read128(uint64 handle, int reg, array<uint8> &out data)

Returns exactly 16 bytes in data.

Write 256-bit Register (YMM)

Copy

bool uc_reg_write256(uint64 handle, int reg, const array<uint8> &in data)

data must be exactly 32 bytes.

Read 256-bit Register (YMM)

Copy

bool uc_reg_read256(uint64 handle, int reg, array<uint8> &out data)

Returns exactly 32 bytes in data.

Execution

Setup Stack (Recommended)

Copy

bool uc_setup_stack(uint64 handle, uint64 stack_base, uint64 stack_size, uint64 stop_addr)

Maps a stack region, sets RSP, pushes a return address, and maps a STOP page.

Use this before running any code that can execute ret.

Returns true on success.

If uc_setup_stack is not used in process mode, the emulator may attempt to read stack memory from the remote process instead of the emulated address space.

Start Emulation

Copy

int uc_start(uint64 handle, uint64 begin, uint64 end, uint64 timeout = 0, uint64 count = 0)

Starts emulation at begin.

end — stop address (use a STOP page if your code returns)
timeout — microseconds (0 = unlimited)
count — instruction limit (0 = unlimited)

Returns UC_ERR_OK on success. Error Codes

Flush Translated Code Cache

Copy

bool uc_flush_code(uint64 handle)

Flushes Unicorn’s internal translation cache (TB cache). Call this after modifying code bytes at an address you will execute again.

Returns true on success.

Callback Signature

funcdef bool UcHookFn(uint64 uc, uint64 addr)

Hook callbacks receive:

uc — Unicorn handle (same value as the handle you created)
addr — address of the instruction or faulting memory access

Return value:

true — continue emulation
false — stop emulation (recommended to also call uc_emu_stop)

Add Hook

bool uc_hook_add(uint64 handle, int type, UcHookFn@ cb)

Registers a hook callback on the Unicorn context.

handle — Unicorn context handle
type — hook type constant (UC_HOOK_CODE, UC_HOOK_MEM_UNMAPPED)
cb — callback function handle

Returns true on success, false on failure.

Stop Emulation (from hook)

void uc_emu_stop(uint64 handle)

Stops emulation immediately. Intended for use inside hook callbacks to halt execution cleanly.

Notes (Hooks)

Hooks run during uc_start(...) execution.
Keep hook callbacks lightweight (they can fire very frequently, especially UC_HOOK_CODE).
If you stop execution from a hook, prefer:
- uc_emu_stop(handle) and return false from the hook.

Examples

Example 1 — Read Notepad ImageBaseAddress via PEB (GS:[0x60])

This example:

References notepad.exe
Creates a process-backed Unicorn context
Reads PEB->ImageBaseAddress via:
- mov rax, gs:[0x60] (PEB)
- mov rax, [rax+0x10] (ImageBaseAddress)
- ret (lands on STOP)

Copy

int main()
{
    proc_t p = ref_process("notepad.exe");
    if (!p.alive()) { log_error("notepad not found"); return -1; }

    uint64 uc = uc_create_process(p, false);
    if (uc == 0) { log_error("uc_create_process failed"); p.deref(); return -1; }

    array<uint8> code = {
        0x65,0x48,0x8B,0x04,0x25,0x60,0x00,0x00,0x00, // mov rax, gs:[0x60]
        0x48,0x8B,0x40,0x10,                         // mov rax, [rax+0x10]
        0xC3                                          // ret
    };

    uint64 CODE  = 0x1000;
    uint64 STACK = 0x2000;
    uint64 STOP  = 0x4000;

    uc_mem_map(uc, CODE, 0x1000, UC_PROT_ALL);
    uc_mem_write(uc, CODE, code);

    uc_reg_write64(uc, UC_X86_REG_RIP, CODE);

    if (!uc_setup_stack(uc, STACK, 0x2000, STOP)) {
        log_error("uc_setup_stack failed");
        uc_close(uc); p.deref();
        return -1;
    }

    if (!uc_start(uc, CODE, STOP, 0, 0)) {
        log_error("uc_start failed");
        uc_close(uc); p.deref();
        return -1;
    }

    uint64 imageBase = uc_reg_read64(uc, UC_X86_REG_RAX);
    log("PEB->ImageBaseAddress: 0x" + formatInt(imageBase, "h"));

    uc_close(uc);
    p.deref();
    return 1;
}

Example 2 — Patch Code In-Place + Flush Cache

This example shows why uc_flush_code exists. We run two different code blobs at the same address:

Run 1: mov rax, gs:[0x60]; ret (returns PEB)
Patch code in place
Flush translation cache
Run 2: mov rax, [abs64]; ret (returns ImageBase)

Copy

int main()
{
    proc_t p = ref_process("notepad.exe");
    if (!p.alive()) { log_error("notepad not found"); return -1; }

    uint64 uc = uc_create_process(p, false);
    if (uc == 0) { log_error("uc_create_process failed"); p.deref(); return -1; }

    uint64 CODE  = 0x1000;
    uint64 STACK = 0x2000;
    uint64 STOP  = 0x4000;

    uc_mem_map(uc, CODE, 0x1000, UC_PROT_ALL);

    // Run 1: get PEB in RAX
    array<uint8> get_peb = {
        0x65,0x48,0x8B,0x04,0x25,0x60,0x00,0x00,0x00, // mov rax, gs:[0x60]
        0xC3
    };

    uc_mem_write(uc, CODE, get_peb);
    uc_flush_code(uc);

    uc_reg_write64(uc, UC_X86_REG_RIP, CODE);
    uc_setup_stack(uc, STACK, 0x2000, STOP);

    if (!uc_start(uc, CODE, STOP, 0, 0)) {
        log_error("uc_start(get_peb) failed");
        uc_close(uc); p.deref();
        return -1;
    }

    uint64 peb = uc_reg_read64(uc, UC_X86_REG_RAX);
    log("PEB ptr = 0x" + formatInt(peb, "h"));

    // Read expected ImageBase from process-backed memory (optional)
    array<uint8> q;
    uc_mem_read(uc, peb + 0x10, 8, q);

    uint64 expected = 0;
    for (int i = 0; i < 8; i++)
        expected |= (uint64(q[i]) << (i * 8));

    // Run 2: mov rax, [abs (peb+0x10)]
    array<uint8> read_abs = {
        0x48,0xA1,
        0,0,0,0,0,0,0,0,
        0xC3
    };

    uint64 addr = peb + 0x10;
    for (int i = 0; i < 8; i++)
        read_abs[2 + i] = uint8((addr >> (i * 8)) & 0xFF);

    uc_mem_write(uc, CODE, read_abs);
    uc_flush_code(uc);

    uc_reg_write64(uc, UC_X86_REG_RIP, CODE);
    uc_setup_stack(uc, STACK, 0x2000, STOP);

    if (!uc_start(uc, CODE, STOP, 0, 0)) {
        log_error("uc_start(read_abs) failed");
        uc_close(uc); p.deref();
        return -1;
    }

    uint64 imageBase = uc_reg_read64(uc, UC_X86_REG_RAX);
    log("ImageBase = 0x" + formatInt(imageBase, "h"));
    log("Expected  = 0x" + formatInt(expected, "h"));

    uc_close(uc);
    p.deref();
    return 1;
}

Example 3 — Local Sandbox Emulation (No Process)

This runs a tiny code snippet in a fully local emulator memory map.

Copy

int main()
{
    uint64 uc = uc_create();
    if (uc == 0) { log_error("uc_create failed"); return -1; }

    uint64 CODE  = 0x1000;
    uint64 STACK = 0x2000;
    uint64 STOP  = 0x4000;

    // mov rax, 0x12345678; ret
    array<uint8> code = {
        0x48,0xC7,0xC0,0x78,0x56,0x34,0x12,
        0xC3
    };

    uc_mem_map(uc, CODE, 0x1000, UC_PROT_ALL);
    uc_mem_write(uc, CODE, code);
    uc_reg_write64(uc, UC_X86_REG_RIP, CODE);

    if (!uc_setup_stack(uc, STACK, 0x2000, STOP)) {
        log_error("uc_setup_stack failed");
        uc_close(uc);
        return -1;
    }

    if (!uc_start(uc, CODE, STOP, 0, 0)) {
        log_error("uc_start failed");
        uc_close(uc);
        return -1;
    }

    uint64 rax = uc_reg_read64(uc, UC_X86_REG_RAX);
    log("RAX = 0x" + formatInt(rax, "h"));

    uc_close(uc);
    return 1;
}

PreviousEngine NextRender API

Last updated 3 days ago

hashtagNotes (Important)

hashtagConstants

hashtagMemory Protection Flags

hashtagRegister IDs (x86_64)

hashtagHook Types

hashtagEngine Handles

hashtagCreate (Local)

hashtagCreate (Process-backed)

hashtagClose

hashtagMemory

hashtagMap Memory

hashtagWrite Memory

hashtagRead Memory

hashtagRegisters

hashtagWrite 64-bit Register

hashtagRead 64-bit Register

hashtagWrite 128-bit Register (XMM)

hashtagRead 128-bit Register (XMM)

hashtagWrite 256-bit Register (YMM)

hashtagRead 256-bit Register (YMM)

hashtagExecution

hashtagSetup Stack (Recommended)

hashtagStart Emulation

hashtagFlush Translated Code Cache

hashtagCallback Signature

hashtagAdd Hook

hashtagStop Emulation (from hook)

hashtagNotes (Hooks)

hashtagExamples

hashtagExample 1 — Read Notepad ImageBaseAddress via PEB (GS:[0x60])

hashtagExample 2 — Patch Code In-Place + Flush Cache

hashtagExample 3 — Local Sandbox Emulation (No Process)

Notes (Important)

Constants

Memory Protection Flags

Register IDs (x86_64)

Hook Types

Engine Handles

Create (Local)

Create (Process-backed)

Close

Memory

Map Memory

Write Memory

Read Memory

Registers

Write 64-bit Register

Read 64-bit Register

Write 128-bit Register (XMM)

Read 128-bit Register (XMM)

Write 256-bit Register (YMM)

Read 256-bit Register (YMM)

Execution

Setup Stack (Recommended)

Start Emulation

Flush Translated Code Cache

Callback Signature

Add Hook

Stop Emulation (from hook)

Notes (Hooks)

Examples

Example 1 — Read Notepad ImageBaseAddress via PEB (GS:[0x60])

Example 2 — Patch Code In-Place + Flush Cache

Example 3 — Local Sandbox Emulation (No Process)