aeondave/unicorn

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.