emulating-shellcode-with-unicorn

Name: emulating-shellcode-with-unicorn
Author: meltedinhex

18stars5forks

How to install emulating-shellcode-with-unicorn?

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

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

Installs into the current project.

Summary

Emulates position-independent shellcode in a controlled CPU emulator (Unicorn) to

Files · 1

View on GitHub

SKILL.md

1	# Emulating Shellcode With Unicorn
2
3	## When to Use
4
5	- You have a raw shellcode blob (decoder stub, egg hunter, staged loader) and want to observe its
6	behavior via emulation rather than native execution.
7	- You want to recover a second stage that the shellcode decrypts/decompresses in memory.
8
9	Do not use native execution for this — emulation contains the code. Unsupported API calls must
10	be stubbed; emulation is not a full Windows environment.
11
12	## Prerequisites
13
14	- The shellcode blob and the `unicorn` Python package (degrades gracefully if absent — the script
15	reports that emulation is unavailable and still does static prep).
16
17	## Safety & Handling
18
19	- Even under emulation, treat the blob as malicious; run on an isolated VM and store stages
20	password-protected.
21
22	## Workflow
23
24	### Step 1: Prepare and validate the blob
25
26	```bash
27	python scripts/analyst.py prep shellcode.bin --arch x64
28	```
29
30	Reports size, detected architecture hints, and whether Unicorn is available.
31
32	### Step 2: Emulate with an instruction/memory trace
33
34	```bash
35	python scripts/analyst.py emulate shellcode.bin --arch x64 --max-insns 200000
36	```
37
38	Maps the code into emulator memory, sets up a minimal stack, hooks instruction and memory-write
39	events, and stops on a self-modified region or instruction budget.
40
41	### Step 3: Dump decoded stages
42
43	If the shellcode writes a new executable region, dump that buffer for follow-on analysis.
44
45	### Step 4: Document
46
47	Record the entry behavior, decoded stage offset, and any observed (stubbed) API references.
48
49	## Validation
50
51	- Emulation halts on the instruction budget or a clear decode-complete signal — never hangs.
52	- A decoded stage, if produced, has a recognizable header (MZ/known opcode prologue).
53	- Unsupported instructions/APIs are reported, not silently ignored.
54
55	## Pitfalls
56
57	- Missing API/syscall environment causing early faults — stub the calls the stub needs.
58	- Wrong architecture/bitness producing immediate invalid-instruction faults.
59	- Emulating an anti-emulation stub that detects timing/missing APIs.
60
61	## References
62
63	- See [`references/api-reference.md`](references/api-reference.md) for the emulator harness.
64	- Unicorn engine and ATT&CK T1620 (linked in frontmatter).

People who liked this also viewed

6 picks

Type

entra-app-registrationGuides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API perSkillsJul 2026471k1.3k
azure-complianceRun Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: SkillsJul 2026470k1.3k
azure-rbacOfficial agent plugin providing skills and MCP server configurations for Azure scenarios.SkillsJul 2026466k1.3k
better-auth-best-practicesAgent skill from better-auth/skillsSkillsJul 202678k203
firebase-security-rules-auditorA skill to evaluate how secure Firestore security rules are. Use this when Firestore security rules are updated to ensure that the generated rules are extremely secure and robust.SkillsJul 202676k386
audit-websiteAudit a website with the squirrelscan CLI and fix the findings in code. Runs SEO, performance, security, technical, content, accessibility, and 15 other rule categories (260+ rules), returns an LLM-opSkillsJul 202665k85

emulating-shellcode-with-unicorn

18stars5forks

View on GitHub

How to install emulating-shellcode-with-unicorn?

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

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

Installs into the current project.

Summary

Emulates position-independent shellcode in a controlled CPU emulator (Unicorn) to

Files · 1

View on GitHub

SKILL.md

1	# Emulating Shellcode With Unicorn
2
3	## When to Use
4
5	- You have a raw shellcode blob (decoder stub, egg hunter, staged loader) and want to observe its
6	behavior via emulation rather than native execution.
7	- You want to recover a second stage that the shellcode decrypts/decompresses in memory.
8
9	Do not use native execution for this — emulation contains the code. Unsupported API calls must
10	be stubbed; emulation is not a full Windows environment.
11
12	## Prerequisites
13
14	- The shellcode blob and the `unicorn` Python package (degrades gracefully if absent — the script
15	reports that emulation is unavailable and still does static prep).
16
17	## Safety & Handling
18
19	- Even under emulation, treat the blob as malicious; run on an isolated VM and store stages
20	password-protected.
21
22	## Workflow
23
24	### Step 1: Prepare and validate the blob
25
26	```bash
27	python scripts/analyst.py prep shellcode.bin --arch x64
28	```
29
30	Reports size, detected architecture hints, and whether Unicorn is available.
31
32	### Step 2: Emulate with an instruction/memory trace
33
34	```bash
35	python scripts/analyst.py emulate shellcode.bin --arch x64 --max-insns 200000
36	```
37
38	Maps the code into emulator memory, sets up a minimal stack, hooks instruction and memory-write
39	events, and stops on a self-modified region or instruction budget.
40
41	### Step 3: Dump decoded stages
42
43	If the shellcode writes a new executable region, dump that buffer for follow-on analysis.
44
45	### Step 4: Document
46
47	Record the entry behavior, decoded stage offset, and any observed (stubbed) API references.
48
49	## Validation
50
51	- Emulation halts on the instruction budget or a clear decode-complete signal — never hangs.
52	- A decoded stage, if produced, has a recognizable header (MZ/known opcode prologue).
53	- Unsupported instructions/APIs are reported, not silently ignored.
54
55	## Pitfalls
56
57	- Missing API/syscall environment causing early faults — stub the calls the stub needs.
58	- Wrong architecture/bitness producing immediate invalid-instruction faults.
59	- Emulating an anti-emulation stub that detects timing/missing APIs.
60
61	## References
62
63	- See [`references/api-reference.md`](references/api-reference.md) for the emulator harness.
64	- Unicorn engine and ATT&CK T1620 (linked in frontmatter).

People who liked this also viewed

6 picks

Type