Emulating Shellcode With Unicorn

When to Use

• You have a raw shellcode blob (decoder stub, egg hunter, staged loader) and want to observe its behavior via emulation rather than native execution.
• You want to recover a second stage that the shellcode decrypts/decompresses in memory.

Do not use native execution for this — emulation contains the code. Unsupported API calls must be stubbed; emulation is not a full Windows environment.

Prerequisites

• The shellcode blob and the unicorn Python package (degrades gracefully if absent — the script reports that emulation is unavailable and still does static prep).

Safety & Handling

• Even under emulation, treat the blob as malicious; run on an isolated VM and store stages password-protected.

Workflow

Step 1: Prepare and validate the blob

python scripts/analyst.py prep shellcode.bin --arch x64

Reports size, detected architecture hints, and whether Unicorn is available.

Step 2: Emulate with an instruction/memory trace

python scripts/analyst.py emulate shellcode.bin --arch x64 --max-insns 200000

Maps the code into emulator memory, sets up a minimal stack, hooks instruction and memory-write events, and stops on a self-modified region or instruction budget.

Step 3: Dump decoded stages

If the shellcode writes a new executable region, dump that buffer for follow-on analysis.

Step 4: Document

Record the entry behavior, decoded stage offset, and any observed (stubbed) API references.

Validation

• Emulation halts on the instruction budget or a clear decode-complete signal — never hangs.
• A decoded stage, if produced, has a recognizable header (MZ/known opcode prologue).
• Unsupported instructions/APIs are reported, not silently ignored.

Pitfalls

• Missing API/syscall environment causing early faults — stub the calls the stub needs.
• Wrong architecture/bitness producing immediate invalid-instruction faults.
• Emulating an anti-emulation stub that detects timing/missing APIs.

References

• See references/api-reference.md for the emulator harness.
• Unicorn engine and ATT&CK T1620 (linked in frontmatter).