magnus919/agent-skills/binary-analysis

Binary Analysis — Agent Skill

Plan analysis of unknown binary files through a deterministic, non-interactive CLI intended for Ghidra; see the implementation limitation below. The skill teaches you how to reason about binaries: when to triage versus deep-dive, how to interpret canonical evidence, and how to produce auditable reports. All observable operations happen through the binary CLI — you never call Ghidra APIs directly.

Implementation status

This release does not provide live Ghidra analysis. Import, analyze, metadata, structural/function queries, search, triage, and report generation stop with an explicit backend error. Installing dependencies cannot make the unfinished adapter operational. Project administration and dependency diagnostics remain available. The production CLI does not load or select FakeAdapter; tests inject it explicitly. There is no fixture/demo CLI switch or environment override.

The workflow below describes the intended interface, not runnable analysis in this release. Stop at the backend error and explain the limitation. Do not cite old fixture-derived reports as evidence about a user's binary, even if an old project is marked READY. A future live backend needs verification on distinct known binaries before results can be treated as observations.

When to Use

Load this skill when any of the following conditions match:

• A user provides a binary file (PE, ELF, Mach-O, firmware image) and asks what

it does, what APIs it imports, or whether it is suspicious.

• A user asks for decompilation, disassembly, call-graph exploration, or

cross-reference analysis of a specific function or address.

• A user wants a structured triage report, suspicious-API analysis, or

capability map for an unknown binary.

• A user asks to compare two binaries, verify export tables, or extract strings

matching a pattern.

• A user wants to set up the analysis toolchain (binary doctor, `binary

bootstrap`) or manage analysis projects.

When Not to Use

Do not load this skill for:

• Runtime or dynamic analysis — debugging, strace/dtrace, sandbox

execution, process monitoring. This skill is static-analysis only (V1).

• Binary patching or modification — hex-editing, resource editing,

repackaging. The analysis harness is read-only by design.

• Binaries you already fully understand — if the user is asking for

documentation or explanation of known code, use a general-purpose skill.

• Source-code analysis — C, C++, Rust, or assembly source files. Use a

language-specific or general code-analysis skill instead.

• Network forensics or packet capture — PCAP analysis, protocol reverse

engineering at the wire level. Use a network-focused skill.

• Live memory forensics — process memory dumps, heap analysis. Static

analysis of memory-mapped regions from files is in scope; live-process introspection is not.

What the Agent Owns vs What the CLI Owns

This boundary is the most important concept in the skill. Crossing it produces unreliable evidence, wasted context, or both.

Rule of thumb: A JSON data field alone does not establish evidence. Verify that results came from an implemented live backend for the supplied binary. If you are tempted to infer something not directly supported by that evidence, flag it as an agent inference and note the confidence gap.

Core Workflow

Every analysis session follows this sequence. Do not skip phases — each one produces evidence the next phase depends on.

Phase 1: Environment Check

binary doctor --json

If any component reports severity: "ERROR", run the bootstrap plan:

binary bootstrap --plan --json

Review the plan. If the user authorizes installation, run:

binary bootstrap --apply --json

Verify with binary version --json.

Phase 2: Project Setup

Create a project for every binary you analyze. Projects isolate analysis state and provide an audit trail.

binary project create <project-name> --json
binary import <path-to-binary> --project <project-name> --json

Use copy mode (default) for reproducibility. Use --reference only when the binary is large, read-only, or shared across projects, and explain the staleness risk to the user.

Phase 3: Initial Analysis

Run the standard analysis profile first. It covers the structural queries most triage workflows need.

binary analyze --project <project-name> --json

Check the response:

• success: true, partial: false — proceed to Phase 4.
• success: true, partial: true — review diagnostics for gaps. Proceed with

bounded results, noting limitations.

• success: false, partial: true — timeout. Extract what completed, report

what did not.

• success: false, partial: false — hard failure. Check diagnostics for the

failure reason. The project is now FAILED; run binary project clean to reset.

Phase 4: Evidence Collection

Choose analyses based on the user's question. Run these in order, building evidence from broad to specific.

For triage (broad survey):

binary triage --project <project-name> --json
binary suspicious-apis --project <project-name> --json
binary capability-map --project <project-name> --json

For structural understanding:

binary metadata --project <project-name> --json
binary sections --project <project-name> --json
binary entrypoints --project <project-name> --json
binary imports --project <project-name> --json
binary exports --project <project-name> --json
binary strings --project <project-name> --contains "<pattern>" --json

For function-level deep-dive:

binary functions --project <project-name> --json
binary decompile --project <project-name> <function-selector> --json
binary disassemble --project <project-name> <target> --json
binary xrefs --project <project-name> <entity-selector> --json
binary callers --project <project-name> <function-selector> --json
binary callees --project <project-name> <function-selector> --json
binary callgraph --project <project-name> <function-selector> --depth 3 --json

For path analysis:

binary trace --project <project-name> --from <source> --to <target> --json

Phase 5: Report and Handoff

Generate a durable report before explaining results to the user:

binary export-report --project <project-name> --type triage --format markdown --json

Read the report. Synthesize findings into a clear explanation. Always mark agent inferences separately from CLI evidence. Example:

## CLI Evidence (deterministic)
- The binary imports VirtualAlloc, WriteProcessMemory, and CreateRemoteThread
  (suspicious-apis, risk_score 8, rule_id: process-injection)
- Entry point at 0x401000, 3 sections (.text, .rdata, .data)
 
## Agent Assessment (inference)
- The API combination suggests process injection capability. This is a
  heuristic, not a confirmed behavior. The binary would need to be executed
  (out of scope for static analysis) to confirm.

Safety Boundaries

The CLI enforces these boundaries automatically. You must never attempt to bypass them, even if a user asks.

Evidence Standards

All CLI evidence follows a confidence hierarchy. Use these standards when citing evidence in reports or explanations.

Evidence Categories (triage output)

Confidence Levels

Agent Inferences

When you synthesize multiple CLI observations into a conclusion, label it explicitly as an agent inference. Never present an inference as a CLI fact. Use language like:

• "Based on the combination of X and Y, the agent assesses that..."
• "The CLI reports Z as a heuristic (confidence: MEDIUM). The agent interprets

this as consistent with..."

• "The CLI could not determine W. The agent notes this is an open question."

Reference Routing

References are loaded on demand — do not read them all at startup. Use this table to route your current task to the right reference file.