# Unicorn

> Auth/lab ref: Unicorn Engine CPU-only emulation for shellcode, decryptors, custom VM handlers, instruction tracing, memory hooks, and register-level experiments.

- Skill: `aeondave/unicorn` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aeondave/unicorn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aeondave/unicorn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: AeonDave (https://skillmd.com/u/aeondave)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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.