Binary Analysis — Agent Skill

Give your AI agent the ability to analyze unknown binary files through a deterministic, read-only CLI backed by Ghidra's static-analysis engine.

Why Install This Skill

You have a binary file and you need to know what it does — but you don't have a reverse engineer on call. Maybe it's a vendor-supplied library without source code, a suspicious download, an embedded firmware image, or a legacy executable your team inherited. You want to answer questions like: What APIs does it call? Are there any suspicious capabilities? What does this specific function do?

This skill teaches AI agents how to use the binary CLI — a non-interactive, flag-driven analysis harness — to answer those questions systematically. The agent learns when to run a fast triage versus a deep function-level dive, how to separate deterministic evidence from interpretation, and how to produce structured, auditable reports.

After installing this skill, your agent can:

Triage unknown binaries — identify suspicious API imports, assess capabilities, and produce evidence-backed reports in under a minute.
Decompile and disassemble specific functions to understand logic without source code.
Map call graphs and cross-references to trace how functions relate to each other.
Extract structural data — sections, entry points, imports, exports, symbols, and strings — with cursor-based pagination.
Generate auditable reports in Markdown, JSON, HTML, or PDF with full provenance (binary SHA-256, adapter version, analysis profile).

What You Get

Directory	What It Provides
`SKILL.md`	Agent instructions: trigger rules, workflow phases, safety boundaries, evidence standards, and reference routing.
`README.md`	This file — human-facing documentation.
`scripts/binary`	The CLI entrypoint — 37 commands across 14 functional groups. Thin argparse wrapper, no network listeners.
`scripts/binary_analysis/`	Python package with CLI command implementations, canonical domain model (21 entities, 9 enums), project lifecycle, backend adapters (abstract + fake + Ghidra), reporting engine, rule engine, and optional worker daemon.
`references/`	Deep reference docs loaded on demand: installation, CLI reference, binary formats, triage workflow, function analysis, evidence methodology, security rules, packed binaries, firmware, troubleshooting, and reporting.
`tests/`	Unit, contract, integration, security, and golden tests with a fake backend for offline testing.
`assets/`	Report templates and rule sets.
`evals/`	Agent evaluation cases for output-quality verification.

Quick Start

1. Check your environment

cd binary-analysis
scripts/binary doctor --json

If anything reports severity: "ERROR", the output will include remediation hints. The bootstrap command can automate setup for PyGhidra:

scripts/binary bootstrap --apply --json

For Java and Ghidra, follow the manual install steps in the doctor output.

2. Confirm everything is ready

scripts/binary version --json

Expected output includes cli_version, adapter, backend, and platform.

3. Run your first triage

scripts/binary project create my-first-triage --json
scripts/binary import /path/to/suspicious.exe --project my-first-triage --json
scripts/binary analyze --project my-first-triage --json
scripts/binary triage --project my-first-triage --json

The triage output separates observations (deterministic facts), heuristics (rule-derived with confidence scores), and unknowns (unresolved questions).

Triggers

Your agent will load this skill when you say things like:

"Analyze this binary" or "What does this executable do?"
"Decompile this function" or "Show me the pseudocode for..."
"Is this binary suspicious?" or "What APIs does it import?"
"Trace the call path from main to socket"
"Generate a triage report for this firmware image"
"Check if Ghidra is set up correctly" or "Install the binary analysis tools"

The skill does not load for source-code analysis, runtime debugging, binary patching, or network forensics — those are different domains with their own skills.

Requirements

Dependency	Version	Purpose	Install
Python	3.12+	CLI runtime and analysis package	System or pyenv
Java JDK	21+	Ghidra runtime	Adoptium or system package
Ghidra	12.1+	Static-analysis backend	ghidra-sre.org
PyGhidra	3.1+	Python bridge to Ghidra	`pip install pyghidra` or `binary bootstrap --apply`

Set these environment variables before running Ghidra-backed commands:

export JAVA_HOME="/path/to/jdk-21"
export GHIDRA_INSTALL_DIR="/path/to/ghidra_12.1.2_PUBLIC"

Use scripts/binary doctor --json to verify your installation at any time. Commands that don't require Ghidra (project management, fake-backend tests) work without these variables.

5.0 KiB Raw Blame History