Ghidrust provides a hyper fast, AI native reverse engineering platform built in Rust, inspired by Ghidra. Includes experimental GPU kernels to rapidly decompile large files, a decryption suite, and network monitor for packet to binary reverse engineering.
| Name | Last commit message | Last commit date |
|---|---|---|
| .github | ||
| crates | ||
| docs | ||
| fixtures | ||
| rules | ||
| scripts | ||
| skill | ||
| .gitignore 630 B | ||
| Cargo.lock 118 KB | ||
| Cargo.toml 1.9 KB | ||
| LICENSE 11.1 KB | ||
| README.md 61.0 KB |
Ghidrust
Rust reverse-engineering toolkit inspired by Ghidra.
Ghidrust loads PE/ELF (and raw blobs), produces Capstone-class multi-arch listings (23 ISAs; x86-64 primary analyze/decompile pipeline), runs Auto Analysis, decompiles to pseudo-C, parses IL2CPP metadata / Unity install inventory, and saves durable projects — from a CLI, an MCP server for agents, or an egui CodeBrowser-style GUI.
Ghidnet (native network plane) attributes host sockets and capture flows to processes/images, runs in-tree GNR / Proofpoint ET Open detection (IDS-class alert/pass/drop records — not kernel IPS), and digs into the offending binary with the same RE stack.
It is not a Ghidra fork or wrapper. Analysis logic (loaders, decode, analyzers, decompile, Ghidnet) is written in-tree so the core stays small, auditable, and freestanding.
Includes custom GPU kernels to conduct decompiling at lightning speed, this feature is experimental and in development.
What it aims to achieve
| Goal | Meaning in practice |
|---|---|
| Surpass Ghidra (measurable) | On x86-64 PE/ELF: faster Auto Analysis + decompile-all wall clock than Ghidra headless on the same machine/binary; ≥ Ghidra F1 on function discovery; structured typed C with expression folding (not mnemonic scaffolding); differential correctness vs Ghidra on a fixed corpus — target, not a claim of today’s quality. Human rubric: docs/READABILITY_RUBRIC.md. Hex-Rays-class display is the ceiling after the Ghidra bar. |
| Ghidra-shaped workflow | Familiar labels and surfaces (Auto Analysis names, project import/analyze/export, listing + click FUN → decompile) without depending on the Ghidra JVM stack |
| Custom core | PE/ELF, Capstone-class multi-arch decode (ghidrust-decode), x86-64 RTTI/analyzers, and the IR → SSA → structure → typed-C pipeline implemented in Rust — third-party RE libraries are avoided at runtime; Ghidra sources are reference-only |
| CPU-correct first | CPU paths are the oracle; optional GPU paths must match or enrich them, not replace honesty with speed claims |
| Agent-ready | Headless CLI + stdio MCP with artifact spill/drain, program identity (path or project+file_id), PE install inventory, RTTI catalog query, UTF-16 xref support, function create / bounded disasm / call graphs, IL2CPP touch-map + body proof, live process bridge (Windows), Ghidnet (net_*, tool_surface ≥ 8), and egui panes for every surface. 2026-07-19: Windows agent disasm pipeline + bounds honesty (--brief/--pretty, bounds_suspect, listing_text) — see CHANGELOG.md |
| Practical projects | Create a workspace, import binaries, run analyzers, persist results (analysis.bin), reopen later |
| Ghidnet (native) | Process-attributed sockets/flows → GNR/ET Open IDS alerts → dig into image (load/analyze/decompile / live process). In-tree only — see Ghidnet |
Experimental GPU feature
Ghidrust includes an experimental GPU path (wgpu / Vulkan) for two roles:
- Bulk RE — parallel printable / pattern / RTTI-style scans where SIMT helps
- GPU-resident decompile — multipass decompile kernels that keep mid-pipeline IR in VRAM (upload code once → device passes → download a
.gdecompdump)
Enabled by default on the CLI / decomp crates via the gpu feature. Without a Vulkan adapter, those paths fall back or report unavailability; CPU decompile and analysis still work.
Honest performance note: on small fixtures, GPU decompile is often correct but slower wall-clock than CPU because of adapter init and PCIe transfer — residency mid-pipeline is the research win, not automatic speedups. Details: docs/GPU_DECOMPILER_RESEARCH.md, docs/GPU_DECOMPILE_PROCESS.md, docs/GPU_ANALYZER_MATRIX.md.
Build
Requirements: Rust stable (edition 2021), Windows / Linux / macOS. GPU features need a Vulkan-capable GPU when you use the default gpu build.
# Clone and enter the repo, then:
# Debug (fast compile)
cargo build --workspace
# Release (recommended for GUI and large binaries)
cargo build --workspace --release
Binaries:
| Binary | Path (after release build) |
|---|---|
| CLI (+ MCP) | target/release/ghidrust (.exe on Windows) |
| GUI | target/release/ghidrust-gui |
| Ghidnet capture helper | target/release/ghidrust-netcap |
# CLI only
cargo build -p ghidrust-cli --release
# GUI only
cargo build -p ghidrust-gui --release
# Ghidnet capture helper
cargo build -p ghidrust-net-capture --release --bin ghidrust-netcap
# Explicit GPU decomp + core bulk features
cargo build -p ghidrust-cli --release --features ghidrust-core/gpu
| Feature | Where | Purpose |
|---|---|---|
gpu (default on decomp / CLI) |
ghidrust-decomp |
GPU-resident decompile + related kernels |
gpu |
ghidrust-core |
Bulk string / pattern GPU path |
# Run the test suite
cargo test --workspace
cargo test -p ghidrust-decomp
Quick start
# Help
cargo run -p ghidrust-cli --release -- help
# or: ./target/release/ghidrust help
# Load / disassemble fixtures (Capstone-class engine; bounded by function end by default)
./target/release/ghidrust load fixtures/tiny_x64.pe
./target/release/ghidrust disasm fixtures/tiny_x64.pe --count 16
./target/release/ghidrust decode-support --json
./target/release/ghidrust decode-query --query insn_name --arch x86 --id 1 --json
./target/release/ghidrust disasm fixtures/tiny_x64.pe --addr 0x140001000 --count 32 --detail --syntax intel --json
# Lookups (no helper scripts required)
./target/release/ghidrust strings fixtures/analysis_lab.pe --encoding all --filter WideLab --json
./target/release/ghidrust xrefs fixtures/analysis_lab.pe --string ExitProcess --json
./target/release/ghidrust imports fixtures/analysis_lab.pe --json
./target/release/ghidrust function-at fixtures/analysis_lab.pe --addr 0x140001004 --json
# Auto Analysis
./target/release/ghidrust analyzers
./target/release/ghidrust analyze fixtures/analysis_lab.pe --analyzers "Function ID,Stack" --json
# CPU (Stage-1 default) vs experimental GPU decompile
./target/release/ghidrust decompile fixtures/tiny_x64.pe
./target/release/ghidrust gpu-decompile fixtures/tiny_x64.pe --out entry.gdecomp --metrics metrics.log --json
# GUI
cargo run -p ghidrust-gui --release
Windows PowerShell: use .\target\release\ghidrust.exe and .\target\release\ghidrust-gui.exe. --json stdout is UTF-8 without BOM (safe for ConvertFrom-Json).
Fixtures live under fixtures/ (tiny_x64.pe, analysis_lab.pe, tiny_x64.elf, plus decode_continuity.bin for disasm --skip-bad tests). They are committed test corpus — keep them in git; put large private samples under gitignored dev/.
Capabilities
Every row below is exercised end-to-end (CLI + oracle) by
crates/ghidrust-cli/tests/eval_analysis_decompile.rs;
the report lands in dev/EVAL_ANALYSIS_DECOMPILE_REPORT.md
and machine-readable form at dev/eval_analysis_decompile.json. Rerun with:
cargo test -p ghidrust-cli --test eval_analysis_decompile -- --nocapture
Analyzer names are the exact strings from ghidrust analyzers and from the
Auto Analysis screenshot Ghidra ships with. Outputs are honest: no fabricated
symbols, no Hex-Rays / Ghidra C mimicry — you get structured JSON fields plus
one human-readable status line per analyzer.
Auto Analysis (21)
Common invocation shapes:
ghidrust analyze <path> --analyzer "<NAME>" --json
ghidrust analyze <path> --analyzers "<NAME_A>,<NAME_B>" --gpu --json
The columns below reference fields on AnalyzerOutput (per-analyzer entry
inside analysis.results[*] in --json output).
| # | Name (exact) | What it does | --json output fields |
Human message |
|---|---|---|---|---|
| 1 | ASCII Strings |
Bulk scan of executable + data blocks for ≥4-char printable ASCII runs using the preferred bulk backend (Sequential / ParallelCpu / GpuOrFallback). | strings: [{va, value, length, encoding: "ascii"}] |
found N ASCII string(s) [BulkScanMode…] |
| 2 | Unicode Strings |
UTF-16LE printable runs across mapped blocks (even-aligned, NUL-terminated, mostly-ASCII wide strings). Also available via ghidrust strings --encoding utf16. |
strings: [{va, value, length, encoding: "utf16le"}] |
found N UTF-16LE string(s) |
| 3 | Aggressive Instruction Finder |
Fills real code gaps (bytes not covered by any known function): validates a decodable prologue-shaped run, adds new FunctionInfo and a DiscoveredRange. Never fabricates when there is no gap. |
recovered_ranges: [{start, end}] (+ new entries in functions) |
found N recovered code range(s) |
| 4 | Call Convention ID |
Tags every discovered function with a calling-convention heuristic (Win64 x64 default, cdecl / stdcall / thiscall fallbacks). | conventions: [[va, name], …] (+ functions[*].calling_convention) |
identified N calling convention(s) |
| 5 | Call-Fixup Installer |
Detects Windows security cookie / import-thunk stubs and records a fixup entry with the stub VA. | call_fixups: [{fixup_name, call_va}] |
installed N call fixup(s) |
| 6 | Create Address Tables |
Recovers jump/vtable-style contiguous VA tables inside .rdata/data and lists their entries. |
address_tables: [{base, count, entries: [va,…]}] |
found N address table(s) |
| 7 | Decompiler Parameter ID |
Scans each function for arg-register spills (mov [rbp+…], rcx/rdx/…) and attaches typed arg0:rcx / arg1:rdx slots — no invented parameters on bare bodies. |
functions: [{entry, parameters: ["arg0:rcx", …]}] |
recovered parameters for N function(s) |
| 8 | Decompiler Switch Analysis |
Turns jump-table address tables into switch structures with (case_value, target_va) pairs. |
switches: [{jump_va, cases: [[val, target], …]}] |
recovered N switch table(s) |
| 9 | Demangler Microsoft |
Parses PE symbols in the MSVC (?...@@) mangling scheme, records demangled name alongside the raw symbol. |
symbols: [{name, va, demangled?}] |
demangled N symbol(s) |
| 10 | Embedded Media |
Scans data for well-known magic prefixes (PNG, JPG, GIF, WAV, …) and records their VA + kind. | media: [{kind, va}] |
found N media signature(s) |
| 11 | Function ID |
Hashes each function's prologue window and matches it against the shipped FID catalog (fid_* names). |
fid_matches: [{entry, matched_name}] |
matched N FID signature(s) |
| 12 | Function Start Search |
Seeds functions from entry, symbol table, exact 55 48 89 e5 prologues, and orphan sub rsp, imm8 starts. Grows each body (skips small decode holes) until ret. Drops mid-body seeds. Prefer ghidrust function-at to map a VA → containing function. |
functions: [{entry, end, name}] |
identified N function start(s) |
| 13 | Non-Returning Functions - Discovered |
Marks functions ending in int3 without a ret, plus known no-return imports (ExitProcess, abort, …). |
noreturn_entries: [va, …] (+ functions[*].noreturn) |
marked N noreturn function(s) |
| 14 | PDB MSDIA |
Portable PDB (MSF7) reader tuned to the MSDIA symbol shapes (S_PUB32, S_GPROC32 names). |
symbols: [{name, va}] |
parsed N PDB symbol(s) (msdia→universal) |
| 15 | PDB Universal |
Same MSF7 reader without MSDIA-specific filtering — surfaces every stream symbol it can find (MSF7 marker included as a sentinel symbol). |
symbols: [{name, va}] |
parsed N PDB symbol(s) (universal) |
| 16 | Shared Return Calls |
Finds sites where multiple callers reuse the same epilogue block (tail-call / shared-return pattern). | shared_returns: [va, …] |
marked N shared return site(s) |
| 17 | Stack |
Per-function frame recovery: reads sub rsp, imm / push rbp; mov rbp, rsp to compute frame_size=0x…, then attaches param_… slots. Won't pollute functions that have no real frame. |
stack_frames: [[va, ["frame_size=0x20", "param_rcx@0x8", …]], …] |
recovered N stack frame(s) |
| 18 | Variadic Function Signature Override |
Ensures API symbols matching printf / sprintf / scanf families exist, tags them varargs=true cdecl and gives them a format param. |
varargs_entries: [va, …] (+ functions[*].varargs) |
applied varargs to N function(s) |
| 19 | WindowsPE x86 PE RTTI Analyzer |
MSVC C++ RTTI recovery: locates COL / class-hierarchy / type-info descriptors, links them to vtables, extracts demangled class names. | rtti: {classes: [{name, type_info_va, vtable_va, col_va, kind}], notes: [str,…]} |
recovered N RTTI class record(s) |
| 20 | Windows x86 Propagate External Parameters |
Applies known prototypes to imported Windows APIs (ExitProcess(UINT), GetProcAddress, …) so calls resolve typed args. |
external_params: [[va, prototype], …] |
applied N external parameter prototype(s) |
| 21 | WindowsResourceReference |
Parses .rsrc and records resource records (VERSION, RT_ICON, …) with their VA. |
resources: [{name, va}] |
parsed N resource record(s) |
Defaults (empty --analyzer list): ASCII Strings, Unicode Strings, WindowsPE x86 PE RTTI Analyzer, Function Start Search, Create Address Tables, Embedded Media, Demangler Microsoft.
Notes:
--gpuonanalyzeruns each selected CPU analyzer, then per-analyzer GPU seed kernels; the CPU output above is unchanged, but the human message is appended withgpu_enrich hits_merged=… backend=….- Every entry above is a PASS in
dev/EVAL_ANALYSIS_DECOMPILE_REPORT.md; theanalysis_lab.pe/tiny_x64.pefixtures pin known VAs (e.g.printf@0x140002010,PNG@0x140002050,VERSION@0x140002090,WideLabStringUTF-16,WidgetRTTI class).
Lookups (CLI + MCP)
First-class commands for the queries agents used to need ad-hoc scripts for. Same capabilities are exposed as MCP tools (see MCP tools).
| Command | Purpose | Key flags |
|---|---|---|
ghidrust load <path|--project DIR --file-id ID> |
Load PE/ELF; JSON includes resolved_path, sections, informational section_notes |
--json, --out |
ghidrust strings <path> |
Scan ASCII and/or UTF-16LE strings (PE/ELF or --raw blob) |
--encoding, --filter, --match substr|token|whole|glob, --limit N, --out FILE, --raw, --json |
ghidrust xrefs <path> |
Cross-references (absolute + RIP-relative; string encoding modes); call edges | Exactly one of: --to / --from / --string / --import / --calls; --encoding ascii|utf16le|all; --skip-stubs / --classify |
ghidrust imports <path> |
PE import directory → DLL + symbol + IAT VA | --dll NAME, --name NAME, --json |
ghidrust function-at <path> --addr HEX |
Containing analyzed function for a body VA (runs Function Start Search if needed); JSON includes seed_kind |
--json |
ghidrust function create <path> --addr HEX |
Create/heal a function at VA (pdata/export/FSS complements; may synthesize) | --end HEX, --json |
ghidrust decompile <path> |
Containing-fn resolve + Stage-1 pseudo-C | --addr (mid-body ok), --follow-stub, --json |
ghidrust gpu-decompile <path> |
GPU multipass at resolved entry; metrics JSON primary; .gdecomp opaque |
--addr, --metrics, --json |
ghidrust rtti <path> |
RTTI catalog (filter/exact/match; multi-vtable honest) | --filter/--name/--exact, --match, --json |
ghidrust inventory <dir> |
Generic PE install inventory (exe/dll + VERSIONINFO; artifact if large) | --max-depth, --hash, --json |
ghidrust tree <path> |
Bounded file tree index (existence/size; no unpack) | --max-depth, --ext, --name, --json |
ghidrust artifact get|query|list |
Drain spilled analysis artifacts (next_offset) |
--offset, --limit, --json |
ghidrust process list|attach|launch|…|break|wait|scan|watch |
Live Process Bridge (Windows; observe default, mode=debug for BP/step; tool_surface ≥ 7) |
session_id / -mode / --args / --cwd / --addr / --module / --rva |
ghidrust net dig|playbook|connections|owners|ifaces|capture|flows|detect|alerts|rules|pivots |
Ghidnet — attribute sockets/flows, ET Open / GNR detect, dig into image (tool_surface ≥ 8) |
See Ghidnet; ghidrust net help |
ghidrust il2cpp meta|map|touch-map|stubs|icalls |
IL2CPP metadata + touch-map + method map (body proof / baseline) + stubs + icalls | See docs/IL2CPP.md |
ghidrust unity-inventory <dir> |
Unity player layout (reuses PE VERSIONINFO helpers) | --json, --out FILE |
ghidrust disasm <path> |
Capstone-class listing; bounded by function end by default; decode_gaps when --skip-bad; JSON stop_reason |
--addr HEX, --count N (default 16), --skip-bad, --linear/--flow, --arch, --mode, --syntax, --detail/--no-detail, --detail-real, --skipdata, --skipdata-mnemonic, --skipdata-size, --unsigned-imm, --only-offset-branch, --litbase, --mnem-override ID:MNEMONIC, --out, --json |
ghidrust decode-support |
Engine version, 23 supported arches, options, syntax values, compile features | --json |
ghidrust decode-query |
Engine introspection (insn_name, reg_name, group_name, insn_group, reg_read, reg_write, op_count, op_index, regs_access) |
--query NAME, --arch, --mode, --id, --index, --bytes HEX, --addr HEX, --detail, --json |
# Wide + ASCII string search (token match + limit; BOM-free --out)
ghidrust strings app.exe --encoding all --filter Config --match token --limit 50 --json
ghidrust strings huge.bin --raw --filter Camera --out camera_strings.json --json
# Code sites that reference a string (RIP-relative LEA included; hide IL2CPP resolve stubs)
ghidrust xrefs app.exe --string ResolutionWidth --skip-stubs --json
# Import call-sites (IAT slot + FF15/RIP refs)
ghidrust imports app.exe --name ShellExecuteW --json
ghidrust xrefs app.exe --import ShellExecuteW --json
# Body VA → function interval (seed_kind: pdata|export|method_pointer|prologue|manual|synthesized)
ghidrust function-at app.exe --addr 0x14000d8ad --json
# Create/heal a missing function (optional end; orphan resolve may synthesize SYNTH_*)
ghidrust function create app.exe --addr 0x14000d8ad --json
# Bounded disasm (default); --linear escapes function-end clamp; JSON includes stop_reason
ghidrust disasm app.exe --addr 0x14000d890 --count 40 --skip-bad
ghidrust disasm app.exe --addr 0x14000d890 --count 40 --linear --json
# Callee edges inside a function
ghidrust xrefs app.exe --calls 0x14000d8ad --json
# Unity / IL2CPP (see docs/IL2CPP.md)
ghidrust unity-inventory /path/to/GameDir --json
ghidrust il2cpp touch-map --meta /path/to/*_Data/il2cpp_data/Metadata/global-metadata.dat --filter Camera --json
ghidrust il2cpp meta /path/to/*_Data/il2cpp_data/Metadata/global-metadata.dat --filter Camera --json
ghidrust il2cpp map --binary /path/to/GameAssembly.dll --meta /path/to/.../global-metadata.dat --baseline prev_map.json --json
ghidrust il2cpp stubs --binary /path/to/GameAssembly.dll --json
ghidrust decompile /path/to/GameAssembly.dll --addr 0x180012345 --follow-stub
Decompile methods
| Method | CLI | What it emits | Outputs / where to see them |
|---|---|---|---|
| Stage-1 (default) | ghidrust decompile <path> [--addr HEX] [--count N] [--follow-stub] [--verbose] |
Expression-folded SSA + structure + types (--follow-stub for IL2CPP resolve thunks): nested arith temps collapsed, named import/function calls when known, this on Class::method, float seeds from SSE notes, single-field structs when base is already Ptr, early-exit return polish, emit-time tokens for GUI nav. Still: recovered prototype / local_<off> / p->field_<off> / switch / && || / break continue (lab goto_rate <0.15). Mid-body --addr resolves to containing function. Readability rubric: docs/READABILITY_RUBRIC.md. |
stdout: pseudo_c. --verbose: [name] stage=1 … fold=N tokens=N goto=… lift=…%. --json: {decompile, resolve, stage1: {loops, phis, locals, params, structs, lift_ratio, goto_rate, folded_temps, token_count, return_type, prototype, total_ops}}. |
| Stage-0 (oracle) | ghidrust decompile <path> --stage0 [--addr HEX] [--count N] [--verbose] |
CFG-driven pseudo-C: void FUN_<va>() { block_0: … goto/return; } — mnemonic-style scaffolding, no fabricated locals or types. Kept as regression oracle only. |
stdout: pseudo_c. Metrics on stderr only with --verbose. --json: full Decompile { name, blocks[], edges[], insn_count, pseudo_c }. |
| Stage-0.5 IR (oracle) | ghidrust decompile <path> --stage05 [--addr HEX] [--count N] [--verbose] |
IR-informed emit from the hand-rolled x86-64 lifter → ghidrust-ir: xor a,a → a=0, add/sub/or/and/xor/shl/shr augmented-assign, push/pop, direct call, flag-driven jcc. Falls back to Stage-0 scaffolding for uncovered ops. |
stdout: pseudo_c. Metrics on stderr only with --verbose. --json: {decompile: …, lift_coverage: {total_ops, unimplemented_ops, source_instructions, ratio}}. |
| decompile-bench | ghidrust decompile-bench <path> [--functions N] [--count N] [--stage1] [--parallel] [--out FILE] |
Runs default analyzers, then benches Stage-0/0.5 (default) or Stage-1 (--stage1) across every discovered function; --parallel fans out per-entry Stage-1 across a rayon thread pool. |
Text table (or JSON via --json); optional --out FILE. Report carries per-function stage0_us, stage05_us, stage1_us, stage1_goto_count, stage1_leaf_count, and per-function pseudo_c when Stage-1 is on. |
| ghidra-headtohead | ghidrust ghidra-headtohead <path> [--functions N] [--count N] [--ghidra DIR] [--captured JSON] [--out FILE] |
Fair Ghidra oracle: shared-entry intersection with Ghidra DecompInterface output, per-row Stage-1 vs Ghidra normalized-token similarity, per-entry Stage-1 wall time. Without --ghidra / --captured the report is methodology-only. |
Text or JSON; each row carries token_similarity, ghidrust_stage1_us, ghidra_wall_us. See docs/GHIDRA_HEADTOHEAD.md. |
| gpu-decompile | ghidrust gpu-decompile <path> [--addr HEX] [--out FILE] [--metrics FILE] |
Full GPU-resident VRAM multipass decompile at containing-fn resolve (mid-body addr ok): decode → leaders → blocks → emit kernels; single final download; asserts mid_pipeline_host_reads == 0 and multipass-CPU equivalence. Metrics JSON is primary; .gdecomp is opaque. |
.gdecomp binary dump at --out. stdout: pseudo-C. --json / --metrics FILE produces {resolve, resolved_entry, gpu_backend, gpu_device, gpu_ms, mid_pipeline_host_reads, kernels, dump_path, dump_bytes, gpu_ir_count, gpu_block_count, gpu_edge_count, equivalence_multipass, pseudo_c_head}. Non-zero exit if equivalence fails or a mid-pipeline host read is observed. |
| re-bench | ghidrust re-bench <path> [--out FILE] |
CPU decompile of the entry + bulk RE on a padded haystack, once on CPU (parallel) and once on GPU / fallback; asserts equal bulk hit counts. | Text report to stdout (or JSON with --json / --out). Fields: decompile_cpu {backend, ms, entry, name, blocks, edges, insns, lines, chars, pseudo_c_head}, bulk_cpu, bulk_gpu (each: mode, backend, ms, hits, haystack_bytes), plus note explaining that decompile stays on CPU. |
Two more benches are shipped and callable from the CLI even though they are not part of the analyzer/decompile eval sweep — they measure how the analyzer and RTTI GPU strategies compare against their CPU oracles:
| Method | CLI | Purpose |
|---|---|---|
analyzer-bench |
ghidrust analyzer-bench <path> [--large] [--out FILE] [--json] |
All analyzers + a GPU-decompile row: CPU wall-time vs GPU pcie_upload / device_ms / pcie_download split, with a per-analyzer equal correctness flag. |
analyzer-bench-matrix |
ghidrust analyzer-bench-matrix |
Print the static analyzer → GPU-strategy matrix (e.g. ASCII Strings → printable_run, Unicode Strings → cstr_multi, WindowsPE x86 PE RTTI Analyzer → rtti_scan). |
bulk-bench |
ghidrust bulk-bench <path> [--json] |
Sequential vs parallel-CPU vs GPU/fallback bulk-string timings on the program's own bytes + a padded haystack. |
rtti-gpu-bench |
ghidrust rtti-gpu-bench <path> [--out FILE] [--json] |
CPU recover_rtti vs GPU rtti_scan seed with pcie_upload / device_ms / pcie_download split and a plain-English performance-model note. |
Using the three surfaces
Ghidrust exposes the same analysis core three ways. Pick one (or mix them):
| Surface | Best for | Entry point |
|---|---|---|
| CLI | Scripts, CI, one-shot RE, benches | ghidrust … |
| GUI | Interactive CodeBrowser-style work | ghidrust-gui |
| MCP | AI agents / IDEs that speak Model Context Protocol | ghidrust mcp (stdio) |
Build release binaries first (cargo build --workspace --release), then use the sections below.
CLI — full usage
The CLI is the ghidrust binary from ghidrust-cli. Prefer absolute paths to binaries and project dirs when scripting.
# After release build
./target/release/ghidrust help
# Windows
.\target\release\ghidrust.exe help
Everyday commands
# Map a binary (path OR project + file_id)
ghidrust load /path/to/app.exe --json
ghidrust load --project ./MyProject --file-id <id> --json
# Install / tree inventory (no OS shell needed)
ghidrust inventory /path/to/InstallRoot --max-depth 8 --json
ghidrust tree /path/to/GameDir --ext dll,dat --name "*meta*" --json
# Listing (bounded by fn end by default; --linear escapes; optional --skip-bad)
ghidrust disasm /path/to/app.exe --count 32
ghidrust disasm /path/to/app.exe --addr 0x140001000 --count 64 --skip-bad
ghidrust disasm /path/to/app.exe --addr 0x140001000 --count 64 --linear --json
# Strings / xrefs / imports / containing function
ghidrust strings /path/to/app.exe --encoding all --filter SomeName --match token --limit 50 --json
ghidrust strings /path/to/blob.dat --raw --filter Camera --out camera.json --json
ghidrust xrefs /path/to/app.exe --string SomeName --encoding all --skip-stubs --classify --json
ghidrust xrefs /path/to/app.exe --to 0x140002010 --json
ghidrust xrefs /path/to/app.exe --calls 0x140001000 --json
ghidrust imports /path/to/app.exe --json
ghidrust xrefs /path/to/app.exe --import CreateFileW --json
ghidrust function-at /path/to/app.exe --addr 0x140001234 --json
ghidrust function create /path/to/app.exe --addr 0x140001234 --json
ghidrust rtti /path/to/app.exe --filter Widget --json
# Artifacts (drain large spilled dumps)
ghidrust artifact list --json
ghidrust artifact query <id> --offset 0 --limit 64 --json
# Live process (Windows; observe default, debug opt-in; tool_surface >= 7)
ghidrust process list --json
ghidrust process attach <pid> -mode observe
ghidrust process attach <pid> -mode debug
ghidrust process launch C:\path\to\app.exe -mode debug -break-at-entry --json
ghidrust process modules <session_id> --json
ghidrust process resolve <session_id> --module app.exe --rva 0x1234 --json
ghidrust process break set <session_id> -addr 0x7ff…
ghidrust process continue <session_id>
ghidrust process wait <session_id> -timeout 5000
ghidrust process stack <session_id> <tid>
ghidrust process scan <session_id> -aob "48 8b ?? 90"
ghidrust process watch <session_id> "app.exe+0x1234->*+0x10"
ghidrust process read <session_id> --addr 0x7ff… --size 64 --json
ghidrust process detach <session_id>
# Unity player inventory + IL2CPP touch-map / metadata / stubs / method map
ghidrust unity-inventory /path/to/GameDir --json
ghidrust il2cpp touch-map --meta /path/to/Game_Data/il2cpp_data/Metadata/global-metadata.dat --filter Camera --json
ghidrust il2cpp meta /path/to/Game_Data/il2cpp_data/Metadata/global-metadata.dat --filter Camera --json
ghidrust il2cpp map --binary /path/to/GameAssembly.dll --meta /path/to/.../global-metadata.dat --json
ghidrust il2cpp stubs --binary /path/to/GameAssembly.dll --json
ghidrust il2cpp icalls --binary /path/to/UnityPlayer.dll --filter Camera --json
# List Auto Analysis names (Ghidra-compatible labels)
ghidrust analyzers
# Run analyzers (comma list or repeatable --analyzer)
ghidrust analyze /path/to/app.exe --analyzers "Function Start Search,ASCII Strings,Unicode Strings" --json
ghidrust analyze /path/to/app.exe --analyzer "Stack" --analyzer "Function ID" --gpu --json
# CPU decompile — Stage-1 default; oracles via --stage0 / --stage05; IL2CPP --follow-stub
ghidrust decompile /path/to/app.exe # Stage-1; quiet stderr
ghidrust decompile /path/to/app.exe --verbose # + metrics line on stderr
ghidrust decompile /path/to/app.exe --addr 0x140001000 --json
ghidrust decompile /path/to/app.exe --stage05 --json # IR oracle + lift-coverage JSON
ghidrust decompile /path/to/GameAssembly.dll --addr 0x180012345 --follow-stub
# Wall-clock + lift-coverage bench across all discovered functions
ghidrust decompile-bench /path/to/app.exe --functions 32 --count 128 --out bench.txt
# Experimental GPU decompile (mid-body addr resolves to containing entry)
ghidrust gpu-decompile /path/to/app.exe --addr 0x140001234 --out entry.gdecomp --metrics metrics.log --json
--gpu on analyze turns on GPU bulk strings (when available) and per-analyzer GPU seed enrichment. It is not the same as gpu-decompile (full VRAM multipass decompile).
Durable projects
ghidrust project create ./MyProject --name Case1
ghidrust project import ./MyProject /path/to/app.exe
ghidrust project list ./MyProject
ghidrust project analyze ./MyProject \
--analyzer "Function Start Search" \
--analyzer "ASCII Strings" \
--gpu
ghidrust project export ./MyProject
Layout on disk:
MyProject/
ghidrust.project.json
imports/ # copied binaries
results/<file_id>/
analysis.bin # primary (fast bincode)
summary.json
analysis.json
exports/
Command reference
| Command | What it does |
|---|---|
ghidrust load <path|--project DIR --file-id ID> [--json] |
Load PE/ELF; JSON includes resolved_path, sections, informational section_notes |
ghidrust disasm <path> [--addr HEX] [--count N] [--skip-bad] [--linear|--flow] [--arch ARCH] [--mode MODE] [--syntax SYNTAX] [--detail] [--detail-real] [--skipdata] [--skipdata-mnemonic S] [--skipdata-size N] [--unsigned-imm] [--only-offset-branch] [--litbase HEX] [--mnem-override ID:MNEM]… [--json] |
Capstone-class listing; bounded by function end by default; --linear escapes; JSON stop_reason + decode_gaps |
ghidrust decode-support [--json] |
Decode engine catalog (version, arches, options, syntax values) |
ghidrust decode-query [--query NAME] [--arch ARCH] [--mode MODE] [--id N] [--index N] [--bytes HEX] [--addr HEX] [--detail] [--json] |
Engine introspection queries |
ghidrust bytes <path> --addr HEX [--count N] [--json] |
Raw VA hex dump |
ghidrust strings <path> [--raw] [--encoding …] [--filter SUB] [--match MODE] [--limit N] [--out FILE] [--json] |
String scan (blob-capable) |
ghidrust xrefs <path> (--to|--from|--string|--import|--calls) [--encoding ascii|utf16le|all] [--skip-stubs] [--classify] [--json] |
RIP-aware xrefs; --calls = callee edges; attribution fields when functions exist |
ghidrust imports <path> [--dll NAME] [--name NAME] [--json] |
PE import / IAT slots |
ghidrust function-at <path> --addr HEX [--json] |
Containing function for a body VA (seed_kind) |
ghidrust function create <path> --addr HEX [--end HEX] [--json] |
Create/heal function at VA (pdata/export/FSS; may synthesize) |
ghidrust inventory <dir> [--max-depth N] [--hash] [--json] |
Generic PE install inventory (exe/dll + VERSIONINFO) |
ghidrust tree <path> [--max-depth N] [--ext LIST] [--name GLOB] [--json] |
Bounded file tree index (existence/size; no unpack) |
ghidrust artifact get|query|list … |
Drain / list spilled analysis artifacts (next_offset) |
ghidrust process list|attach|launch|resume|detach|modules|read|resolve|regions … |
Live Process Bridge (Windows; read-only MVP; launch = CREATE_SUSPENDED) |
ghidrust il2cpp meta|map|touch-map|stubs|icalls … |
IL2CPP metadata / touch-map / RVA map (body_class, --baseline → build_skew, --meta-sections) / stubs / icalls (docs/IL2CPP.md) |
ghidrust unity-inventory <dir> [--out FILE] [--json] |
Unity player install inventory |
ghidrust rtti <path> [--filter|--name|--exact] [--match MODE] [--json] |
RTTI catalog (filter/exact; multi-vtable honest) |
ghidrust analyzers [--json] |
List Auto Analysis names |
ghidrust analyze <path> [--analyzers a,b | --analyzer NAME …] [--gpu] [--json] |
Run analyzers; --gpu = bulk strings + seed enrich |
ghidrust decompile <path> [--addr HEX] [--count N] [--stage0|--stage05|--stage1] [--follow-stub] [--verbose] [--json] |
CPU decompile (Stage-1 default; containing-fn resolve; --follow-stub for IL2CPP) |
ghidrust decompile-bench <path> [--functions N] [--count N] [--stage1] [--parallel] [--out F] |
Per-function wall-clock + lift-coverage across stages |
ghidrust gpu-decompile <path> [--addr HEX] [--out FILE] [--metrics FILE] |
GPU-resident multipass at resolved entry; metrics JSON; .gdecomp opaque |
ghidrust bulk-bench <path> |
Seq / parallel CPU / GPU bulk string timings |
ghidrust re-bench <path> [--out FILE] |
CPU decompile + bulk CPU then GPU metrics |
ghidrust analyzer-bench <path> [--large] [--out FILE] |
All analyzers + decompile: CPU vs GPU |
ghidrust analyzer-bench-matrix |
Print GPU strategy class per analyzer |
ghidrust rtti-gpu-bench <path> [--out FILE] |
CPU RTTI vs GPU rtti_scan |
ghidrust project create|import|list|analyze|export … |
Durable projects |
ghidrust version / --version / -V [--json] |
Package version + tool_surface (matches MCP / egui About) |
ghidrust mcp |
Stdio MCP server for agents |
--json and --out FILE write UTF-8 without BOM. Prefer --out over shell redirection when filters contain : (Windows path hazard). Decompile status lines go to stderr only with --verbose (avoids PowerShell NativeCommandError noise when scripting).
Recommended early path: strings / imports / xrefs for orientation → Exception Directory / .pdata seeds + Function Start Search → function create for orphans → bounded disasm / xrefs --calls → address tables → conventions/stack → RTTI → decompile. For Unity IL2CPP players: unity-inventory → il2cpp touch-map (names) → il2cpp map (body_class / shared stubs; --baseline for build_skew) → stubs / --follow-stub as needed.
GUI — full usage
cargo run -p ghidrust-gui --release
# or
./target/release/ghidrust-gui
# Windows: .\target\release\ghidrust-gui.exe
Typical session:
- Project picker — open/create a project folder, pick a recent one, or continue without a project.
- Browse… / Import a PE or ELF into the project tree.
- Double-click a file to load listing / saved analysis into Overview.
- Analyze… — check analyzers (Defaults / All / None), optionally enable GPU (strings bulk + per-analyzer seed kernels), then Run Analysis.
- Results persist under
results/<id>/(analysis.binfor fast reopen, plussummary.json).
The GUI is for humans. Agents should use the CLI or MCP, not drive the UI.
MCP — setup in AI tools
ghidrust mcp is a stdio MCP server (JSON-RPC). Your AI client starts the binary and talks over stdin/stdout — there is no separate HTTP port.
1. Build the CLI once
cargo build -p ghidrust-cli --release
Note the absolute path to the binary, e.g. C:\path\to\Ghidrust\target\release\ghidrust.exe on Windows or /path/to/Ghidrust/target/release/ghidrust on Linux/macOS.
2. Register it in your client
Cursor — user or project MCP config (e.g. ~/.cursor/mcp.json or a local .cursor/mcp.json). Keep project-local .cursor/ gitignored — it is machine-specific IDE config, not product source:
{
"mcpServers": {
"ghidrust": {
"command": "C:/path/to/Ghidrust/target/release/ghidrust.exe",
"args": ["mcp"]
}
}
}
Claude Desktop — in claude_desktop_config.json:
{
"mcpServers": {
"ghidrust": {
"command": "C:/path/to/Ghidrust/target/release/ghidrust.exe",
"args": ["mcp"]
}
}
}
Other MCP clients — same pattern: command = absolute path to ghidrust / ghidrust.exe, args = ["mcp"]. Restart the client after editing config.
After rebuild/restart, confirm the binary matches the skill: ghidrust --version (package + tool_surface), and MCP server_info / tools/list includes process_list and server_info. If those tools are missing, the client is still running a stale binary — rebuild and restart MCP; do not treat that as “live process unsupported.”
On Linux/macOS:
{
"mcpServers": {
"ghidrust": {
"command": "/path/to/Ghidrust/target/release/ghidrust",
"args": ["mcp"]
}
}
}
3. Tools the server exposes
| Tool | Args | Purpose |
|---|---|---|
server_info |
— | Package version, monotonic tool_surface, features, live session_model |
load |
path or project+file_id |
Load PE/ELF; resolved_path, sections, section_notes |
decode_support |
— | Engine version, 23 arches, options, syntax values, compile features |
decode_query |
query, optional arch, mode, id, index, bytes, addr, detail |
Introspection: insn_name, reg_name, group_name, insn_group, reg_read, reg_write, op_count, op_index, regs_access |
disassemble |
path, optional addr, count, skip_bad, linear, flow, arch, mode, syntax, detail, detail_real, skipdata, skipdata_mnemonic, skipdata_size, unsigned_imm, only_offset_branch, litbase, mnem_overrides |
Bounded by function end by default; linear:true escapes; JSON stop_reason + decode_gaps |
rtti |
path |
Full RTTI recover dump |
rtti_query |
path, optional filter, exact, match |
Catalog query; multi-vtable; artifact if large |
artifact_get / artifact_query / artifact_list |
id / optional offset/limit / optional max |
Drain or list spilled results (next_offset) |
inventory |
path, optional max_depth, hash |
Generic PE dir inventory + VERSIONINFO |
list_tree |
path, optional max_depth, extensions, name_glob |
Bounded tree index |
list_analyzers |
— | Auto Analysis option names |
analyze |
path, optional analyzers[], optional gpu |
Run analyzers (+ GPU enrich if gpu: true) |
list_strings / search_strings |
path, optional encoding (ascii|utf16|all), filter, match (substr|token|whole|glob), min, limit, raw |
ASCII / UTF-16LE strings; raw:true for non-PE/ELF blobs |
get_xrefs_to |
path, addr, optional skip_stubs, classify |
Xrefs to a VA; IL2CPP resolve-stub filter/label; to_entry when known |
get_xrefs_from |
path, addr, optional count |
Xrefs from a VA; from_entry / from_function / to_entry when known |
get_calls_from |
path, addr |
Callee edges (call/jmp) inside the containing function |
get_string_xrefs |
path, filter, optional encoding |
String xrefs with ascii|utf16le|all |
list_imports |
path, optional dll / name |
PE IAT slots |
get_import_xrefs |
path, name |
Code sites that reference an import IAT slot |
function_at / get_function_by_address |
path, addr |
Containing function for a body VA (seed_kind) |
read_bytes |
path, addr, optional count |
Raw VA hex dump |
il2cpp_meta |
path, optional filter |
Parse global-metadata.dat (v27/29/31); fail closed if encrypted |
il2cpp_map |
binary, meta or meta_sections, optional filter, baseline |
Metadata ↔ RVA + body_class / shared_stubs / semantics_mismatch / optional build_skew |
il2cpp_touch_map |
filter, meta or meta_sections, optional binary |
Substring touch-map over metadata heaps |
il2cpp_stubs |
binary, optional filter, max |
List IL2CPP resolve stubs by icall name |
il2cpp_icalls |
binary, optional filter |
Engine icall name↔fn tables |
function_create |
path, addr, optional end |
Create/heal a function at VA (pdata/export/FSS; may synthesize SYNTH_*) |
unity_inventory |
path |
Unity player dir → assemblies, plugins, metadata, PE versions |
decompile |
path, optional addr, count, stage, follow_stub |
Containing-fn resolve + Stage-1 expression-folded C; JSON includes folded_temps, token_count, goto_rate, resolve |
list_gpu_strategies |
— | Per-analyzer GPU strategy matrix |
gpu_decompile |
path, optional addr, out |
GPU decompile at VA; metrics JSON; dump opaque |
rtti_gpu_bench |
path |
CPU vs GPU RTTI with PCIe/device split |
process_list / process_attach / process_launch / … / process_break_* / process_wait / process_scan / process_watch_expr |
session / pid / mode / image / module / rva / max | Live Process Bridge (Windows; observe default; debug opt-in; tool_surface ≥ 7) |
net_dig / net_playbook |
hint fields (path/pid/host/ioc) or alert/flow refs |
Compile or execute dig playbook; closed-loop from alert (tool_surface ≥ 8) |
net_connections / net_owners / net_ifaces |
optional pid / filter | Host sockets → owning image; interface list |
net_capture_start / net_capture_stop / net_capture_status / net_flows |
session / iface / replay path | In-process capture session + attributed flows (MCP/GUI; not CLI one-shot reuse) |
net_detect / net_alerts |
pcap / optional rules / max |
GNR/ET detect on a capture; omit rules → active pack + ghidrust-minimal.rules |
net_rules_list / net_rules_load / net_rules_check / net_rules_update |
path / from_archive / url / et_version / dest |
List/check packs; one-click ET Open install (same install_et_open as CLI/GUI) |
net_pivots / net_job_get |
pcap / job id | DNS/TLS/HTTP/SMB pivot fields; dig job status |
Live process (Windows)
Default observe = read-only (PROCESS_VM_READ): process list → attach <pid> [-mode observe] → modules → resolve --module NAME --rva HEX → read / scan / watch → detach.
Debug (-mode debug, requires tool_surface >= 7): attach or launch with debug rights → break set → continue / wait → registers (regs) + stack → optional scan / watch → snapshot → detach. Observe launch still uses CREATE_SUSPENDED + resume. Debug launch uses Windows debug APIs (initial break). Multi-step work must stay in one MCP/GUI process — CLI one-shot cannot reuse session_id. Bytes ≠ types. Anti-cheat: advisory only; access denied is explicit.
GUI Debugger walkthrough
- Debugger → Attach… (or Launch…)
- Targets: set Mode = debug, Attach PID (or Launch with Break at entry)
- Modules: static map
module + RVA→ live VA - Breakpoints: paste live VA → Add
- Continue (F5) / Wait stop → Registers + Stack update
- Watches: add
module+rva->*+0x10→ Refresh; optional AOB Scan - Console → Export snapshot → Detach
Versioning: ghidrust --version, MCP initialize/server_info, and egui Help → About / window title all report the same workspace package version. Agents also check tool_surface: minimum 3 (touch-map / body_class / function_create); prefer >= 4 for bounded disasm / get_calls_from; require >= 5 for decode_support, decode_query, and extended disassemble decode flags; >= 6 for crypto recover/bake; >= 7 for live debug break/step/scan/watch; >= 8 for Ghidnet (net_*, server_info.network); current is 8. server_info.decode mirrors decode-support; server_info.live_process lists modes + capabilities; server_info.network describes Ghidnet.
Analysis artifacts
Large MCP/CLI dumps spill to %TEMP%/ghidrust-artifacts/. Tool envelopes include entry_count, preview, artifact_id, and next_offset. Drain with artifact_query until next_offset is null — never treat truncated host UI text as complete.
GUI Window homes (§13)
| Capability | Window / pane |
|---|---|
| IL2CPP meta / methods / icalls | IL2CPP Metadata, IL2CPP Methods, IL2CPP ICalls |
| PE / Unity inventory | Install Inventory |
| Tree index | File System Browser |
| Artifact spill | Analysis Artifacts |
| GPU decompile | Analysis → GPU Decompile… |
| Encoding / xrefs / RTTI / notes | Defined Strings, Symbol References, Symbol Tree Classes, Memory Map |
| Live process | Debugger (tabbed): Targets / Modules / Memory Bytes / Regions / Breakpoints / Threads / Registers / Stack / Watches (live APIs under mode=debug) |
| Ghidnet | Network tabbed host (Window → Network, or top-level Network menu): Connections / Capture / Alerts / Rules / Dig |
IL2CPP version matrix and Unity inventory schema: docs/IL2CPP.md.
Example agent-facing call shapes (conceptual):
{ "name": "list_strings", "arguments": { "path": "…/app.exe", "encoding": "all", "filter": "Camera", "match": "token", "limit": 50 } }
{ "name": "list_strings", "arguments": { "path": "…/global-metadata.dat", "raw": true, "filter": "UnityEngine", "limit": 20 } }
{ "name": "get_xrefs_to", "arguments": { "path": "…/GameAssembly.dll", "addr": "0x180012345", "skip_stubs": true, "classify": true } }
{ "name": "get_string_xrefs", "arguments": { "path": "…/app.exe", "filter": "ResolutionWidth" } }
{ "name": "get_import_xrefs", "arguments": { "path": "…/app.exe", "name": "ShellExecuteW" } }
{ "name": "function_at", "arguments": { "path": "…/app.exe", "addr": "0x14000d8ad" } }
{ "name": "function_create", "arguments": { "path": "…/app.exe", "addr": "0x14000d8ad" } }
{ "name": "decode_support", "arguments": {} }
{ "name": "decode_query", "arguments": { "query": "insn_name", "arch": "x86", "id": 1 } }
{ "name": "disassemble", "arguments": { "path": "…/app.exe", "addr": "0x14000d890", "count": 40, "detail": true, "syntax": "intel" } }
{ "name": "get_calls_from", "arguments": { "path": "…/app.exe", "addr": "0x14000d8ad" } }
{ "name": "unity_inventory", "arguments": { "path": "…/GameDir" } }
{ "name": "il2cpp_touch_map", "arguments": { "meta": "…/global-metadata.dat", "filter": "Camera" } }
{ "name": "il2cpp_meta", "arguments": { "path": "…/global-metadata.dat", "filter": "Camera" } }
{ "name": "il2cpp_map", "arguments": { "binary": "…/GameAssembly.dll", "meta": "…/global-metadata.dat", "baseline": "…/prev_map.json" } }
{ "name": "il2cpp_stubs", "arguments": { "binary": "…/GameAssembly.dll", "filter": "Camera" } }
{ "name": "decompile", "arguments": { "path": "…/GameAssembly.dll", "addr": "0x180012345", "follow_stub": true } }
{ "name": "analyze", "arguments": { "path": "…/app.exe", "analyzers": ["ASCII Strings", "Unicode Strings"], "gpu": true } }
{ "name": "inventory", "arguments": { "path": "…/InstallRoot", "max_depth": 8 } }
{ "name": "list_tree", "arguments": { "path": "…/GameDir", "extensions": "dll,dat" } }
{ "name": "rtti_query", "arguments": { "path": "…/app.exe", "filter": "Widget" } }
{ "name": "artifact_query", "arguments": { "id": "<artifact_id>", "offset": 0, "limit": 64 } }
{ "name": "process_list", "arguments": {} }
{ "name": "process_attach", "arguments": { "pid": 1234 } }
{ "name": "process_launch", "arguments": { "image": "C:/path/to/app.exe", "args": "--flag", "cwd": "C:/path/to" } }
{ "name": "process_resume", "arguments": { "session_id": "…" } }
{ "name": "process_resolve", "arguments": { "session_id": "…", "module": "app.exe", "rva": "0x1234" } }
4. Optional: agent skill
For tools that load skill files (Cursor, Grok, etc.), also install skill/SKILL.md so the model knows when to call CLI vs MCP. See skill/README.md.
5. Smoke-test without an IDE
# Manual stdio check: start the server, then send JSON-RPC lines from your client.
./target/release/ghidrust mcp
You should not need to type JSON by hand day-to-day — the IDE/agent does that once the server is registered.
Ghidnet (native network plane)
Ghidnet is Ghidrust’s in-tree network investigation plane: attribute → detect → dig. It does not vendor Suricata, Wireshark, Npcap crates, or suricata-update. Outcome target is host investigation that pivots into the same load / analyze / decompile / live-process stack — not packet-UI feature parity with desktop sniffers, and not a kernel IPS.
Requires tool_surface >= 8. server_info.network advertises the plane (caps include et-open / ids). Airgap policy blocks live observe tools (net_connections, capture, detect) while still allowing path-only dig. Full agent SOP: skill/ghidnet.md.
Pipeline
| Stage | What you get | CLI | MCP |
|---|---|---|---|
| Attribute | TCP/UDP sockets → owning PID/image; interface list | net connections, net owners, net ifaces |
net_connections, net_owners, net_ifaces |
| Capture / flows | In-process session, GRNCAP01 files, ghidnetcap live NIC, replay backend, flow table |
net capture …, net flows, ghidrust-netcap |
net_capture_*, net_flows |
| Rules / ET Open | Fetch/install Proofpoint ET Open; activate pack; merge with bundled GNR | net rules update et-open, net rules list|check |
net_rules_update, net_rules_list, net_rules_check |
| Detect (IDS) | Compiled GNR/ET rules → alert/pass/drop records (in-tree matcher) |
net detect, net alerts |
net_detect, net_alerts |
| Pivots | DNS / TLS SNI / HTTP / SMB fields from frames | net pivots --pcap FILE |
net_pivots |
| Dig | Playbook compile/execute; closed-loop from alert → image RE | net dig, net playbook |
net_dig, net_playbook, net_job_get |
ghidrust net help prints the full subcommand list.
ET Open install (one-click)
Proofpoint Emerging Threats Open rules are used as written. The in-tree matcher implements a Suricata-shaped subset; SIDs that need unimplemented keywords are skipped (counted in the install/list report), not rewritten.
CLI, GUI Download / update ET Open, and MCP net_rules_update all call the same install_et_open:
- Fetch
emerging.rules.tar.gz+.md5fromhttps://rules.emergingthreats.net/open(or--from-archive/from_archivefor airgap/CI). - Verify MD5, extract under the user rules root, write
ghidrust.vars($HTTP_SERVERS=$HOME_NETand other Suricata aliases). - Point
active.jsonat that pack. Detect then compiles all*.rulesin the pack plusrules/ghidrust-minimal.rules.
# Online (default ET Open 7.0.3)
./target/release/ghidrust net rules update et-open --json
# Airgap / CI: local tarball + sidecar .md5
./target/release/ghidrust net rules update et-open --from-archive fixtures/et-open-mini.tar.gz --et-version mini --dest DIR --json
./target/release/ghidrust net rules list --json
# → packs.active, loaded, skipped, skip_reasons[]
Rules root (override with GHIDRUST_RULES_DIR):
| OS | Default |
|---|---|
| Windows | %APPDATA%\ghidrust\rules |
| Linux | $XDG_CONFIG_HOME/ghidrust/rules or ~/.ghidrust/rules |
| Pack layout | et-open/<version>/ + active.json |
Optional --url / --et-version / --et-code (ET Pro oink; never logged). Do not vendor the ~40 MB ET tarball in git; CI uses fixtures/et-open-mini.tar.gz.
Detect (IDS, not kernel IPS)
Without --rules / MCP rules, detect uses load_active_ruleset() (active ET pack + minimal). Explicit --rules PATH still compiles that file only.
# After ET install — uses active pack
./target/release/ghidrust net detect --pcap path/to/capture.grncap --json
./target/release/ghidrust net detect --payload-file fixtures/et-http-gate.bin --json
# Explicit pack
./target/release/ghidrust net detect --pcap capture.grncap --rules rules/ghidrust-minimal.rules --json
./target/release/ghidrust net rules check --path rules/ghidrust-minimal.rules --json
| Matcher covers | Skipped (SID not loaded; listed in skipped / skip_reasons) |
|---|---|
content / pcre, nocase, distance/within (cursor = previous hit end) |
flowbits / xbits / flowint |
Sticky buffers: http.uri/host/method/header, dns.query, tls.sni |
ja3 / ja3s |
flow:established,to_server,to_client |
lua / luajit |
$HOME_NET / $HTTP_SERVERS / CIDR / IP lists |
threshold / detection_filter; file-data; byte_test/byte_jump; unknown http.*/tls.* buffers |
Actions alert, pass, drop recorded as alerts |
Kernel/NFQUEUE/WFP block — not implemented |
drop is an IDS action tag on the alert, not an inline packet drop. Kernel IPS / GHIDRUST_NET_INLINE=1 inline block is a separate, disabled-by-default gate.
Capture (ghidnetcap)
net ifaces lists OS adapters (Windows GetAdaptersInfo; Linux sysfs) plus a replay backend. Live open (net capture start --iface NAME):
- Windows: optional NPF
CreateFileif a driver is present; otherwise IPv4 raw sockets (SIO_RCVALL). Cargo does not link Npcap/WinPcap. - Unix: packet sockets.
- Fail-closed:
privilege_requiredorbackend_unavailable. Never fabricates live frames. GHIDRUST_NET_LIVE_STUB=1is test-only and errors on live open (does not silently emit empty captures).- Prefer
--replay FILE/ MCPreplay_pathin CI.
Quick examples
./target/release/ghidrust net help
# Dig playbook from a hint (compile only)
./target/release/ghidrust net dig --path fixtures/tiny_x64.pe --json
# Execute offline dig (load + analyzers + string/import pivots)
./target/release/ghidrust net dig --path fixtures/tiny_x64.pe --execute --json
# Host sockets (Windows IP Helper / Linux /proc)
./target/release/ghidrust net connections --json
./target/release/ghidrust net owners --pid <PID> --json
./target/release/ghidrust net ifaces --json
./target/release/ghidrust net pivots --pcap path/to/capture.grncap --json
Session note: capture session_id lives in one process (same rule as process_*). Multi-step capture/detect/flows must use MCP, the GUI Network host, or a single long-lived process — CLI one-shot cannot reopen another CLI’s session.
GUI (Network host)
Same APIs as CLI/MCP, in-process:
- Network → Show Connections (or Window → Network)
- Connections: Refresh → select row → Dig (fills Dig tab hint)
- Capture: set iface / replay path → Start → Flows → Detect / Pivots
- Alerts: severity queue → Dig (closed-loop when owner path known)
- Rules: Download / update ET Open (one-click fetch + activate) → pack path → Check (default: active ET pack +
rules/ghidrust-minimal.rules) - Dig: Compile / Execute → Open in Listing (loads image into CodeBrowser)
Honesty bounds: live NIC needs elevation (privilege_required otherwise). Capture sessions are process-local. Host header / Help→About show NetworkInfo (wave/caps). Capture Export path reveals out_path (copy + folder). Inline block is disabled unless GHIDRUST_NET_INLINE=1 (hover shows reason).
Decrypt and crypto discovery
Use the discovery order Find Crypt → recover strings → capabilities → recipe peel. Results are evidence-based; a successful GCM recipe returns the counter-mode plaintext path but does not authenticate a tag.
# Locate known cryptographic tables and likely decrypt/encoding sites
ghidrust crypt-constants PATH --algo AES --json
ghidrust recover-strings PATH --only stack,tight,decoded --json
ghidrust crypto-capabilities PATH --tag decrypt --json
# Peel explicit data or ask the bounded heuristic to try common transforms
ghidrust decode bake -b64 SGVsbG8= -op FromBase64 --json
ghidrust decode bake -hex CIPHERTEXT -op AESDecrypt -key-hex KEY -iv-hex IV -mode cbc --json
ghidrust decode magic -b64 SGVsbG8= -depth 3 -crib Hello --json
MCP equivalents are crypt_constants, recover_strings, list_crypto_capabilities, decode_bake, and decode_magic. See skill/decrypt-feature-test-log.md for the tested feature matrix.
Architecture
┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ ghidrust-gui│ │ ghidrust-cli │ │ MCP stdio │
└──────┬──────┘ └────────┬─────────┘ └────────┬────────┘
▼
┌─────────────────┐
│ ghidrust-core │ loaders, disasm, analyzers, bulk GPU
└────────┬────────┘
▼
┌──────────────┬─────┴──────┬──────────────┐
│ │ │ │
┌──────────┐ ┌─────────────┐ ┌────────────┐ ┌──────────────┐
│ decode │ │ lift │ │ ir │ │ ssa │ hand-rolled
│ Capstone-│→│ x86-64→IR │→│ pcode-like │→│ cfg/dom/DF/ │ decompile
│ class 23 │ │ + flag model│ │ ops+varnode│ │ phi placement│ pipeline
│ ISAs │ │ │ │ │ │ │
└──────────┘ └─────────────┘ └────────────┘ └──────────────┘
│
▼
┌─────────────────┐
│ ghidrust-decomp │ Stage-0 CFG→pseudo-C (oracle)
│ │ Stage-0.5 IR-informed emit
│ │ GPU VRAM multipass (experimental)
└─────────────────┘
| Crate | Role |
|---|---|
ghidrust-core |
PE/ELF/blob, x86-64, analyzers, imports/IAT, xrefs, projects, bulk scan |
ghidrust-decode |
Hand-rolled Capstone-class multi-arch Engine (23 ISAs); no Capstone/iced/zydis at runtime |
ghidrust-ir |
Architecture-neutral pcode-like IR (varnodes, ops, tagged blocks, address spaces) |
ghidrust-lift |
x86-64 → IR semantics with flag model + LiftCoverage reporting |
ghidrust-ssa |
CFG-on-IR, Cooper–Harvey–Kennedy dominators, Cytron dominance frontiers, phi placement |
ghidrust-decomp |
Stage-0 CFG → pseudo-C (regression oracle), Stage-0.5 IR-informed emit (ir_emit), decompile-bench harness, experimental GPU VRAM multipass |
ghidrust-il2cpp |
IL2CPP global-metadata.dat + CodeRegistration correlation + resolve stubs |
ghidrust-unity-inventory |
Unity player layout inventory (assemblies, plugins, metadata) |
ghidrust-net-schema |
Ghidnet VOs (NetHint, Alert, DigPlan, flows/pivots) |
ghidrust-net-attr |
Host socket → owner (Windows IP Helper / Linux /proc) |
ghidrust-net-capture |
Capture sessions, GRNCAP01, ghidnetcap live NIC, replay; bin ghidrust-netcap |
ghidrust-net-flow |
Flow table, reassembly, filters |
ghidrust-net-rules |
GNR/Suricata-shaped parse/compile, ET Open install, active pack + $HOME_NET aliases |
ghidrust-net-detect |
In-tree matcher (sticky buffers, pcre, distance/within); IDS alert/pass/drop records; optional inline via GHIDRUST_NET_INLINE |
ghidrust-net-parse |
DNS / TLS SNI / HTTP / SMB pivot extractors |
ghidrust-net-correlate |
Dig playbooks + closed-loop alert → RE |
ghidrust-cli |
CLI + MCP + benches / gpu-decompile / decompile-bench / net … |
ghidrust-gui |
CodeBrowser-style UI |
Docs
| Doc | Topic |
|---|---|
| docs/GPU_DECOMPILER_RESEARCH.md | Research paper: GPU decompile method + results |
| docs/GPU_DECOMPILE_PROCESS.md | Multipass dataflow + dump format |
| docs/GPU_ANALYZER_MATRIX.md | Per-analyzer GPU strategy + bench CLI |
| docs/PARALLEL_RE_RESEARCH.md | CPU pool vs GPU bulk RE |
| docs/IL2CPP.md | IL2CPP metadata matrix + Unity player inventory |
| skill/README.md | Agent skill install |
License
Apache License 2.0 — same license as Ghidra.