SECURITY REVIEW
Not yet assessed
Review the original instructions and requested permissions before installing.
No security review is available for this catalog entry yet.
Community / AGENT SKILL
emulating-shellcode-with-unicorn
0
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.
Understand the trade-offs.
SKILL QUALITY
Not yet assessed
How clearly the skill guides your agent, how complete its workflow is, and how you can check the outcome.
No quality assessment is available for this catalog entry yet.
The full skill.
Original instructions from the publisher’s SKILL.md
# 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 ```bash 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 ```bash 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`](references/api-reference.md) for the emulator harness. - Unicorn engine and ATT&CK T1620 (linked in frontmatter).