/binary-analysis

name: binary-analysis
description: Layer 1 methodology for extracting behavioral intelligence from compiled binaries, bytecode archives, managed assemblies, and bundled applications. Covers artifact identification, string extraction strategy, decompilation workflows, provenance requirements, and handoff to source code mode.

Binary Analysis Methodology

Extract behavioral intelligence from compiled artifacts when source code is unavailable. Static analysis only — the binary is never executed.

When This Mode Applies

Binary analysis activates when:

• The `/analyze` command detects compiled artifacts in the target
• The discovery inventory identifies compiled binaries at the target path
• Other modes discover compiled artifacts during analysis (e.g., a bundled native binary inside an npm package)

Binary Type Taxonomy

| Artifact Type | Format | Survey Tools | Decompiler | Decompilation Quality | Default Confidence | |--------------|--------|-------------|------------|----------------------|-------------------| | Native binaries | ELF, Mach-O, PE | `file`, `readelf`/`otool`/`objdump`, `nm`, `strings` | Ghidra, radare2 (disassembly only) | N/A (no source recovery) | `assumed` | | JVM bytecode | `.class`, `.jar`, `.war` | `jar tf`, `javap -public`, manifest extraction | CFR, Procyon, FernFlower | Very high | `inferred` | | .NET assemblies | `.dll`, `.exe` (managed) | `dotnet ildasm`, type enumeration, attributes | ILSpy (`ilspycmd`) | Very high | `inferred` | | Python bytecode | `.pyc`, `.pyo` | Magic number inspection, `strings` | uncompyle6, decompyle3, pycdc | Very high | `inferred` | | Electron apps | `.asar` bundles | `npx asar extract`, `package.json` | N/A (lossless source recovery) | Lossless | `inferred` | | WebAssembly | `.wasm` | `wasm-tools print`, export/import enumeration | `wasm2wat` (text format only) | Limited | `assumed` |

Agents

| Agent | Role | Output Location | |-------|------|----------------| | `binary-surveyor` | Initial triage: type ID, strings, symbols, metadata, dependencies, decompilation attempts | `workspace/raw/binary/survey/` | | `binary-deep-analyzer` | Deep analysis: disassembly, control flow, data structures, algorithms, protocols | `workspace/raw/binary/analysis/` |

The surveyor always runs first. The deep analyzer runs on modules the surveyor recommends.

Tool Reference

Identification

file target.bin                        # Magic-based type identification

Native Binary Tools (ELF)

readelf -h target.bin                  # ELF header
readelf -S target.bin                  # Section headers
readelf --dyn-syms target.bin          # Dynamic symbol table
readelf -d target.bin                  # Dynamic section (dependencies)
readelf --debug-dump=info target.bin   # Debug info (DWARF)
nm target.bin                          # Symbol table (empty if stripped)
nm -D target.bin                       # Dynamic symbols only
ldd target.bin                         # Shared library dependencies
strings -a -n 4 target.bin            # ASCII strings
strings -a -el -n 4 target.bin        # Wide-character (UTF-16LE) strings
objdump -d --section=.text target.bin  # Disassemble text section

Native Binary Tools (Mach-O)

otool -h target.bin                    # Mach-O header
otool -l target.bin                    # Load commands
otool -TV target.bin                   # Exports trie
otool -L target.bin                    # Linked libraries

Native Binary Tools (PE)

objdump -x target.exe                 # All headers
objdump -p target.exe                 # Private headers (imports/exports)

Disassemblers (Deep Analysis)

# Ghidra headless mode
$GHIDRA_HOME/support/analyzeHeadless \
  /tmp/ghidra-project project-name \
  -import target.bin \
  -postScript ExportDisassembly.java \
  -scriptPath /analysis/scripts/

# radare2: function disassembly
r2 -q -c 'aaa; pdf @ sym.main' target.bin

# radare2: function list
r2 -q -c 'aaa; afl' target.bin

# radare2: string cross-references
r2 -q -c 'aaa; axt @ str.error_message' target.bin

JVM Tools

jar tf target.jar                      # List contents
unzip -p target.jar META-INF/MANIFEST.MF  # Extract manifest
javap -public com.example.MainClass    # Public API surface
java -jar cfr.jar target.jar --outputdir decompiled/  # Decompile

.NET Tools

dotnet ildasm target.dll               # Type/method listing
ilspycmd target.dll -o decompiled/     # Decompile to C#

Python Tools

# Version identification from magic number
python3 -c "
with open('target.pyc', 'rb') as f:
    magic = f.read(4)
    print(f'Magic: {magic.hex()}')
"
uncompyle6 target.pyc > decompiled.py  # Decompile

Electron/ASAR Tools

npx asar list app.asar                 # List contents
npx asar extract app.asar extracted/   # Extract (lossless)

WebAssembly Tools

wasm-tools print target.wasm | head -100  # Text format summary
wasm2wat target.wasm -o target.wat     # Full WAT conversion

Analysis Methodology

digraph binary_analysis {
    rankdir=TB;

    "Start binary analysis" [shape=doublecircle];
    "Survey: identify type, strings, symbols, metadata" [shape=box];
    "Extract behavioral claims from strings" [shape=box];
    "Is it managed code?" [shape=diamond];
    "Attempt decompilation" [shape=box];
    "Decompilation succeeded?" [shape=diamond];
    "Hand off to source code mode agents" [shape=box];
    "Perform deep disassembly analysis" [shape=box];
    "Document gaps explicitly" [shape=box];
    "Binary analysis complete" [shape=doublecircle];

    "Start binary analysis" -> "Survey: identify type, strings, symbols, metadata";
    "Survey: identify type, strings, symbols, metadata" -> "Extract behavioral claims from strings";
    "Extract behavioral claims from strings" -> "Is it managed code?";
    "Is it managed code?" -> "Attempt decompilation" [label="yes (JV