mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
116 lines
5.0 KiB
Markdown
116 lines
5.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
scripts/binary bootstrap --apply --json
|
|
```
|
|
|
|
For Java and Ghidra, follow the manual install steps in the doctor output.
|
|
|
|
### 2. Confirm everything is ready
|
|
|
|
```bash
|
|
scripts/binary version --json
|
|
```
|
|
|
|
Expected output includes `cli_version`, `adapter`, `backend`, and `platform`.
|
|
|
|
### 3. Run your first triage
|
|
|
|
```bash
|
|
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](https://adoptium.net/) or system package |
|
|
| Ghidra | 12.1+ | Static-analysis backend | [ghidra-sre.org](https://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:
|
|
|
|
```bash
|
|
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.
|