Skip to content

meltedinhex/analyst-ai-pack / skills/emulating-shellcode-with-unicorn

emulating-shellcode-with-unicorn

Verified

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.

FileKindSize
LICENSEother340 B
SKILL.mdskill md3.0 KB
references/api-reference.mdmarkdown1.4 KB
scripts/analyst.pyscript3.3 KB

references/api-reference.md

View on GitHub
# API Reference: Emulating Shellcode With Unicorn

## Overview

`scripts/analyst.py` emulates raw x86/x64 shellcode with the Unicorn engine: it maps the code and a
stack, hooks instruction and memory-write events, runs to an instruction budget, and reports
executed instruction count and self-modified regions (decoded stages). Unicorn is optional; without
it, `prep` still reports availability. Intended for isolated VMs.

## Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| unicorn | latest | CPU emulation (optional; emulate requires it) |
| (stdlib) | — | JSON, file IO |

## Core functions

### `prep(path, arch)`
Reports size, architecture, and whether Unicorn is installed.

### `emulate(path, arch, max_insns)`
Maps and runs the shellcode under Unicorn; returns instruction count, self-modified addresses, and
the stop reason.

## Memory layout

- Code base `0x100000` (2 MiB region), stack at `0x300000` (64 KiB). Adjust for larger payloads.

## Usage

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

## Sources

- Unicorn CPU emulator framework — https://www.unicorn-engine.org/
- MITRE ATT&CK T1620 Reflective Code Loading — https://attack.mitre.org/techniques/T1620/
- Shellcode emulation methodology (mapping, stack setup, hooks) from public emulation tooling
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall