---
name: operate-binary-analysis-toolchain
description: Operate Ghidra headless analysis, radare2, platform binary utilities, decompilers, and targeted dynamic evidence for advanced native and bytecode security review. Use for stripped or optimized binary triage, architecture and hardening analysis, call-graph and dataflow reconstruction, patch diffing, parser or trust-boundary review, JNI/native correlation, or resolving disagreements between decompilers and actual machine behavior.
metadata:
  domain: security-tooling
  subdomain: binary-analysis
  triggers:
    - reverse engineer binary
    - inspect executable
    - analyze disassembly
    - inspect binary mitigations
    - decompile native code
    - assess exploit primitives
  tags:
    - Ghidra
    - radare2
    - ELF
    - PE
    - Mach-O
    - reverse-engineering
  frameworks:
    nist_csf:
      - ID.RA
---

# Operate Binary Analysis Toolchain

Treat decompiler output as a lossy hypothesis. Anchor conclusions in bytes, relocations, calling convention, control/data flow, and runtime evidence.

## Establish artifact identity

Record cryptographic hash, source/provenance, format, architecture/subarchitecture, endianness, ABI, load address, sections/segments, imports/exports, relocations, interpreter/runtime, signatures, debug symbols, packing, and hardening. Use bounded `xxd` views when raw bytes resolve format ambiguity, and `archive_extract` for signature-detected, bounded, atomic ZIP, TAR-family, compressed-stream, and native 7-Zip publication. Keep universal/fat slices and platform variants separate.

## Triage before decompiling

Map entry points, initialization/finalization, exported interfaces, IPC/network/file/parser boundaries, privilege transitions, cryptographic and verification APIs, dynamic loading, dangerous memory/process functions, error/log paths, and embedded configuration. Use strings only as cross-reference seeds.

Use the persistent Ghidra MCP as the primary semantic workspace:

1. call `ghidra_import` with a relative workarea path and retain its SHA-256;
2. poll the returned identifier with `ghidra_job` instead of blocking on analysis;
3. use `ghidra_search`, `ghidra_xrefs`, and `ghidra_call_graph` to narrow the boundary; when a name or signature is ambiguous, select only a returned canonical address rather than guessing;
4. confirm decisive sites with `ghidra_listing` and `ghidra_decompile`;
5. preserve hypotheses and confidence with `ghidra_annotations`;
6. create a `ghidra_project` checkpoint before handoff.

The project, analysis, names, comments, bookmarks, and job history survive phase and runtime replacement. Cite the automatically captured `raw/ghidra/` evidence paths in handoffs and reports. Never request arbitrary scripts or binary patching through the MCP; use radare2 and platform tools to independently confirm sections, functions, references, and instructions at critical sites.

Read [references/binary-analysis-fieldbook.md](references/binary-analysis-fieldbook.md) when reconstructing optimized code or patch-diffing.

## Reconstruct security invariants

For each boundary:

1. identify exact calling convention and argument ownership;
2. trace length, signedness, encoding, lifetime, and error values;
3. locate all dominating validation and authorization branches;
4. follow indirect calls, vtables, jump tables, callbacks, and dynamic imports;
5. inspect cleanup and exceptional exits;
6. verify ambiguous behavior in disassembly or a bounded runtime trace.

Search both forward from untrusted input and backward from sensitive effects.

## Account for compiler transformations

Expect inlining, tail calls, thunks, split functions, merged constants, stack-slot reuse, dead-code elimination, exception tables, link-time optimization, and control-flow flattening. Rename functions and types only with confidence annotations. Preserve raw addresses and image bases so another analyst can reproduce references.

## Diff by semantics

For patches, normalize addresses and compiler noise; compare control-flow shape, constants, call targets, bounds, validation order, error handling, and data structure layout. Trace the changed invariant outward to sibling functions and older product branches. A one-line source fix may compile into several sites, while a large binary diff may be toolchain noise.

Use `binary_diff compare_programs`, `changed_functions`, `changed_calls`, and `changed_constants` to retain reproducible first-pass evidence. Use `security_candidates` only to prioritize manual validation; its heuristic label is not a finding. Confirm decisive changes in Ghidra listings or raw disassembly.

## Deliver

Preserve hashes, loader options, analysis database/project, script versions, architecture assumptions, annotated functions, raw disassembly at decisive sites, xrefs, dynamic traces, unresolved indirect calls, and confidence. Report the earliest violated invariant and a reproducible input or state when possible.