nightwing-us/pyghidra-decaf

# PyGhidra Decaf 一个无需 Java 开发即可为 Ghidra 开发插件的 Python 包 ## 文档概述 - [快速开始](#quick-start) — 5 分钟编写你的第一个插件 - [插件开发指南](docs/index.md) — 完整的 API 参考与示例 - [架构与对比](docs/gap-analysis-ghidra-pyghidra-decaf.md) — Decaf 存在的原因及其与 PyGhidra 的对比 - [使用 pyghidra-decaf 的项目](#projects-using-pyghidra-decaf) — 你可以学习的真实消费者项目 - [贡献指南](CONTRIBUTING.md) — 如何提交补丁 - [安全](SECURITY.md) — 如何报告漏洞 ## 前置条件 你需要： - **Ghidra 11.0 或更高版本**，并内置 PyGhidra（PyGhidra 默认包含在 Ghidra 发行版中） - **Python 3.10+** Decaf 封装了 PyGhidra 并提供 Python 原生的插件开发。有关设置详细信息，请参阅 [PyGhidra 安装文档](https://github.com/NationalSecurityAgency/ghidra/tree/master/GhidraDocs)。 ## 问题所在：Ghidra 的插件发现机制 Ghidra 在 JVM 启动时通过扫描 classpath 中带有 `@PluginInfo` 注解的 `.class` 文件来发现插件。这种字节码级别的扫描发生在任何 Python 代码运行之前，因此 PyGhidra 的 JPype 代理（即没有磁盘编译形式的纯 Python 对象）对 Ghidra 的插件系统是不可见的。你可以使用 PyGhidra 来*编写脚本*控制 Ghidra，但如果没有手写的 Java 模板代码，你就无法将 Python 代码注册为*插件*、服务或分析器。 **Decaf 解决了这个问题**，它会在设置阶段根据你的 Python 元数据生成最简化的 Java 桩类（stub classes），使你的 Python 插件能够被 Ghidra 的字节码扫描器发现。在运行时，Decaf 通过 JPype 反射将这些桩绑定到你的 Python 代码。结果是：无需任何 Java 开发，即可实现完整的插件生命周期（初始化、销毁、事件、服务注册、状态持久化）。 ## 安装 ``` uv pip install pyghidra_decaf ``` ## 快速开始：你的第一个插件 ### 1. 创建一个最简化的插件包 ``` mkdir my-ghidra-plugin && cd my-ghidra-plugin mkdir -p src/my_plugin touch src/my_plugin/__init__.py ``` ### 2. 编写 `src/my_plugin/decaf_init.py` ``` from importlib.metadata import version from pyghidra_decaf.launch import ( DecafExtensionInfo, DecafPluginInfo, PluginType, PluginStatus ) def decaf_init(launcher): return DecafExtensionInfo( name="My Plugin", description="My first Ghidra plugin", author="You", version=version("my-plugin"), plugins=[ DecafPluginInfo( type=PluginType.ProgramPlugin, qualname="MyPlugin", class_name="MyPlugin", status=PluginStatus.STABLE, module_name="my_plugin.plugin", category="Analysis", shortDescription="My first plugin", description="My first Ghidra plugin in pure Python", ) ], java_package="", ) ``` ### 3. 编写 `src/my_plugin/plugin.py` ``` from typing import List, Tuple, Type from pyghidra_decaf.decaf.plugin import DecafProgramPlugin class MyPlugin(DecafProgramPlugin): def init(self): self.tool.setStatusInfo("MyPlugin loaded!") def decaf_load() -> List[Tuple[str, Type[DecafProgramPlugin]]]: return [("my_plugin.plugin.MyPlugin", MyPlugin)] ``` ### 4. 创建 `pyproject.toml` ``` [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [project] name = "my-plugin" version = "0.1.0" description = "My first Ghidra plugin" [project.entry-points."decaf.init"] my_plugin = "my_plugin.decaf_init:decaf_init" [project.entry-points."decaf.load"] my_plugin = "my_plugin.plugin:decaf_load" ``` ### 5. 安装并初始化 ``` pip install -e . pyghidra_decaf_bootstrap ``` ### 6. 启动 Ghidra 并启用插件 ``` pyghidra --gui --install-dir ~/ghidra/ghidra_11_3_2_PUBLIC ``` 出现提示时，在 文件 → 安装扩展 中启用 "My Plugin"。你会在 Ghidra 的状态栏看到 "MyPlugin loaded!"。 有关完整的详细步骤，请参阅 [插件开发指南](docs/index.md)。有关完整的真实案例，请参阅 [mcpyghidra](https://github.com/nightwing-us/mcpyghidra) — 这是一个已发布且正在积极使用的 Decaf 插件。 ## 使用 pyghidra-decaf 的项目 - **[mcpyghidra](https://github.com/nightwing-us/mcpyghidra)** — 一个 Model Context Protocol (MCP) 服务器，将 Ghidra 逆向工程工具暴露给 LLM 客户端。 用 pyghidra-decaf 构建了什么吗？欢迎提交 PR 将其添加到这里。 ## 开发说明 本项目使用 `uv` 进行 Python 环境和包管理。 ### 设置开发环境 ``` # 如果尚未安装，请安装 uv curl -sSf https://astral.sh/uv/install.sh | bash # 创建 virtual environment 并安装 dev dependencies uv venv uv pip install -e ".[dev]" ``` ### 运行测试 ``` uv run pytest ``` ### 类型检查 ``` uv run mypy ``` ### 代码检查与格式化 ``` uv run ruff check src tests uv run ruff format src tests ``` ### 构建包 ``` uv build ``` ## 尚未支持的功能 Decaf 目前支持 `Plugin` 和 `ProgramPlugin` 扩展点，使你能够编写： - 可停靠的 UI 面板（通过 `ComponentProvider` 接口） - 插件生命周期钩子（初始化、销毁、事件、状态持久化） - 服务注册和事件订阅 **尚未支持（欢迎提交补丁）：** - `Analyzer`（参与自动分析） - `Loader`（文件格式支持） - `Exporter`（自定义导出格式） - `FieldFactory`（自定义 Listing 列） - 自定义 `PluginEvent` 子类 对于超出此范围的使用场景，请考虑手写 Java 插件或使用原生的 PyGhidra 脚本。有关详细的功能对比，请参阅 [架构指南](docs/gap-analysis-ghidra-pyghidra-decaf.md)。 ## 许可证 Apache-2.0 — 详情请参阅 [LICENSE](LICENSE)。 版权所有 © 2026 Nightwing Group, LLC.

标签：Ghidra, PyGhidra, Python, SOC Prime, 云资产清单, 代码分析, 凭证管理, 开发工具, 插件开发, 无后门, 逆向工具, 逆向工程