ghidra-decomp 0.2.0__tar.gz

ghidra_decomp-0.2.0/.gitattributes

@@ -0,0 +1,2 @@
+# Prevent Git from mangling binary test fixtures
+tests/fixtures/sample binary

ghidra_decomp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install click mypy
+      - run: mypy src/ghidra_decomp/ --ignore-missing-imports
+
+  # Note: e2e tests require a Ghidra installation and are not run in CI.
+  # Run them locally with: pytest tests/

ghidra_decomp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

ghidra_decomp-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.claude/
+CLAUDE.md
+*_ghidra/
+.mypy_cache/
+.ruff_cache/
+*.so
+*.dylib

ghidra_decomp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 totekuh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghidra_decomp-0.2.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: ghidra-decomp
+Version: 0.2.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
+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/) 11.0+ (which bundles pyghidra).
+
+```bash
+pip install -e .
+```
+
+Set `GHIDRA_INSTALL_DIR` to your Ghidra installation, or pass `--ghidra-path`.
+
+## Usage
+
+```bash
+ghidra-decomp ./firmware.bin -o ./firmware_decomp
+```
+
+Options:
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-o, --output` | Output directory | `<binary>_decomp/` |
+| `--timeout` | Per-function decompilation timeout (seconds) | 60 |
+| `--ghidra-path` | Path to Ghidra install | `$GHIDRA_INSTALL_DIR` |
+| `--base-addr` | Rebase binary to this address before analysis (e.g. `0x80000000`) | none |
+| `--entry` | Mark this address as the entry point and disassemble from it before analysis (e.g. `0x31000`). Useful for raw binaries. | none |
+| `--language` | Force Ghidra language ID (e.g. `ARM:LE:32:v7`). Use when auto-detect fails. | auto |
+| `--compiler` | Force compiler spec ID (e.g. `gcc`, `default`, `windows`). Requires `--language`. | auto |
+| `--list-languages` | List all available language IDs and compiler specs, then exit. | |
+
+For raw binaries or unknown formats, Ghidra will refuse to auto-load. Discover the right spec then pass it:
+
+```bash
+ghidra-decomp --list-languages | grep -i arm
+ghidra-decomp ./firmware.bin --language ARM:LE:32:v7 --compiler default
+```
+
+Raw binaries typically also need a known image base and an entry point for auto-analysis to reach every function. Both are applied *before* analysis runs, so function boundaries, xrefs, and switch-table recovery all happen at the real addresses:
+
+```bash
+ghidra-decomp ./dal_ivm.mod \
+  --language x86:LE:32:default \
+  --compiler gcc \
+  --base-addr 0x00031000 \
+  --entry   0x00031000
+```
+
+## Output
+
+```
+firmware_decomp/
+├── functions/
+│   ├── 00010000_main.c
+│   ├── 00010234_parse_config.c
+│   └── ...
+├── all_functions.c     # everything in one file
+├── types.json          # recovered structs, enums, unions, typedefs
+├── functions.json      # function index with address ranges + signatures
+├── callgraph.json      # who calls who
+├── strings.json        # strings + xrefs to functions
+├── imports.json        # external library functions
+├── exports.json        # exported entry points
+├── symbols.json        # globals, labels, data
+├── sections.json       # memory map with r/w/x permissions
+└── metadata.json       # binary info + stats
+```
+
+Each `.c` file includes a metadata header:
+
+```c
+// Function: parse_config
+// Address:  00010234
+// Size:     284 bytes
+// Calling:  __stdcall
+// Params:   3
+
+void parse_config(char *param_1, int param_2, int param_3) {
+    ...
+}
+```
+
+## Intended workflow
+
+1. **Dump** the binary with `ghidra-decomp`
+2. **Analyze** the output like source code — grep, glob, read
+3. **Write back** renames/annotations to Ghidra via MCP (separate tool)
+
+## License
+
+MIT

ghidra_decomp-0.2.0/README.md

@@ -0,0 +1,99 @@
+# 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/) 11.0+ (which bundles pyghidra).
+
+```bash
+pip install -e .
+```
+
+Set `GHIDRA_INSTALL_DIR` to your Ghidra installation, or pass `--ghidra-path`.
+
+## Usage
+
+```bash
+ghidra-decomp ./firmware.bin -o ./firmware_decomp
+```
+
+Options:
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-o, --output` | Output directory | `<binary>_decomp/` |
+| `--timeout` | Per-function decompilation timeout (seconds) | 60 |
+| `--ghidra-path` | Path to Ghidra install | `$GHIDRA_INSTALL_DIR` |
+| `--base-addr` | Rebase binary to this address before analysis (e.g. `0x80000000`) | none |
+| `--entry` | Mark this address as the entry point and disassemble from it before analysis (e.g. `0x31000`). Useful for raw binaries. | none |
+| `--language` | Force Ghidra language ID (e.g. `ARM:LE:32:v7`). Use when auto-detect fails. | auto |
+| `--compiler` | Force compiler spec ID (e.g. `gcc`, `default`, `windows`). Requires `--language`. | auto |
+| `--list-languages` | List all available language IDs and compiler specs, then exit. | |
+
+For raw binaries or unknown formats, Ghidra will refuse to auto-load. Discover the right spec then pass it:
+
+```bash
+ghidra-decomp --list-languages | grep -i arm
+ghidra-decomp ./firmware.bin --language ARM:LE:32:v7 --compiler default
+```
+
+Raw binaries typically also need a known image base and an entry point for auto-analysis to reach every function. Both are applied *before* analysis runs, so function boundaries, xrefs, and switch-table recovery all happen at the real addresses:
+
+```bash
+ghidra-decomp ./dal_ivm.mod \
+  --language x86:LE:32:default \
+  --compiler gcc \
+  --base-addr 0x00031000 \
+  --entry   0x00031000
+```
+
+## Output
+
+```
+firmware_decomp/
+├── functions/
+│   ├── 00010000_main.c
+│   ├── 00010234_parse_config.c
+│   └── ...
+├── all_functions.c     # everything in one file
+├── types.json          # recovered structs, enums, unions, typedefs
+├── functions.json      # function index with address ranges + signatures
+├── callgraph.json      # who calls who
+├── strings.json        # strings + xrefs to functions
+├── imports.json        # external library functions
+├── exports.json        # exported entry points
+├── symbols.json        # globals, labels, data
+├── sections.json       # memory map with r/w/x permissions
+└── metadata.json       # binary info + stats
+```
+
+Each `.c` file includes a metadata header:
+
+```c
+// Function: parse_config
+// Address:  00010234
+// Size:     284 bytes
+// Calling:  __stdcall
+// Params:   3
+
+void parse_config(char *param_1, int param_2, int param_3) {
+    ...
+}
+```
+
+## Intended workflow
+
+1. **Dump** the binary with `ghidra-decomp`
+2. **Analyze** the output like source code — grep, glob, read
+3. **Write back** renames/annotations to Ghidra via MCP (separate tool)
+
+## License
+
+MIT

ghidra_decomp-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ghidra-decomp"
+dynamic = ["version"]
+description = "Bulk-decompile binaries via Ghidra into a browsable source tree"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{name = "totekuh", email = "totekuh@protonmail.com"}]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Disassemblers",
+]
+dependencies = [
+    "pyghidra",
+    "click",
+]
+
+[project.scripts]
+ghidra-decomp = "ghidra_decomp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/totekuh/ghidra-decomp"
+Repository = "https://github.com/totekuh/ghidra-decomp"
+Issues = "https://github.com/totekuh/ghidra-decomp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ghidra_decomp"]
+
+[tool.hatch.version]
+path = "src/ghidra_decomp/__init__.py"

ghidra_decomp-0.2.0/src/ghidra_decomp/__init__.py

@@ -0,0 +1,3 @@
+"""Bulk-decompile binaries via Ghidra into a browsable source tree."""
+
+__version__ = "0.2.0"

ghidra_decomp-0.2.0/src/ghidra_decomp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m ghidra_decomp."""
+
+from .cli import main
+
+main()

ghidra_decomp-0.2.0/src/ghidra_decomp/cli.py

@@ -0,0 +1,128 @@
+"""CLI entry point for ghidra-decomp."""
+
+import click
+from pathlib import Path
+
+from .decompiler import decompile_binary, list_languages
+
+
+@click.command()
+@click.argument(
+    "binary",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    required=False,
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Output directory. Defaults to <binary_name>_decomp/",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=60,
+    show_default=True,
+    help="Decompilation timeout per function (seconds).",
+)
+@click.option(
+    "--ghidra-path",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    envvar="GHIDRA_INSTALL_DIR",
+    default=None,
+    help="Path to Ghidra installation. Falls back to GHIDRA_INSTALL_DIR env var.",
+)
+@click.option(
+    "--base-addr",
+    type=str,
+    default=None,
+    help="Rebase the binary to this address before analysis (e.g. 0x80000000).",
+)
+@click.option(
+    "--entry",
+    type=str,
+    default=None,
+    help="Mark this address as the program entry point and disassemble from it "
+    "before analysis (e.g. 0x31000). Useful for raw binaries.",
+)
+@click.option(
+    "--language",
+    type=str,
+    default=None,
+    help="Force Ghidra language/processor ID (e.g. ARM:LE:32:v7). "
+    "Use when auto-detect fails. See --list-languages.",
+)
+@click.option(
+    "--compiler",
+    type=str,
+    default=None,
+    help="Force compiler spec ID (e.g. gcc, default, windows). "
+    "Requires --language. See --list-languages.",
+)
+@click.option(
+    "--list-languages",
+    "list_langs",
+    is_flag=True,
+    default=False,
+    help="List all available Ghidra language IDs and their compiler specs, then exit.",
+)
+def main(
+    binary: Path | None,
+    output: Path | None,
+    timeout: int,
+    ghidra_path: Path | None,
+    base_addr: str | None,
+    entry: str | None,
+    language: str | None,
+    compiler: str | None,
+    list_langs: bool,
+):
+    """Decompile BINARY into a browsable source tree.
+
+    Produces one .c file per function, plus JSON indexes for strings,
+    call graph, imports, and exports.
+    """
+    if list_langs:
+        list_languages(ghidra_path=ghidra_path)
+        return
+
+    if binary is None:
+        raise click.UsageError("Missing argument 'BINARY'.")
+
+    if compiler is not None and language is None:
+        raise click.UsageError("--compiler requires --language.")
+
+    binary = binary.resolve()
+    if output is None:
+        output = Path.cwd() / f"{binary.stem}_decomp"
+
+    output = output.resolve()
+
+    click.echo(f"Binary:  {binary}")
+    click.echo(f"Output:  {output}")
+    if base_addr is not None:
+        click.echo(f"Base:    {base_addr}")
+    if entry is not None:
+        click.echo(f"Entry:   {entry}")
+    if language is not None:
+        click.echo(f"Lang:    {language}")
+    if compiler is not None:
+        click.echo(f"CSpec:   {compiler}")
+
+    decompile_binary(
+        binary,
+        output,
+        timeout=timeout,
+        ghidra_path=ghidra_path,
+        base_addr=base_addr,
+        entry=entry,
+        language=language,
+        compiler=compiler,
+    )
+
+    click.echo(f"\nDone. Output at: {output}")
+
+
+if __name__ == "__main__":
+    main()