reverse-skills-max/vendor-new/analyst-ai-pack/skills/emulating-shellcode-with-unicorn/SKILL.md

name, description, domain, subdomain, tags, version, author, license, mitre_attack, d3fend, references

name	description	domain	subdomain	tags	version	author	license	mitre_attack	d3fend	references
emulating-shellcode-with-unicorn	Emulates position-independent shellcode in a controlled CPU emulator (Unicorn) to trace executed instructions, memory writes, and decoded second stages without running it on a real host. Activates for requests to emulate shellcode, trace a decoder stub, or recover a stage unpacked at runtime by shellcode.	cybersecurity	reverse-engineering	reverse-engineering shellcode emulation unicorn dynamic-analysis	1.0.0	analyst-ai-pack	Apache-2.0	T1027 T1620 T1055	D3-DA D3-SDA	Unicorn CPU emulator framework — https://www.unicorn-engine.org/ MITRE ATT&CK T1620 Reflective Code Loading — https://attack.mitre.org/techniques/T1620/

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).