binary-re

Use when user has a binary/executable/bytecode and wants to understand what it does, how it works, or analyze its behavior. Triggers on "I have a binary", "this executable", "what does this binary do", "how does this work", "can you analyze", "figure out what", "reverse engineer", "disassemble", "decompile", "pyc file", "python bytecode", "obfuscated python", "marshal". Covers ELF, shared libraries, kernel modules, firmware, Python bytecode for ARM64, ARMv7, x86_64, MIPS, RISC-V using radare2, Ghidra, GDB, QEMU, pycdc.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 6, 2026

When & Why to Use This Skill

The Binary Reverse Engineering skill is a comprehensive framework for analyzing executables, shared libraries, and bytecode across various architectures including ARM, x86, MIPS, and RISC-V. By integrating powerful tools like radare2, Ghidra, and QEMU, it enables users to perform deep static and dynamic analysis to uncover program logic, identify security vulnerabilities, and decompile obfuscated code. This skill is essential for security researchers and developers needing to understand the inner workings of software without access to the original source code.

Use Cases

  • Malware Analysis: Investigating suspicious binaries to understand their behavior, network activity, and potential impact on a system.
  • Legacy Software Maintenance: Reverse engineering old executables to understand their internal logic and dependencies when source code is no longer available.
  • Security Vulnerability Research: Auditing firmware, kernel modules, and shared libraries for security flaws, hardcoded secrets, or potential backdoors.
  • Python Bytecode Recovery: Decompiling .pyc files and analyzing obfuscated Python bytecode or marshal objects to restore original logic.
  • Cross-Architecture Debugging: Emulating and tracing binaries from different hardware platforms (e.g., analyzing ARM firmware on an x86 host) using QEMU and GDB.
namebinary-re
descriptionThis skill should be used when analyzing binaries, executables, or bytecode to understand what they do or how they work. Triggers on "binary", "executable", "ELF", "what does this do", "reverse engineer", "disassemble", "decompile", "pyc file", "python bytecode", "analyze binary", "figure out", "marshal". Routes to sub-skills for triage, static analysis, dynamic analysis, synthesis, or tool setup.

Binary Reverse Engineering

Purpose

Comprehensive guide for binary reverse engineering. This skill provides the overall methodology, philosophy, and reference material. Related skills handle specific phases:

Skill Purpose Trigger Keywords
binary-re:triage Fast fingerprinting "what is this binary", "identify", "file type"
binary-re:static-analysis r2 + Ghidra analysis "disassemble", "decompile", "functions"
binary-re:dynamic-analysis QEMU + GDB + Frida "run", "execute", "debug", "trace"
binary-re:synthesis Report generation "summarize", "report", "document findings"
binary-re:tool-setup Install tools "install", "setup", "tool not found"

Note: Each skill auto-detects based on keywords. You don't need to explicitly route - just ask what you need.

Pre-Flight Verification

Before beginning any analysis, verify tooling availability:

Core Tools (Required)

rabin2 -v  # Should show version
r2 -v      # Should show version

Decompilation (Optional)

# Check r2ghidra availability
r2 -qc 'pdg?' - 2>/dev/null | grep -q Usage && echo "r2ghidra OK" || echo "r2ghidra missing - install with: r2pm -ci r2ghidra"

Dynamic Analysis Platform Check

Host Platform Method Setup Required
Linux x86_64 Native QEMU apt install qemu-user
macOS (any) Docker + binfmt See binary-re-tool-setup skill
Windows WSL2 Use Linux method inside WSL

If dynamic tools unavailable: Proceed with static-only analysis, note reduced confidence in synthesis phase.

Fallback Tooling (No r2/Ghidra)

When radare2 or Ghidra aren't available, use standard binutils/LLVM tools:

# Metadata (replaces rabin2 -I)
readelf -h binary              # ELF header
readelf -d binary              # Dynamic section (dependencies)
file binary                    # Quick identification

# Imports/Exports (replaces rabin2 -i/-E)
readelf -Ws binary | grep -E "FUNC|OBJECT" | awk '{print $8}'
nm -D binary 2>/dev/null       # Dynamic symbols

# Strings (replaces rabin2 -zz)
strings -a -n 8 binary | grep -Ei 'http|ftp|/etc|/var|error|pass|key|token|api'

# Disassembly (replaces r2 pdf)
objdump -d -M intel binary | head -500
# Or LLVM (better cross-arch support):
llvm-objdump -d --no-show-raw-insn binary | head -500

# Dependencies (replaces rabin2 -l)
ldd binary 2>/dev/null || readelf -d binary | grep NEEDED

Limitations of fallback approach:

  • No cross-references (axt/axf) - must trace manually
  • No decompilation - assembly only
  • No function boundary detection - raw disassembly
  • Reduced accuracy for stripped binaries

Philosophy

The LLM drives analysis; the human provides context.

Human provides:

  • Platform info (device type, OS, hardware)
  • Suspected purpose (what the binary might do)
  • Constraints (no network, isolated env, etc.)

LLM executes:

  • Tool selection and invocation
  • Hypothesis formation from evidence
  • Experiment design
  • Knowledge synthesis

The Agentic Loop

┌─────────────────────────────────────────────────┐
│           HYPOTHESIS-DRIVEN ANALYSIS            │
├─────────────────────────────────────────────────┤
│                                                 │
│  0. I/O SANITY → Compare known inputs/outputs   │
│  1. OBSERVE → Gather facts via tools            │
│  2. HYPOTHESIZE → Form theories from facts      │
│  3. PLAN → Design experiments to test theories  │
│  4. EXECUTE → Run tools (gate risky ops)        │
│  5. RECORD → Capture observations               │
│  6. UPDATE → Confirm/refute hypotheses          │
│  7. LOOP → Until understanding sufficient       │
│                                                 │
└─────────────────────────────────────────────────┘

Step 0: Compare Known I/O First (CRITICAL)

Before diving into code analysis, always check if known inputs/outputs exist.

This step prevents hours of wasted analysis by establishing ground truth first.

⚠️ REQUIRES HUMAN APPROVAL - Even for I/O comparison, get explicit approval before execution.

# SAFE: Use emulation for cross-arch binaries (after human approval)
# ARM32 example:
qemu-arm -L /usr/arm-linux-gnueabihf -- ./binary input.txt > actual_output.txt

# x86-64 native (still requires approval):
./binary input.txt > actual_output.txt

# Docker-based (macOS - safest option):
docker run --rm --platform linux/arm/v7 -v ~/samples:/work:ro \
  arm32v7/debian:bullseye-slim /work/binary /work/input.txt > actual_output.txt

# Compare outputs:
diff expected_output.txt actual_output.txt
cmp -l expected_output.txt actual_output.txt | head -20  # Byte-level

# Document the delta:
# - Where does output first diverge?
# - What pattern appears in the corruption?
# - Does file size match (logic bug) or differ (truncation)?

Record as FACT:

FACT: Output differs at byte {N}, expected "{X}" got "{Y}" (source: diff/cmp)
FACT: File sizes match/differ by {N} bytes (source: ls -l)

This single step often reveals the bug category before any disassembly.

Knowledge Model

Throughout analysis, maintain structured knowledge via episodic memory:

FACTS: Verified observations with tool attribution
HYPOTHESES: Theories with confidence and evidence
QUESTIONS: Open unknowns blocking progress
EXPERIMENTS: Planned tool invocations
OBSERVATIONS: Results from experiments
DECISIONS: Human-approved choices with rationale

Episodic Memory Integration

Knowledge persists across sessions via episodic memory. Use consistent tagging:

[BINARY-RE:{phase}] {artifact_name} (sha256: {hash})
FACT: {observation} (source: {tool})
HYPOTHESIS: {theory} (confidence: {0.0-1.0})
QUESTION: {unknown}
DECISION: {choice} (rationale: {why})

Starting analysis: Search episodic memory for artifact hash first After each phase: Findings are automatically captured in conversation Resuming: Search [BINARY-RE] {artifact_name} to restore context

Human-in-the-Loop Triggers

ALWAYS ask human before:

  1. Executing the binary - Even under QEMU, confirm sandbox
  2. Network operations - Prevent unintended phone-home
  3. Conflicting evidence - Resolve contradictory findings
  4. Privileged operations - Device access, root actions
  5. Major direction changes - Significant analysis pivots

Session Management

Starting New Analysis

1. Compute artifact hash: sha256sum binary
2. Search episodic memory: "[BINARY-RE] sha256:{hash}"
3. If previous analysis found:
   → "Found previous analysis from {date}. Resume or start fresh?"
4. If resuming: Load facts/hypotheses, continue from last phase
5. If fresh: Begin with triage phase

Resuming Interrupted Analysis

User: "Continue analyzing that thermostat binary"

Claude:
1. Invoke episodic-memory:search-conversations
   Query: "[BINARY-RE] thermostat"
2. Retrieve previous session findings
3. Summarize: "Last session identified ARM32/musl, found network
   functions. We were about to run dynamic analysis."
4. Continue from that phase

Searching Past Analyses

User: "Have we analyzed any ARM binaries with hardcoded passwords?"

Claude:
1. Search: "[BINARY-RE] FACT: hardcoded" or "[BINARY-RE] ARM"
2. Return matching artifacts and findings

Standard Analysis Flow

For typical unknown binary analysis:

1. Triage (binary-re-triage)
   └─ Architecture, ABI, dependencies, capabilities

2. Static Analysis (binary-re-static-analysis)
   └─ Functions, strings, xrefs, decompilation

3. Dynamic Analysis (binary-re-dynamic-analysis) - if safe
   └─ Syscalls, network, file access

4. Synthesis (binary-re-synthesis)
   └─ Structured report with evidence

Quick Reference

Essential Commands

# Fast triage
rabin2 -I binary              # Metadata
rabin2 -l binary              # Dependencies
rabin2 -zz binary             # Strings

# Static analysis
r2 -q -c 'aa; aflj' binary    # Functions
r2 -q -c 'izj' binary         # Strings

# Dynamic (ARM example)
qemu-arm -L /usr/arm-linux-gnueabihf -strace ./binary

Architecture Detection

Indicator Architecture QEMU Binary Ghidra Processor
e_machine=EM_386 (3) x86 32-bit qemu-i386 or Docker --platform linux/i386 x86:LE:32:default
e_machine=EM_ARM (40) ARM 32-bit qemu-arm or Docker --platform linux/arm/v7 ARM:LE:32:v7
e_machine=EM_AARCH64 (183) ARM 64-bit qemu-aarch64 or Docker --platform linux/arm64 AARCH64:LE:64:v8A
e_machine=EM_X86_64 (62) x86-64 Native or Docker --platform linux/amd64 x86:LE:64:default
e_machine=EM_MIPS (8) MIPS 32 LE qemu-mipsel MIPS:LE:32:default
e_machine=EM_MIPS (8) BE MIPS 32 BE qemu-mips MIPS:BE:32:default
e_machine=EM_RISCV (243) RISC-V 64 qemu-riscv64 RISCV:LE:64:RV64I
e_machine=EM_RISCV (243) 32 RISC-V 32 qemu-riscv32 RISCV:LE:32:RV32I

Libc Detection

Interpreter Libc
ld-linux-armhf.so.3 glibc (ARM hard-float)
ld-musl-arm.so.1 musl
ld-uClibc.so.0 uClibc

Error Recovery

Situation Action
Tool not found Use binary-re-tool-setup skill
Wrong architecture Re-run triage, verify file output
QEMU fails Try Qiling, Unicorn, or on-device
Analysis timeout Reduce scope, use aa not aaa
Conflicting evidence Ask human, document both interpretations

Documentation

See companion docs:

  • docs/r2-commands.md - Complete r2 reference for LLMs
  • docs/ghidra-headless.md - Ghidra scripting guide
  • docs/arch-adapters.md - Per-architecture quirks
  • docs/python-bytecode-re.md - Python .pyc/marshal obfuscation patterns

Integration

Works with other plugins:

  • remote-system-maintenance: Extract binaries from devices via SSH
  • fresh-eyes-review: Validate conclusions before documenting
  • scenario-testing: Create reproducible analysis environments