agentsclimarketplace
Sign in

Emulating shellcode with unicorn

Skill meltedinhex/analyst-ai-pack/skills/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.From its SKILL.md

Install
npx -y skills add meltedinhex/analyst-ai-pack --skill emulating-shellcode-with-unicorn

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 21 stars21 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.0 KB, 479 tokens by cl100k_base, as published. Nobody here has run it

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

What ships with it: 3 files

5.0 KB alongside SKILL.md, 1 of them executable

references/

scripts/

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.