reverse-skills-max: initial public release (restored, redacted, hardened)

vendor-new/analyst-ai-pack/skills/reverse-engineering-shellcode/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: reverse-engineering-shellcode
+description: 'Analyzes position-independent shellcode: disassembling raw bytes at the right
+  architecture, recognizing PEB-walk API resolution and egg hunters, and emulating execution
+  to recover behavior and payloads. Activates for requests to analyze shellcode, disassemble
+  raw position-independent code, or emulate a shellcode blob.'
+domain: cybersecurity
+subdomain: reverse-engineering
+tags:
+  - reverse-engineering
+  - shellcode
+  - emulation
+  - position-independent
+  - peb-walk
+  - disassembly
+version: 1.0.0
+author: analyst-ai-pack
+license: Apache-2.0
+mitre_attack:
+  - T1055
+  - T1106
+  - T1027
+d3fend:
+  - D3-PSA
+  - D3-FCR
+references:
+  - 'Capstone disassembly framework — https://www.capstone-engine.org/'
+  - 'Unicorn CPU emulator — https://www.unicorn-engine.org/'
+---
+
+# Reverse Engineering Shellcode
+
+## When to Use
+
+- You extracted a raw code blob (from a document, exploit, injected memory region, or beacon)
+  with no PE/ELF headers.
+- You need to determine the architecture, recover the API-resolution method, and understand
+  what the shellcode does.
+- You want to emulate the shellcode safely to recover staged payloads or C2.
+
+**Do not use** a file-format parser on shellcode — there is no header. Treat it as a flat byte
+stream at a known base and disassemble/emulate.
+
+## Prerequisites
+
+- Capstone (`pip install capstone`) for disassembly; Unicorn (`pip install unicorn`) for
+  emulation.
+- Knowledge of the likely architecture/bitness (x86 vs x64) and calling context.
+
+## Workflow
+
+### Step 1: Determine architecture and entry
+
+Try disassembling as x86 and x64; the one that yields coherent instructions (and a sane
+prologue) is correct. Shellcode usually starts executing at offset 0.
+
+```bash
+python scripts/analyst.py disasm shellcode.bin --arch x64
+```
+
+### Step 2: Recognize API resolution
+
+Windows shellcode typically walks the PEB to find `kernel32`, then resolves exports by hash:
+
+```text
+mov rax, gs:[60h]        ; PEB (x64)   / mov eax, fs:[30h] (x86)
+... traverse Ldr -> InMemoryOrderModuleList
+... hash export names, compare to embedded constants
+```
+
+Recovered hash constants feed the API-hash resolver (see the obfuscation skill).
+
+### Step 3: Identify the technique
+
+Look for egg hunters (searching memory for a tag), socket setup (reverse/bind shell), or a
+download-and-exec stager (`WinINet`/`WinHTTP` resolution then a URL).
+
+### Step 4: Emulate to recover behavior
+
+Emulate with Unicorn, hooking memory and (optionally) faking API calls, to observe the
+control flow and extract strings/URLs the static view hides:
+
+```bash
+python scripts/analyst.py emulate shellcode.bin --arch x64 --base 0x140000000
+```
+
+### Step 5: Extract IOCs and payload
+
+Recover C2 URLs/hosts, embedded second stages, and the resolved API set for the report.
+
+## Validation
+
+- The chosen architecture yields a coherent prologue and no garbage instruction stream.
+- Recovered API hashes resolve to a sensible function set (LoadLibrary/GetProcAddress, network
+  APIs).
+- Emulation reaches the network/exec stage consistent with the static read.
+
+## Pitfalls
+
+- Disassembling at the wrong bitness and chasing nonsense.
+- Emulating without bounding execution, looping forever on unresolved calls.
+- Ignoring self-modifying decoders — emulate through the decode stub to reach real code.
+
+## References
+
+- See [`references/api-reference.md`](references/api-reference.md) for the disassembler and
+  emulator wrapper.
+- Capstone and Unicorn (linked in frontmatter).