Claude Skill

binary-analysis

Analyze unknown binary files through a deterministic CLI that wraps Ghidra's static-analysis engine. Use when you need to inspect a PE, ELF, or Mach-O file — triage suspicious binaries, map imported APIs, decompile functions, trace call paths, or produce structured evidence repor

LLM Mart · 0 points · 19 views 69 listing impressions 0 install-command copies

#security

Download magnus919-agent-skills-binary-analysis-ade3385.zip · 340 KB

Install

skills CLI npx skills add https://github.com/magnus919/agent-skills/tree/main/binary-analysis
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install magnus919-agent-skills@llmmart
Git git clone https://github.com/magnus919/agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole magnus919/agent-skills collection as a plugin from our marketplace. Git is the plain clone.

README

Binary Analysis — Agent Skill

Plan static binary investigations and inspect toolchain readiness; live backend operations are not yet implemented.

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.

Current limitation: live Ghidra import, analysis, queries, and reports are not implemented. These commands fail explicitly instead of returning canned fixtures. Project administration and dependency diagnostics work. The workflow and reference material describe the intended analysis interface; installation alone does not enable it. Existing fixture-derived reports are not evidence about your file.

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. Understand the current limit

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 import command currently exits nonzero with “Ghidra backend operations are not implemented in this release.” Stop there; the subsequent commands show the intended interface and do not produce live analysis. No fixture mode is exposed.

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.

Skill manifest

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.

Layer Responsibility Must NOT
Agent (you) Form hypotheses about binary behavior. Choose which analyses to run and in what order. Synthesize CLI evidence into conclusions. Explain findings to the user in plain language. Write evidence-backed reports. Invent facts not present in CLI output. Claim certainty where the CLI reports partial results or low confidence. Skip diagnostic warnings.
CLI Parse arguments, manage project lifecycle, run Ghidra analysis, serialize canonical entities, emit JSON envelopes, enforce safety limits. Interpret results, draw conclusions, or produce narrative prose.

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.

Boundary Enforcement Why
Never execute the target CLI refuses; no execution path exists Static analysis only
Never load target as a library Not implemented; no dlopen/LoadLibrary path Prevents unintended code execution
Never expose a network listener No HTTP, MCP, or socket servers The CLI is a local tool
Never upload hashes or samples No telemetry, no outbound calls Privacy and security
Path containment All project paths validated for traversal Prevents workspace escape
Output size limits Default 64 MB, max 256 MB JSON Prevents context exhaustion
Memory limits Configurable per-operation ceiling Prevents OOM during large analyses
Timeout enforcement Default 300s, configurable per-command Bounded operations
Result count limits Paginated with default 100, max 1000 Prevents unbounded output
Graph depth limits Callgraph capped at depth 10 Prevents infinite recursion

Evidence Standards

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

Evidence Categories (triage output)

Category Definition Example
Observation Direct deterministic fact from the backend. No confidence field. "Section .text is executable, size 4096 bytes"
Heuristic Rule-derived interpretation with explicit confidence. "Suspicious API: VirtualAlloc (risk_score: 8, confidence: HIGH)"
Unknown Explicit unresolved question at a specific address. "Indirect call target at 0x402080 could not be resolved"

Confidence Levels

Level Meaning When to cite
HIGH Backend is certain about this result Cite as fact
MEDIUM Backend has reasonable confidence Cite with qualification ("likely")
LOW Backend made a best-guess Cite only with explicit caveat
UNKNOWN Backend could not determine Present as an open question

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.

Reference When to Load
references/installation.md Setting up Ghidra, Java, or PyGhidra. Running binary doctor or binary bootstrap. Dependency troubleshooting.
references/cli-reference.md Need the complete command reference with flags, exit codes, and examples. Unfamiliar with a specific command or flag.
references/triage-workflow.md Performing a triage on an unknown binary. Need the step-by-step triage methodology and interpretation guide.
references/function-analysis.md Decompiling, disassembling, or tracing a function. Understanding decompiler output or call-graph analysis.
references/binary-formats.md Identifying or interpreting PE, ELF, or Mach-O format characteristics. Understanding section flags, entry point conventions, or format-specific quirks.
references/security.md Interpreting suspicious-API results, capability maps, or security rule matches. Understanding risk scoring and rule priorities.
references/evidence-and-confidence.md Writing reports that distinguish CLI evidence from agent inferences. Building an evidence-backed argument.
references/packed-and-obfuscated.md Suspicious that a binary is packed, compressed, or obfuscated. High entropy sections, missing imports, or small import tables.
references/firmware.md Analyzing firmware images. Need firmware-specific load address conventions, filesystem extraction patterns, or boot-loader analysis.
references/troubleshooting.md CLI returns unexpected errors, timeouts, or partial results. Ghidra fails to start. Project state is stuck.
references/reporting.md Generating reports with binary export-report. Choosing report types and formats. Interpreting report structure.

Reporting Expectations

Every analysis session must produce at least one of these outputs before the agent considers the task complete:

  1. Triage report — for unknown binaries. Covers observations, heuristics, unknowns, and an agent assessment section clearly separated from CLI evidence.
  2. Focused analysis — for targeted questions about a specific function, import, or behavior. Answers the user's question with CLI evidence first, agent interpretation second.
  3. Capability summary — for "what does this binary do" questions. Maps functional areas with evidence sources and confidence levels.

Reports must:

  • Separate CLI evidence (deterministic) from agent assessment (interpretation).
  • Cite confidence levels for every heuristic claim.
  • Include provenance: project ID, binary SHA-256, adapter and backend versions.
  • Note partial results, timeouts, or diagnostic warnings — do not hide limitations.

Verification Matrix

Before presenting results to the user, verify:

Check How
CLI commands all returned success: true or documented partial: true Check success and partial in each response envelope
No diagnostic warnings were silently ignored Review diagnostics array in every response
Evidence citations are traceable to CLI output Every factual claim matches a field in a data block
Agent inferences are explicitly labeled Search your output for unqualified claims
Project state is clean Run binary project status --project <name> --json
Report was generated and reviewed Report file exists in project reports/ directory

Exit Criteria

Stop and report results when:

  • A triage report has been generated and the user's question is answered with evidence-backed findings.
  • A focused analysis has produced the specific information requested (decompiled function, call path, import list) with provenance.
  • Three non-converging diagnostic passes have been attempted for the same issue. Report the evidence gathered and the blocker.
  • The binary format is unsupported (exit code 5). Report the format limitation.
  • A hard dependency is missing and the user declines to install it. Report the gap.

Do not stop after a single structural query unless it fully answers the user's question. Static analysis is iterative — broad survey, then deep-dive.

Files (agent-skills)
  • evals
    • evals.json 7.4 KB
      Loading…
  • references
    • binary-formats.md 14.9 KB
      Loading…
    • cli-reference.md 20.4 KB
      Loading…
    • evidence-and-confidence.md 10.8 KB
      Loading…
    • firmware.md 10.1 KB
      Loading…
    • function-analysis.md 14.1 KB
      Loading…
    • installation.md 9.9 KB
      Loading…
    • packed-and-obfuscated.md 11 KB
      Loading…
    • reporting.md 10.6 KB
      Loading…
    • security.md 12.3 KB
      Loading…
    • triage-workflow.md 12.8 KB
      Loading…
    • troubleshooting.md 11.3 KB
      Loading…
  • scripts
    • binary_analysis
      • adapters
        • ghidra
          • adapter.py 13.8 KB
            Loading…
          • bridge.py 8.7 KB
            Loading…
          • __init__.py 550 B
            Loading…
        • base.py 20.9 KB
          Loading…
        • fake.py 62.1 KB
          Loading…
        • runtime.py 718 B
          Loading…
        • __init__.py 1000 B
          Loading…
      • bootstrap
        • deps.py 10.8 KB
          Loading…
        • __init__.py 249 B
          Loading…
      • cli
        • binary_ops.py 36.2 KB
          Loading…
        • bootstrap.py 12.7 KB
          Loading…
        • doctor.py 2.8 KB
          Loading…
        • functions.py 32 KB
          Loading…
        • helpers.py 7.9 KB
          Loading…
        • main.py 26.9 KB
          Loading…
        • project.py 25 KB
          Loading…
        • references.py 23.2 KB
          Loading…
        • reporting.py 13.1 KB
          Loading…
        • search.py 18.2 KB
          Loading…
        • security.py 30.2 KB
          Loading…
        • structural.py 27.8 KB
          Loading…
        • version.py 1.4 KB
          Loading…
        • worker.py 8.6 KB
          Loading…
        • __init__.py 528 B
          Loading…
      • domain
        • entities.py 10.4 KB
          Loading…
        • enums.py 2.5 KB
          Loading…
        • errors.py 6.3 KB
          Loading…
        • schemas.py 10.9 KB
          Loading…
        • selectors.py 8.4 KB
          Loading…
        • __init__.py 2.8 KB
          Loading…
      • projects
        • atomic.py 4.4 KB
          Loading…
        • cache.py 6.1 KB
          Loading…
        • diagnostics.py 4.5 KB
          Loading…
        • lock.py 8 KB
          Loading…
        • manifest.py 5.9 KB
          Loading…
        • path_security.py 8.5 KB
          Loading…
        • state_machine.py 5.5 KB
          Loading…
        • workspace.py 6.5 KB
          Loading…
        • __init__.py 2.4 KB
          Loading…
      • reporting
        • audit.py 4.8 KB
          Loading…
        • generator.py 36.1 KB
          Loading…
        • __init__.py 1.1 KB
          Loading…
      • rules
        • capabilities.py 27.4 KB
          Loading…
        • engine.py 33.2 KB
          Loading…
        • suspicious_apis.py 16.7 KB
          Loading…
        • __init__.py 788 B
          Loading…
      • worker
        • client.py 6.1 KB
          Loading…
        • resolver.py 1.9 KB
          Loading…
        • server.py 9.4 KB
          Loading…
        • __init__.py 793 B
          Loading…
      • __init__.py 130 B
        Loading…
    • binary 489 B · in bundle
    • test_runtime_backend.py 9.6 KB
      Loading…
  • tests
    • contract
      • test_json_contracts.py 28.7 KB
        Loading…
      • __init__.py 190 B
        Loading…
    • golden
      • __init__.py 190 B
        Loading…
    • integration
      • test_cross_area.py 27.7 KB
        Loading…
      • __init__.py 190 B
        Loading…
    • security
      • __init__.py 190 B
        Loading…
    • unit
      • test_atomic.py 10 KB
        Loading…
      • test_binary_ops.py 29.5 KB
        Loading…
      • test_bootstrap.py 10.2 KB
        Loading…
      • test_cache.py 10.2 KB
        Loading…
      • test_cli.py 12 KB
        Loading…
      • test_doctor.py 10 KB
        Loading…
      • test_entities.py 11 KB
        Loading…
      • test_enums.py 6.5 KB
        Loading…
      • test_envelope.py 7.2 KB
        Loading…
      • test_errors.py 8.1 KB
        Loading…
      • test_fake_adapter.py 42.1 KB
        Loading…
      • test_functions.py 49.6 KB
        Loading…
      • test_ghidra_adapter.py 23.4 KB
        Loading…
      • test_lock.py 9.6 KB
        Loading…
      • test_manifest.py 12.6 KB
        Loading…
      • test_project_lifecycle.py 35.5 KB
        Loading…
      • test_references.py 26.7 KB
        Loading…
      • test_regressions.py 9.1 KB
        Loading…
      • test_reporting.py 37.4 KB
        Loading…
      • test_safety_hardening.py 41.4 KB
        Loading…
      • test_schemas.py 11.1 KB
        Loading…
      • test_search.py 19.7 KB
        Loading…
      • test_security.py 58 KB
        Loading…
      • test_selectors.py 7.2 KB
        Loading…
      • test_structural.py 30.6 KB
        Loading…
      • test_version.py 6.3 KB
        Loading…
      • test_worker.py 29.4 KB
        Loading…
      • test_workspace.py 11.1 KB
        Loading…
      • __init__.py 190 B
        Loading…
    • conftest.py 1.3 KB
      Loading…
    • __init__.py 184 B
      Loading…
  • .coveragerc 317 B · in bundle
  • README.md 4.8 KB
    # Binary Analysis — Agent Skill
    
    Plan static binary investigations and inspect toolchain readiness; live backend operations are not yet implemented.
    
    ## 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.
    
    **Current limitation:** live Ghidra import, analysis, queries, and reports are
    not implemented. These commands fail explicitly instead of returning canned
    fixtures. Project administration and dependency diagnostics work. The workflow
    and reference material describe the intended analysis interface; installation
    alone does not enable it. Existing fixture-derived reports are not evidence
    about your file.
    
    ## 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. Understand the current limit
    
    ```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 import command currently exits nonzero with “Ghidra backend operations are
    not implemented in this release.” Stop there; the subsequent commands show the
    intended interface and do not produce live analysis. No fixture mode is exposed.
    
    ## 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.
    
  • SKILL.md 15.7 KB
    ---
    name: binary-analysis
    description: >-
      Plan static inspection of unknown binary files with a deterministic CLI whose
      Ghidra operations are currently unimplemented and fail closed. Use when you need to inspect a PE, ELF, or Mach-O
      file — triage suspicious binaries, map imported APIs, decompile functions,
      trace call paths, or produce structured evidence reports. Do not use for
      runtime analysis (debugging, dynamic tracing, sandbox execution), for
      modifying or patching binaries, or for binaries you already know everything
      about. The skill owns planning, hypothesis formation, and evidence synthesis;
      the CLI owns all deterministic operations.
    license: MIT
    compatibility: Requires Python 3.12+, Java JDK 21+, Ghidra 12.1+, PyGhidra 3.1+
    metadata:
      tags: binary-analysis, reverse-engineering, security, malware-analysis, static-analysis, ghidra
      skill_version: "1.0.0"
      cli_entrypoint: scripts/binary
      required_skill: none
      uses: scripts/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.
    
    | Layer | Responsibility | Must NOT |
    |-------|---------------|----------|
    | **Agent (you)** | Form hypotheses about binary behavior. Choose which analyses to run and in what order. Synthesize CLI evidence into conclusions. Explain findings to the user in plain language. Write evidence-backed reports. | Invent facts not present in CLI output. Claim certainty where the CLI reports partial results or low confidence. Skip diagnostic warnings. |
    | **CLI** | Parse arguments, manage project lifecycle, run Ghidra analysis, serialize canonical entities, emit JSON envelopes, enforce safety limits. | Interpret results, draw conclusions, or produce narrative prose. |
    
    **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
    
    ```bash
    binary doctor --json
    ```
    
    If any component reports `severity: "ERROR"`, run the bootstrap plan:
    
    ```bash
    binary bootstrap --plan --json
    ```
    
    Review the plan. If the user authorizes installation, run:
    
    ```bash
    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.
    
    ```bash
    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.
    
    ```bash
    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):**
    ```bash
    binary triage --project <project-name> --json
    binary suspicious-apis --project <project-name> --json
    binary capability-map --project <project-name> --json
    ```
    
    **For structural understanding:**
    ```bash
    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:**
    ```bash
    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:**
    ```bash
    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:
    
    ```bash
    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.
    
    | Boundary | Enforcement | Why |
    |----------|-------------|-----|
    | **Never execute the target** | CLI refuses; no execution path exists | Static analysis only |
    | **Never load target as a library** | Not implemented; no dlopen/LoadLibrary path | Prevents unintended code execution |
    | **Never expose a network listener** | No HTTP, MCP, or socket servers | The CLI is a local tool |
    | **Never upload hashes or samples** | No telemetry, no outbound calls | Privacy and security |
    | **Path containment** | All project paths validated for traversal | Prevents workspace escape |
    | **Output size limits** | Default 64 MB, max 256 MB JSON | Prevents context exhaustion |
    | **Memory limits** | Configurable per-operation ceiling | Prevents OOM during large analyses |
    | **Timeout enforcement** | Default 300s, configurable per-command | Bounded operations |
    | **Result count limits** | Paginated with default 100, max 1000 | Prevents unbounded output |
    | **Graph depth limits** | Callgraph capped at depth 10 | Prevents infinite recursion |
    
    ## Evidence Standards
    
    All CLI evidence follows a confidence hierarchy. Use these standards when
    citing evidence in reports or explanations.
    
    ### Evidence Categories (triage output)
    
    | Category | Definition | Example |
    |----------|-----------|---------|
    | **Observation** | Direct deterministic fact from the backend. No `confidence` field. | "Section .text is executable, size 4096 bytes" |
    | **Heuristic** | Rule-derived interpretation with explicit `confidence`. | "Suspicious API: VirtualAlloc (risk_score: 8, confidence: HIGH)" |
    | **Unknown** | Explicit unresolved question at a specific address. | "Indirect call target at 0x402080 could not be resolved" |
    
    ### Confidence Levels
    
    | Level | Meaning | When to cite |
    |-------|---------|--------------|
    | `HIGH` | Backend is certain about this result | Cite as fact |
    | `MEDIUM` | Backend has reasonable confidence | Cite with qualification ("likely") |
    | `LOW` | Backend made a best-guess | Cite only with explicit caveat |
    | `UNKNOWN` | Backend could not determine | Present as an open question |
    
    ### 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.
    
    | Reference | When to Load |
    |-----------|-------------|
    | [references/installation.md](references/installation.md) | Setting up Ghidra, Java, or PyGhidra. Running `binary doctor` or `binary bootstrap`. Dependency troubleshooting. |
    | [references/cli-reference.md](references/cli-reference.md) | Need the complete command reference with flags, exit codes, and examples. Unfamiliar with a specific command or flag. |
    | [references/triage-workflow.md](references/triage-workflow.md) | Performing a triage on an unknown binary. Need the step-by-step triage methodology and interpretation guide. |
    | [references/function-analysis.md](references/function-analysis.md) | Decompiling, disassembling, or tracing a function. Understanding decompiler output or call-graph analysis. |
    | [references/binary-formats.md](references/binary-formats.md) | Identifying or interpreting PE, ELF, or Mach-O format characteristics. Understanding section flags, entry point conventions, or format-specific quirks. |
    | [references/security.md](references/security.md) | Interpreting suspicious-API results, capability maps, or security rule matches. Understanding risk scoring and rule priorities. |
    | [references/evidence-and-confidence.md](references/evidence-and-confidence.md) | Writing reports that distinguish CLI evidence from agent inferences. Building an evidence-backed argument. |
    | [references/packed-and-obfuscated.md](references/packed-and-obfuscated.md) | Suspicious that a binary is packed, compressed, or obfuscated. High entropy sections, missing imports, or small import tables. |
    | [references/firmware.md](references/firmware.md) | Analyzing firmware images. Need firmware-specific load address conventions, filesystem extraction patterns, or boot-loader analysis. |
    | [references/troubleshooting.md](references/troubleshooting.md) | CLI returns unexpected errors, timeouts, or partial results. Ghidra fails to start. Project state is stuck. |
    | [references/reporting.md](references/reporting.md) | Generating reports with `binary export-report`. Choosing report types and formats. Interpreting report structure. |
    
    ## Reporting Expectations
    
    Every analysis session must produce at least one of these outputs before the
    agent considers the task complete:
    
    1. **Triage report** — for unknown binaries. Covers observations, heuristics,
       unknowns, and an agent assessment section clearly separated from CLI
       evidence.
    2. **Focused analysis** — for targeted questions about a specific function,
       import, or behavior. Answers the user's question with CLI evidence first,
       agent interpretation second.
    3. **Capability summary** — for "what does this binary do" questions. Maps
       functional areas with evidence sources and confidence levels.
    
    Reports must:
    - Separate CLI evidence (deterministic) from agent assessment (interpretation).
    - Cite confidence levels for every heuristic claim.
    - Include provenance: project ID, binary SHA-256, adapter and backend versions.
    - Note partial results, timeouts, or diagnostic warnings — do not hide
      limitations.
    
    ## Verification Matrix
    
    Before presenting results to the user, verify:
    
    | Check | How |
    |-------|-----|
    | CLI commands all returned `success: true` or documented `partial: true` | Check `success` and `partial` in each response envelope |
    | No diagnostic warnings were silently ignored | Review `diagnostics` array in every response |
    | Evidence citations are traceable to CLI output | Every factual claim matches a field in a `data` block |
    | Agent inferences are explicitly labeled | Search your output for unqualified claims |
    | Project state is clean | Run `binary project status --project <name> --json` |
    | Report was generated and reviewed | Report file exists in project `reports/` directory |
    
    ## Exit Criteria
    
    Stop and report results when:
    
    - A triage report has been generated and the user's question is answered with
      evidence-backed findings.
    - A focused analysis has produced the specific information requested (decompiled
      function, call path, import list) with provenance.
    - Three non-converging diagnostic passes have been attempted for the same issue.
      Report the evidence gathered and the blocker.
    - The binary format is unsupported (exit code 5). Report the format limitation.
    - A hard dependency is missing and the user declines to install it. Report the
      gap.
    
    Do not stop after a single structural query unless it fully answers the user's
    question. Static analysis is iterative — broad survey, then deep-dive.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.