Skip to content

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.

Updated readmes

oofz09f275d11a80
diff --git a/README.md b/README.md
index 7f96a49..43d6cb0 100644
--- a/README.md
+++ b/README.md
@@ -109,7 +109,86 @@ Fixtures live under [`fixtures/`](fixtures/) (`tiny_x64.pe`, `analysis_lab.pe`,
---
-## CLI reference
+## 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 both 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.
+
+```bash
+# After release build
+./target/release/ghidrust help
+
+# Windows
+.\target\release\ghidrust.exe help
+```
+
+### Everyday commands
+
+```bash
+# Map a binary
+ghidrust load /path/to/app.exe --json
+
+# Listing
+ghidrust disasm /path/to/app.exe --count 32
+ghidrust disasm /path/to/app.exe --addr 0x140001000 --count 64
+
+# 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" --json
+ghidrust analyze /path/to/app.exe --analyzer "Stack" --analyzer "Function ID" --gpu --json
+
+# CPU decompile (pseudo-C)
+ghidrust decompile /path/to/app.exe
+ghidrust decompile /path/to/app.exe --addr 0x140001000
+
+# Experimental GPU decompile → greppable dump
+ghidrust gpu-decompile /path/to/app.exe --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
+
+```bash
+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 |
|---------|----------------|
@@ -126,38 +205,115 @@ Fixtures live under [`fixtures/`](fixtures/) (`tiny_x64.pe`, `analysis_lab.pe`,
| `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 mcp` | Stdio MCP tools for agents |
+| `ghidrust mcp` | Stdio MCP server for agents |
+
+Recommended early analyzer order: **Function Start Search** → address tables → conventions/stack → strings/RTTI.
+
+---
+
+## GUI — full usage
+
+```bash
+cargo run -p ghidrust-gui --release
+# or
+./target/release/ghidrust-gui
+# Windows: .\target\release\ghidrust-gui.exe
+```
+
+Typical session:
-### Project workflow
+1. **Project picker** — open/create a project folder, pick a recent one, or continue without a project.
+2. **Browse… / Import** a PE or ELF into the project tree.
+3. **Double-click** a file to load listing / saved analysis into Overview.
+4. **Analyze…** — check analyzers (Defaults / All / None), optionally enable **GPU (strings bulk + per-analyzer seed kernels)**, then **Run Analysis**.
+5. Results persist under `results/<id>/` (`analysis.bin` for fast reopen, plus `summary.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
```bash
-./target/release/ghidrust project create ./MyProject --name Case1
-./target/release/ghidrust project import ./MyProject ./samples/app.exe
-./target/release/ghidrust project list ./MyProject
-./target/release/ghidrust project analyze ./MyProject --analyzer "Function Start Search" --analyzer "ASCII Strings" --gpu
-./target/release/ghidrust project export ./MyProject
+cargo build -p ghidrust-cli --release
```
-On-disk layout:
+Note the absolute path to the binary, e.g. `F:\Repos\Ghidrust\target\release\ghidrust.exe` on Windows or `/home/you/Ghidrust/target/release/ghidrust` on Linux/macOS.
+
+### 2. Register it in your client
+**Cursor** — project or user MCP config (e.g. `.cursor/mcp.json`):
+
+```json
+{
+ "mcpServers": {
+ "ghidrust": {
+ "command": "F:/Repos/Ghidrust/target/release/ghidrust.exe",
+ "args": ["mcp"]
+ }
+ }
+}
```
-MyProject/
- ghidrust.project.json
- imports/ # copied binaries
- results/<file_id>/
- analysis.bin # primary (fast bincode)
- summary.json
- analysis.json
- exports/
+
+**Claude Desktop** — in `claude_desktop_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "ghidrust": {
+ "command": "F:/Repos/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.
+
+On Linux/macOS you can use a shell wrapper if needed:
+
+```json
+{
+ "mcpServers": {
+ "ghidrust": {
+ "command": "/home/you/Ghidrust/target/release/ghidrust",
+ "args": ["mcp"]
+ }
+ }
+}
```
-### GUI workflow
+### 3. Tools the server exposes
+
+| Tool | Args | Purpose |
+|------|------|---------|
+| `load` | `path` | Load PE/ELF, return map / sections |
+| `disassemble` | `path`, optional `addr`, `count` | x86-64 listing |
+| `rtti` | `path` | Recover RTTI class names / vtables |
+| `list_analyzers` | — | Auto Analysis option names |
+| `analyze` | `path`, optional `analyzers[]`, optional `gpu` | Run analyzers (+ GPU enrich if `gpu: true`) |
+| `list_gpu_strategies` | — | Per-analyzer GPU strategy matrix |
+| `gpu_decompile` | `path`, optional `out` | GPU-resident multipass decompile |
+| `rtti_gpu_bench` | `path` | CPU vs GPU RTTI with PCIe/device split |
+
+Example agent-facing call shape (conceptual): `analyze` with `{ "path": "…/app.exe", "analyzers": ["ASCII Strings"], "gpu": true }`.
+
+### 4. Optional: agent skill
+
+For tools that load skill files (Cursor, Grok, etc.), also install [skill/SKILL.md](skill/SKILL.md) so the model knows *when* to call CLI vs MCP. See [skill/README.md](skill/README.md).
+
+### 5. Smoke-test without an IDE
+
+```bash
+# Manual stdio check: start the server, then send JSON-RPC lines from your client.
+./target/release/ghidrust mcp
+```
-1. Open/create a project (folder with `ghidrust.project.json`), or continue without one.
-2. **Browse…** / **Import** a PE or ELF.
-3. Double-click a file in the Project Tree.
-4. **Analyze…** → choose analyzers (optional GPU bulk for strings).
-5. Results save under `results/<id>/` for fast reopen.
+You should not need to type JSON by hand day-to-day — the IDE/agent does that once the server is registered.
---
@@ -184,20 +340,6 @@ MyProject/
| `ghidrust-cli` | CLI + MCP + benches / `gpu-decompile` |
| `ghidrust-gui` | CodeBrowser-style UI |
-Recommended early analyzer order: **Function Start Search** → address tables → conventions/stack → strings/RTTI (`ghidrust analyzers` for the full list).
-
----
-
-## MCP and agent skill
-
-```bash
-./target/release/ghidrust mcp
-```
-
-JSON-RPC over stdio: `load`, `disassemble`, `rtti`, `list_analyzers`, `analyze`.
-
-Optional agent skill (Cursor, Grok, and other skill-aware tools): [skill/SKILL.md](skill/SKILL.md) — install notes in [skill/README.md](skill/README.md).
-
---
## Docs
@@ -209,6 +351,7 @@ Optional agent skill (Cursor, Grok, and other skill-aware tools): [skill/SKILL.m
| [docs/GPU_ANALYZER_MATRIX.md](docs/GPU_ANALYZER_MATRIX.md) | Per-analyzer GPU strategy + bench CLI |
| [docs/PARALLEL_RE_RESEARCH.md](docs/PARALLEL_RE_RESEARCH.md) | CPU pool vs GPU bulk RE |
| [DEPENDENCIES.md](DEPENDENCIES.md) | Dependency policy |
+| [skill/README.md](skill/README.md) | Agent skill install |
---
diff --git a/skill/README.md b/skill/README.md
index 70b3add..96a289e 100644
--- a/skill/README.md
+++ b/skill/README.md
@@ -26,7 +26,7 @@ cargo run -p ghidrust-gui --release
Windows: `.\target\release\ghidrust.exe` / `.\target\release\ghidrust-gui.exe`.
-MCP for agents:
+MCP for agents (register in Cursor / Claude Desktop / other MCP clients — see root README):
```bash
./target/release/ghidrust mcp