Rogue Binary

Import and cache

Ghidra import is cache-backed by SHA-256. Most read tools use analyzeHeadless -process <name> -noanalysis, so import and analysis happen once per binary.

ghidra_check confirms availability.
ghidra_import imports the binary.
ghidra_project_binaries, ghidra_binary_metadata, and ghidra_delete_binary manage cached projects.

Tool	Starts JVM?	Use when	Output
`ghidra_check`	No	Checking setup.	Install dir, launcher path, version, structured errors.
`ghidra_import`	Yes	Preparing a binary for warm-path queries.	Status, cache key, project dir, ETA.
`ghidra_project_binaries`	No	Listing cached binaries.	Cached program metadata.
`ghidra_binary_metadata`	No	Resolving a program name or SHA.	Single cached binary envelope.
`ghidra_delete_binary`	No	Cleaning a stale cache entry.	Deleted flag and cache metadata.

Import normal PE

{
  "tool": "ghidra_import",
  "arguments": {
    "binary_path": "/samples/payload.exe"
  }
}

Import raw staged blob

{
  "tool": "ghidra_import",
  "arguments": {
    "binary_path": "/samples/stage.bin",
    "loader": "BinaryLoader",
    "processor": "x86:LE:32:default",
    "cspec": "windows",
    "loader_base_addr": "0x0"
  }
}

Decompiler path

For large targets, use inventory and call projections before asking for broader decompiler output.

ghidra_inventory with mode=functions
ghidra_xrefs, ghidra_search_bytes, and ghidra_read_bytes for addressable proof.
ghidra_decompile_meta when token and variable metadata matters more than full pseudocode.
ghidra_decompiler_calls
ghidra_callsite_facts when pseudocode may be misleading.
ghidra_decompiler_block_behavior or ghidra_decompiler_memory after narrowing the question.

Tool	Use when	Key params	Next step
`ghidra_inventory`	You need functions, symbols, strings, memory map, or bookmarks.	`mode`, `query`, `offset`, `limit`.	`ghidra_decompiler_calls`.
`ghidra_xrefs`	You need references to or from a symbol or address.	`name_or_address`, `direction`, `offset`, `limit`.	`ghidra_callsite_facts` on an exact caller.
`ghidra_search_bytes`	You need mapped-memory byte hits, not raw file offsets.	`hex_pattern`, `max_hits`.	`ghidra_read_bytes` or containing-function review.
`ghidra_read_bytes`	You need bytes at a Ghidra memory address.	`address`, `size`.	Use as exact byte proof for a claim.
`ghidra_decompile_meta`	Pseudocode text is too lossy.	`name_or_address`, `simplification_style`, `token_limit`.	`ghidra_callsite_facts` or variable review.
`ghidra_decompiler_calls`	You need external, indirect, thunk, or API-heavy calls.	`name_or_address`, `only_external`, `only_api_tag`.	`ghidra_callsite_facts`.
`ghidra_callsite_facts`	One exact callsite matters.	`call_address`, optional containing function.	Use as canonical argument evidence.
`ghidra_decompiler_divergence`	Pseudocode may hide or normalize arguments.	`name_or_address`.	Follow emitted `ghidra_callsite_facts` calls.
`ghidra_function_dossier`	You need a compact function overview.	`name_or_address`.	Use suggested next tool calls.

External calls only

{
  "tool": "ghidra_decompiler_calls",
  "arguments": {
    "binary_name": "payload.exe",
    "name_or_address": "0x401000",
    "only_external": true
  }
}

Exact callsite facts

{
  "tool": "ghidra_callsite_facts",
  "arguments": {
    "binary_name": "payload.exe",
    "call_address": "0x4012a4",
    "name_or_address": "0x401000"
  }
}

Inventory modes

ghidra_inventory is the cheap cached index view. Pick the mode that matches the question before opening a function.

functions, symbols, imports, and exports find named code and linkage facts.
strings, defined_data, namespaces, memory_map, data_types, equates, and bookmarks cover the common non-code pivots.
Use query, offset, and limit where the mode supports filtering or pagination.

Mode	Use when	Returns	Next step
`functions`	Choosing a function target.	Function names, addresses, and sizes.	`ghidra_function_dossier` or `ghidra_decompiler_calls`.
`symbols`	A name fragment or namespace matters.	Symbol matches with addresses and symbol metadata.	`ghidra_xrefs`.
`imports` or `exports`	Linkage is the pivot.	Imported and exported names.	`ghidra_decompiler_calls` or `dll_export_profile`.
`strings` or `defined_data`	Literals or data objects drive the analysis.	String/data rows with addresses.	`ghidra_xrefs` or `ghidra_read_bytes`.
`memory_map`	You need mapped address ranges.	Blocks, permissions, and address ranges.	`ghidra_search_bytes` or `ghidra_read_bytes`.
`data_types`, `equates`, or `bookmarks`	Types, constants, or saved findings matter.	Cached project metadata.	`ghidra_variables` or exact evidence tools.

Exact evidence

The Ghidra tools include listing-grounded callsite facts, CFGs, P-code, byte reads, xrefs, variable views, path digests, and persistent project edits.

ghidra_decompile, ghidra_decompile_meta, ghidra_disassemble, ghidra_pcode, ghidra_cfg, and ghidra_decompiler_cfg.
ghidra_callsite_slices, ghidra_function_checkpoints, ghidra_function_dossier, ghidra_variables, ghidra_thunk_target, and ghidra_xrefs.
ghidra_field_flow, ghidra_field_lineage, ghidra_jump_table_field_summary, ghidra_context_api_slots, and ghidra_indirect_jump_slices for state, context, and dispatch work.
ghidra_rename_function, ghidra_set_function_prototype, ghidra_set_bookmark, ghidra_set_comment, ghidra_create_label, and ghidra_create_function.

Situation	Use	Why	Avoid first
Decompiler CFG invalid or timed out	`ghidra_cfg`.	Listing-level BasicBlockModel is separate from decompiler CFG.	`ghidra_decompile`.
Need P-code facts	`ghidra_pcode`.	Structured ops, varnodes, and decompiler status.	Raw pseudocode.
Need stack args around calls	`ghidra_callsite_slices`.	Nearby setup, recovered stack args, return consumers.	Manual instruction windows.
Need local decoded buffers	`ghidra_local_buffer_slices`.	Groups immediate memory writes into recovered byte previews.	Writing a one-off extractor too early.
Need first consumers of a struct field	`ghidra_field_lineage`.	Tracks root-pointer loads, copied field values, calls, and destination structs.	`ghidra_field_flow` when register reuse is noisy.
Need table target field usage	`ghidra_jump_table_field_summary`.	Field reads/writes and call arguments across computed table targets.	Opening each target manually.
Need context-table API slots	`ghidra_context_api_slots`.	Context offsets, module slots, API slots, indirect calls, and export hashes.	Manually stitching resolver output to stack slots.
Need state-machine path	`ghidra_path_digest`.	Flow blocks, calls, computed jumps, fields, buffers, constants.	Paging through the whole function.