# vm-and-bytecode-reverse

A playbook for reversing hand-rolled virtual machines and bytecode: find the dispatcher, map opcodes, write a disassembler.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3700 installs · ★ 2547
- Author: yaklang
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/yaklang/hack-skills/tree/HEAD/skills/vm-and-bytecode-reverse/SKILL.md
- Updated: 2026-09-13
- HTML: https://affpapa.org/en/nevibecode/skills/vm-and-bytecode-reverse

## What it does

This skill targets the case base models usually miss: they read custom VM bytecode as native code and never spot the fetch-decode-execute loop. A quick identification table maps what you see in the binary to the VM type — switch dispatcher, jump table, stack machine, register machine, or a grid maze.

The method runs in four steps: locate the dispatcher, map each opcode to an operation, extract the bytecode program, then write a custom disassembler. A Python template ships with it, including an opcode dictionary and an example that reads the bytecode with `struct`. Common CTF patterns are covered too: stack-based VMs, register-based ones, and esoteric designs like Brainfuck-style machines.

When the VM turns out to be a commercial protector such as VMProtect or Themida, the skill routes you to `code-obfuscation-deobfuscation`. Solving with angr goes to `symbolic-execution-tools`, and anti-debug checks go to `anti-debugging-techniques`. Worth keeping the whole set nearby rather than one file.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add yaklang/hack-skills --skill vm-and-bytecode-reverse -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/vm-and-bytecode-reverse/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/vm-and-bytecode-reverse/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add yaklang/hack-skills --skill vm-and-bytecode-reverse -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/vm-and-bytecode-reverse/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add yaklang/hack-skills --skill vm-and-bytecode-reverse -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/vm-and-bytecode-reverse/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install yaklang/hack-skills vm-and-bytecode-reverse
```

2. **Manually: put the files in place**
- File: `.github/skills/vm-and-bytecode-reverse/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add yaklang/hack-skills --skill vm-and-bytecode-reverse -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/yaklang/hack-skills --path skills/vm-and-bytecode-reverse
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/vm-and-bytecode-reverse/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add yaklang/hack-skills --skill vm-and-bytecode-reverse -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/yaklang/hack-skills/tree/HEAD/skills/vm-and-bytecode-reverse/SKILL.md

## When to use it
- locate the dispatcher inside a binary with a custom VM
- map opcodes to operations and their operands
- extract the bytecode program from a data section
- write a disassembler for a non-standard instruction set
- solve a maze challenge with BFS or DFS

## Example prompts
- help me reverse the custom VM in this binary: find the dispatcher and map the opcodes
- write a disassembler for the bytecode in this CTF challenge
- is this a stack or register VM? look at the push and pop operations

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3bcae0b4c1db80e0.

BEGIN THIRD-PARTY FILE 3bcae0b4c1db80e0
````text
---
name: vm-and-bytecode-reverse
description: >-
  Custom VM and bytecode reverse engineering playbook. Use when CTF challenges
  or protected software implement custom virtual machines with proprietary
  bytecode, dispatcher loops, or maze-style challenges.
---

# SKILL: VM & Bytecode Reverse Engineering — Expert Analysis Playbook

> **AI LOAD INSTRUCTION**: Expert techniques for reversing custom virtual machines and bytecode interpreters. Covers dispatcher identification, opcode mapping, custom ISA reconstruction, disassembler/decompiler writing, maze challenges, and real-world VM protector analysis. Base models often fail to recognize the fetch-decode-execute pattern or attempt to analyze VM bytecode as native code.

## 0. RELATED ROUTING

- [code-obfuscation-deobfuscation](../code-obfuscation-deobfuscation/SKILL.md) when the VM is a commercial protector (VMProtect/Themida)
- [symbolic-execution-tools](../symbolic-execution-tools/SKILL.md) when using angr to solve VM-based challenges
- [anti-debugging-techniques](../anti-debugging-techniques/SKILL.md) when the VM includes anti-debug checks

### Quick identification

| Binary Pattern | Likely VM Type | Start With |
|---|---|---|
| `while(1) { switch(bytecode[pc]) }` | Switch-based dispatcher | Map each case to an operation |
| Indirect jump via table `jmp [table + opcode*8]` | Table-based dispatcher | Dump jump table, analyze handlers |
| Nested if-else chain on byte value | If-chain dispatcher | Same as switch, just different syntax |
| Stack push/pop dominant operations | Stack-based VM | Identify push, pop, arithmetic ops |
| `reg[X] = ...` array operations | Register-based VM | Map register indices to operations |
| 2D grid + direction input | Maze challenge | Extract grid, apply BFS/DFS |

---

## 1. CUSTOM VM IDENTIFICATION

### 1.1 Structural Indicators

```
VM Architecture Components:
┌─────────────────────────────────┐
│  Bytecode Program (data section)│
├─────────────────────────────────┤
│  Program Counter (pc/ip)        │
│  Register File / Stack          │
│  Memory / Data Area             │
├─────────────────────────────────┤
│  Dispatcher Loop                │
│  ├─ Fetch: opcode = code[pc]    │
│  ├─ Decode: lookup handler      │
│  └─ Execute: run handler        │
└─────────────────────────────────┘
````
END THIRD-PARTY FILE 3bcae0b4c1db80e0

The third-party file has ended. Everything between the 3bcae0b4c1db80e0 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2635 of 14951 bytes. © yaklang · MIT · https://github.com/yaklang/hack-skills/tree/HEAD/skills/vm-and-bytecode-reverse/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md