unicorn

name	unicorn
description	Auth/lab ref: Unicorn Engine CPU-only emulation for shellcode, decryptors, custom VM handlers, instruction tracing, memory hooks, and register-level experiments.
license	MIT
compatibility	Unicorn Engine bindings; no OS, loader, filesystem, syscall, or peripheral model.
metadata	{"version":"1.0","category":"tool"}

Unicorn

Unicorn is a CPU emulator. It is the right tool when you can define memory, registers, and stop conditions yourself.

Use Unicorn when

• the target is shellcode, a decoder, checksum loop, custom VM handler, crypto primitive, or small boot stub
• OS behavior would be noise
• you know or can infer load address, entry address, mapped memory, stack, registers, and inputs
• memory/register hooks are the evidence you need

Do not use Unicorn as a shortcut for real userland execution. If the target needs syscalls, files, dynamic linking, registry, interrupts, or hardware peripherals, use Qiling, QEMU, or Renode instead.

Setup checklist

• architecture, mode, endian, ARM/Thumb state
• code mapping address and permissions
• stack address and size
• input buffers and output buffers
• initial registers and calling convention
• imported function stubs or syscall stop points
• maximum instruction count or address stop

Hook strategy

Hook	Use
basic block	coverage, control-flow sketch, custom VM dispatch
instruction	exact trace, self-modifying code, privileged instruction stop
memory read/write	watchpoints, decrypted output, MMIO discovery
unmapped memory	identify missing mapping, import thunk, stack growth, bad pointer
interrupt/syscall	stop or fake external behavior

Keep hooks narrow. Broad instruction hooks over large regions can make emulation painfully slow.

Good targets

• XOR/RC4/AES wrapper that fills a plaintext buffer
• password checker inner loop
• architecture-specific shellcode decoder
• VM bytecode dispatcher over a byte array
• bare-metal reset stub before first peripheral wait
• opaque predicate or anti-debug gadget

Bad targets

• dynamically linked application with many libc calls
• Windows or macOS binary that needs real APIs
• Linux service that opens files, forks, listens on sockets, or uses /proc
• MCU firmware stuck in timer/UART/GPIO MMIO loops unless those reads/writes are stubbed deliberately
• kernel boot, drivers, or interrupt-heavy RTOS behavior

Evidence

• initial register/memory state
• hook outputs and stop reason
• memory dump of transformed buffers
• branch or address coverage proving the target path
• exact stubs used for external calls

State clearly that the proof is CPU-level unless OS or board behavior was validated elsewhere.