Metadata-Version: 2.5
Name: ghidra-decomp
Version: 0.8.0
Summary: Bulk-decompile binaries via Ghidra into a browsable source tree
Project-URL: Homepage, https://github.com/totekuh/ghidra-decomp
Project-URL: Repository, https://github.com/totekuh/ghidra-decomp
Project-URL: Issues, https://github.com/totekuh/ghidra-decomp/issues
Author-email: totekuh <totekuh@protonmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Disassemblers
Requires-Python: >=3.10
Requires-Dist: click
Requires-Dist: pyghidra>=3.0
Description-Content-Type: text/markdown

# ghidra-decomp

Bulk-decompile binaries into browsable source trees using Ghidra.

Takes a binary, runs Ghidra's decompiler on every function, and produces a directory of `.c` files and JSON indexes — ready for grep, code review, or AI-assisted analysis.

## Why

Reverse engineering through Ghidra's GUI (or MCP) means looking at one function at a time. This tool dumps everything upfront so you can treat the binary like a normal codebase: grep for patterns, read call graphs, search strings — all without waiting for decompilation round-trips.

## Install

Requires [Ghidra](https://ghidra-sre.org/) 12.0+ and PyGhidra 3.0+.

```bash
make install
```

Or manually: `pip install -e .`

Set `GHIDRA_INSTALL_DIR` to your Ghidra installation, or pass `--ghidra-path`.

## Usage

```bash
ghidra-decomp ./firmware.bin -o ./firmware_decomp
```

| Flag | Description | Default |
|------|-------------|---------|
| `-o, --output` | Output directory | `<binary>_decomp/` |
| `--timeout` | Per-function decompilation timeout (seconds) | 60 |
| `--combined` | Also emit `all_functions.c` | off |
| `--ghidra-path` | Path to Ghidra install | `$GHIDRA_INSTALL_DIR` |
| `--base-addr` | Rebase binary to this address before analysis | none |
| `--entry` | Mark address as entry point before analysis | none |
| `--language` | Force Ghidra language ID (e.g. `ARM:LE:32:v7`) | auto |
| `--compiler` | Force compiler spec ID. Requires `--language`. | auto |
| `--list-languages` | List all available language/compiler IDs, then exit | |
| `--workers` | Decompiler threads | `min(4, CPU count)` |
| `--resume` | Reuse hash-valid per-function artifacts from existing output | off |
| `--include` / `--exclude` | Function name regexes. Repeatable. | all |
| `--function` | Export function at this address. Repeatable. | |
| `--gdt` | Apply a Ghidra data type archive. Repeatable. | none |
| `--pdb` | PDB source: `auto` (fetch from symbol server), `none`, or local path | detect+prompt |
| `--gzf` | Also export `program.gzf` | off |
| `--semgrep-config` | Scan pseudocode with semgrep, write `semgrep.sarif` | off |
| `--verbose-analysis` | Attach console monitor to Ghidra auto-analysis | off |
| `--mermaid` | Render call graphs as Mermaid flowcharts in `callgraphs/` | off |
| `--cpp-export` | Export single `.c` + `.h` via Ghidra's CppExporter | off |
| `--max-ram-percent` | JVM MaxRAMPercentage for heap sizing (1.0–100.0) | 50.0 |
| `--print-jvm-flags` | Print JVM flag values at startup | off |
| `--callgraph-depth` | Neighborhood hops for per-function Mermaid (1–10) | 1 |
| `--condense-threshold` | Collapse whole-graph Mermaid when edges exceed N | none |
| `--reachable FROM TO` | Check if FROM can reach TO in the call graph | none |

## Output

```
firmware_decomp/
├── manifest.json
├── functions/
│   ├── 00010000_<digest>_main.c
│   ├── 00010000_<digest>_main.json
│   └── ...
├── assembly/
│   ├── 00010000_<digest>_main.s
│   └── ...
├── xrefs.jsonl
├── all_functions.c     # --combined
├── program.gzf         # --gzf
├── semgrep.sarif       # --semgrep-config
├── types.json
├── functions.json
├── callgraph.json
├── callgraphs/          # --mermaid
│   ├── callgraph.md
│   ├── endpoints.json
│   ├── reachability.json  # --reachable
│   ├── paths.md           # --reachable --mermaid
│   └── <function>.md
├── export.c             # --cpp-export
├── export.h             # --cpp-export
├── strings.json
├── imports.json
├── exports.json
├── symbols.json
├── sections.json
└── metadata.json
```

See [docs/output-format.md](docs/output-format.md) for the full artifact contract, sidecar structure, type records, and manifest semantics.

## Callgraph Queries (no Ghidra needed)

Query a previous export's `callgraph.json` without starting Ghidra:

```bash
# Find root and leaf functions
ghidra-decomp-query endpoints ./firmware_decomp

# Check if main can reach encrypt_data
ghidra-decomp-query reachable ./firmware_decomp main encrypt_data

# Find all paths between two functions
ghidra-decomp-query paths ./firmware_decomp main encrypt_data --max-depth 50
```

## Docker

```bash
docker compose run --rm ghidra-decomp ./firmware.bin -o /output/firmware_decomp
```

## Workflow

1. **Dump** the binary with `ghidra-decomp`
2. **Analyze** the output like source code — grep, glob, read
3. **Re-run** with `--resume`, or narrow with `--include`/`--function`
4. **Write back** renames/annotations to Ghidra via MCP (separate tool, not yet built)

## Docs

- [Output format](docs/output-format.md) — artifact contract, sidecars, types, manifest
- [Raw binaries](docs/raw-binaries.md) — language/compiler selection, rebasing, entry points
- [Development](docs/development.md) — testing, CI, fixture regeneration

## License

MIT
