ghidra-agent

Ghidra Binary Analysis Subagent

Overview

This subagent specializes in reverse engineering binaries using Ghidra CLI. It provides efficient, token-optimized access to binary analysis capabilities for Claude Code and other AI agents.

When to Use This Subagent

Use this subagent when you need to:

• Analyze binary executables (PE, ELF, Mach-O)
• Reverse engineer malware or suspicious binaries
• Extract functions, strings, imports/exports from binaries
• Decompile functions to understand behavior
• Find specific patterns in binary code
• Analyze memory layout and structure
• Identify crypto functions, network operations, or file I/O
• Generate reports on binary capabilities

Capabilities

Data Extraction

• **Functions**: List, filter, and decompile functions
• **Strings**: Extract and search string literals
• **Imports/Exports**: Analyze external dependencies
• **Memory Layout**: View memory regions and permissions
• **Symbols**: Access symbol table
• **Cross-References**: Find call relationships

Analysis Features

• **Universal Query System**: Query any data type with powerful filters
• **Advanced Filtering**: Complex boolean expressions with field-level filtering
• **Multiple Output Formats**: JSON, CSV, Table, minimal (token-efficient)
• **Decompilation**: Convert assembly to C-like pseudocode
• **Pattern Matching**: Find specific code patterns and strings

LLM Optimizations

• **Count-First Workflow**: Check result sizes before fetching data
• **Field Selection**: Request only needed fields
• **Aggressive Filtering**: Pre-filter on Ghidra side
• **Compact Formats**: Minimal token usage with `json-compact`
• **Pagination**: Handle large datasets efficiently

Command Reference

Quick Start

# Import and analyze a binary
ghidra import <binary-path> --project=<project>

# Get program summary
ghidra summary --program=<binary>

Universal Query

# Query any data type
ghidra query <data-type> --program=<binary> [options]

# Data types: functions, strings, imports, exports, memory
# (symbols and xrefs have their own commands: `ghidra symbol list`, `ghidra x-ref ...`)

# Essential options:
  --filter="<expression>"    # Filter results
  --fields=<list>            # Select specific fields
  --format=<format>          # Output format (json, json-compact, table, count)
  --limit=<n>                # Max results
  --count                    # Just return count

Common Queries

# List functions with filtering
ghidra query functions --program=<binary> \
  --filter="size>1000 AND name~crypt" \
  --fields=name,address,size \
  --format=json-compact

# Find strings
ghidra query strings --program=<binary> \
  --filter="value~http" \
  --format=minimal

# List imports
ghidra dump imports --program=<binary> \
  --filter="name~Crypt" \
  --format=json-compact

# Get memory map
ghidra query memory --program=<binary> --format=table

Decompilation

# Decompile function by address
ghidra decompile 0x401000 --program=<binary>

# Decompile by name
ghidra decompile main --program=<binary>

# Compact output
ghidra fn decompile <addr> --program=<binary> --format=compact

Filter Language

Operators

Comparison:     =, !=, >, >=, <, <=
String:         ~ (contains), ^ (starts), $ (ends), =~ (regex)
Logical:        AND, OR, NOT, ()
Special:        EXISTS, IN [val1,val2]

Examples

# Exact match
name=malloc

# Numeric comparison
size>1000

# String matching (case-insensitive)
name~crypt

# Boolean logic
name~crypt AND size>500
(name~main OR name~start) AND NOT name^FUN_

# IN operator
name IN [malloc,free,realloc]

# Field existence
calls EXISTS

# Complex expression
size>=100 AND size<=1000 AND (name~crypt OR calls~Crypt)

Output Formats

• `count` - Just the number (check result size)
• `json-compact` - Minimal JSON (best for LLMs)
• `minimal` - Addresses/names only (piping)
• `ids` - Just IDs (for further queries)
• `table` - Human-readable (display)
• `json` - Full JSON (complete data)

Best Practices

1. Count-First Pattern

Always check the result size before fetching data:

# Step 1: Count
ghidra query functions --program=<binary> --count

# Step 2: Refine filter if needed
ghidra query functions --program=<binary> \
  --filter="NOT name^FUN_" \
  --count

# Step 3: Fetch minimal data
ghidra query functions --program=<binary> \
  --filter="NOT name^FUN_" \
  --fields=name,address \
  --format=json-compact \
  --limit=50

2. Aggressive Filtering

Filter on Ghidra side, not in your code:

# GOOD: Pre-filter
ghidra query functions --program=<binary> \
  --filter="size>1000 AND name~crypt"

# BAD: Fetch all, then filter
ghidra query functions --program=<binary>  # Then filter in code

3. Field Selection

Request only what you need:

# Only name and address
ghidra query functions --program=<binary> \
  --fields=name,address \
  --format=json-compact

4. Use Compact Formats

Minimize token usage:

# For analysis: json-compact
--format=json-compact

# For display: table
--format=table

# For piping: minimal or ids
--format=ids

Analysis Workflows

Initial Reconnaissance

# 1. Get summary
ghidra summary --program=<binary>

# 2. Count functions
ghidra query functions --program=<binary> --count

# 3. Count named functions
ghidra query functions --program=<binary> \
  --filter="NOT name^FUN_" --count

# 4. List key functions
ghidra query functions --program=<binary> \
  --filter="NOT name^FUN_" \
  --fields=name,address,size \
  --format=json-compact \
  --limit=20

Finding Suspicious Behavior

# Network operations
ghidra query imports --program=<binary> \
  --filter="name~socket OR name~http OR name~inet" \
  --format=json-compact

# File operations
ghidra query imports --program=<binary> \
  --filter="name~File OR name~Read OR name~Write" \
  --format=json-compact

# Process operations
ghidra query imports -