pyghidra-lite

pyghidra-lite

面向基于 Ghidra 的逆向工程的高效 MCP 服务。支持分析 ELF、Mach-O 和 PE 二进制文件，并支持 Swift、Objective-C 和 Hermes——可反编译、反汇编、追踪调用和值流、恢复数据类型，并将地址映射回文件偏移量。可在 Linux、macOS 和 Windows 上运行；随附 Claude Code 插件及逆向工程技能。

简而言之：精简且以安全为先的 Ghidra MCP。默认采用只读模式——分析工具绝不会修改二进制文件或服务配置（配置在进程生命周期内保持不变）。唯一可写入的工具 annotate（重命名／添加注释／修改原型）需要显式启用（--allow-write），并且必须由人工确认：每项更改在提交前都必须由你通过 MCP 征询提示批准；如果客户端无法发起询问，则操作会安全失败。你可以获得一个能够持久保存分析结果的分析 Agent——但须接受监督，且不必牺牲只读安全保障。

快速开始

1. 前置条件

需要 64 位 JDK 21+ 和 Ghidra 11.x 或 12.x（已使用 Ghidra 12.1.2 和 JDK 21 测试）。

# macOS
brew install openjdk@21
brew install ghidra

# Ubuntu/Debian
sudo apt install openjdk-21-jdk
# Download Ghidra from https://ghidra-sre.org

# Arch Linux
sudo pacman -S jdk21-openjdk
yay -S ghidra

通过 Homebrew（brew install ghidra）安装，或安装在 /opt/ghidra 或 ~/ghidra 的 Ghidra 会被自动检测到。安装在其他位置时——包括任何 Windows 安装——请将 GHIDRA_INSTALL_DIR 指向解压后的 ghidra_<version>_PUBLIC 文件夹。

2. 安装 — 任选一种方式

Claude Code 插件（推荐用于 Claude Code）

一步安装 MCP 服务和逆向工程技能；安装时会询问你的 Ghidra 目录。需要将 uv 放在 PATH 中。

/plugin install pyghidra-lite --marketplace johnzfitch/pyghidra-lite

任意 MCP 客户端

安装软件包，然后将其添加到客户端（Claude Code：项目中的 .mcp.json 或 ~/.claude.json；其他客户端：请参阅 MCP 配置）。

pip install pyghidra-lite

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite"
    }
  }
}

3. 检查环境

pyghidra-lite doctor   # Ghidra, JDK, decompiler, project dir, locks; exits 1 on problems

提示

未通过 shell 安装的插件用户，可运行 uvx pyghidra-lite doctor 进行同样的检查。

4. 开始使用

You: Analyze the binary at /path/to/binaries/app

Claude: [calls load, info, code...]

安装

Claude Code 插件

安装 MCP 服务（通过 uvx 运行，因此必须将 uv 添加到 PATH），以及 pyghidra-lite:reverse-engineering 工作流技能，并询问你的 Ghidra 目录、缓存目录、可选的路径限制，以及是否允许使用 annotate：

/plugin install pyghidra-lite --marketplace johnzfitch/pyghidra-lite

• 对于低于 2.1.275 的 Claude Code 版本，先运行 /plugin marketplace add johnzfitch/pyghidra-lite， 然后运行 /plugin install pyghidra-lite@pyghidra-lite。
• 插件会锁定一个确切的软件包版本，并在每个会话中运行一个服务。更新插件后，运行 /reload-plugins（或启动新会话）以切换到新版本。
• 之后可在 /config 中更改设置。

警告

如果你还在 .mcp.json 或 ~/.claude.json 中手动添加了 pyghidra-lite 条目，请将其移除 — 否则每个工具都会显示两次。

PyPI（推荐）

pip install pyghidra-lite

Arch Linux（AUR）

yay -S python-pyghidra-lite

从源代码安装

git clone https://github.com/johnzfitch/pyghidra-lite
cd pyghidra-lite
pip install -e .

MCP 配置

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "uvx",
      "args": ["pyghidra-lite"]
    }
  }
}

uvx 会在首次运行时自动从 PyPI 安装 pyghidra-lite。Ghidra 会自动检测；如有需要，可在 env 中设置 GHIDRA_INSTALL_DIR：

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "uvx",
      "args": ["pyghidra-lite"],
      "env": {
        "GHIDRA_INSTALL_DIR": "/path/to/ghidra"
      }
    }
  }
}

Claude Code

在项目中创建 .mcp.json（或在 ~/.claude.json 中创建全局配置）：

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite"
    }
  }
}

直接模式（跳过代理）

用于单会话或调试时，可直接运行服务：

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite",
      "args": ["serve"]
    }
  }
}

指定 Ghidra 路径

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite",
      "args": [
        "serve",
        "--ghidra-dir", "/path/to/ghidra"
      ]
    }
  }
}

限制为特定路径

默认情况下，pyghidra-lite 可以从任何路径加载二进制文件（MCP 客户端负责处理权限）。使用 --restrict-path 可限制访问范围：

{
  "mcpServers": {
    "pyghidra-lite": {
      "command": "pyghidra-lite",
      "args": [
        "serve",
        "--restrict-path", "/home/user/binaries",
        "--restrict-path", "/opt/targets"
      ]
    }
  }
}

共享 HTTP 传输（网络访问）

HTTP/SSE 传输是共享的，并会启用 DNS 重绑定保护（Host/Origin 验证）。绑定到非回环地址时，还必须同时指定 --restrict-path 和 bearer 令牌：

pyghidra-lite serve -t streamable-http --host 0.0.0.0 \
  --restrict-path /opt/targets \
  --auth-token "$PYGHIDRA_LITE_AUTH_TOKEN" \
  --allowed-host re.example.com:8000   # if fronted under another hostname

之后，客户端在每个请求中都要发送 Authorization: Bearer <token>。如需远程访问，请在反向代理处终止 TLS。

工具（9 个）

pyghidra-lite 提供 8 个只读分析工具，以及 1 个可选择启用的写入工具；所有工具都会自动检测文件格式（ELF/Mach-O/PE）和语言（Swift/ObjC/Hermes）：

工具	用途	关键参数
load	导入并分析二进制文件	path、profile?、fresh?、bootstrap?、bootstrap_mode?
delete	移除二进制文件并取消任务	name
binaries	列出二进制文件及任务状态	jobs?、rank_sources?
info	二进制文件概览	binary、detail?（summary/full/format/sections/entropy）
functions	列出/搜索函数、导入项、导出项	binary、query?、type?（all/swift/objc/imports/exports/types/got/dylibs）、limit?
code	反编译、反汇编、p-code、字节	binary、target、what?（decompile/asm/pcode/bytes/string）、cfg?
xrefs	引用和调用图	binary、target、direction?、depth?、diff?
search	查找字符串、字节、符号、数据类型	binary、query、type?（strings/symbols/bytes/all/blob/extract/types）、mode?、bg?
annotate 🔒	重命名/添加注释/设置原型	binary、target、action、name?/comment?/prototype?

🔒 annotate 是唯一会写入数据的工具。除非启动服务时使用 --allow-write，否则该工具处于禁用状态；并且每次更改提交前都需要交互式确认（MCP elicitation）——无法确认的客户端只能获取预览。请参阅写回。

示例

# Import and analyze
load("/path/to/binary", profile="fast")

# Version-track from a prior build, including synthetic IDs for unnamed code
load("/path/to/new.bin", profile="deep", bootstrap="old.bin", bootstrap_mode="all")

# Get overview with full triage
info("mybinary", detail="full")

# List Swift functions
functions("mybinary", type="swift")

# Decompile with CFG
code("mybinary", "main", cfg=True)

# Search strings in background
search("mybinary", ["password", "api_key"], bg=True)

# Get cross-references
xrefs("mybinary", "malloc", depth=2)

# Value flow: SSA p-code, grouped by basic block; each value is defined once
code("mybinary", "parse_header", what="pcode")
# ...or just where one argument's value goes (forward slice; ~10x smaller on real code)
code("mybinary", "parse_header,param_2", what="pcode")

# Raw bytes plus where they live in the file (for patching)
code("mybinary", "0x4011a0,64", what="bytes")   # -> hex, ascii, file_offset, block

# Recovered struct layouts / enums / typedefs
search("mybinary", "sockaddr", type="types")

自动检测

所有工具都会自动检测：

• 格式：ELF、Mach-O、PE
• 语言：Swift、Objective-C、Hermes/React Native
• 运行时：Bun、Node.js、Electron、PyInstaller

使用 type 和 detail 参数可访问特定于格式/语言的功能。

引导模式

• bootstrap_mode="named"：只传输有意义的源名称（默认）。
• bootstrap_mode="all"：在传输过程中，也为源 FUN_* 函数分配稳定的合成标签。这适用于大型版本间引导工作流，此类场景中唯一性比语义更重要。

写回

默认情况下，pyghidra-lite 为只读模式——没有工具会修改你的二进制文件。若要让 Agent 持久化调查结果（重命名函数、添加注释、修正原型），请使用 --allow-write 启动服务：

pyghidra-lite serve --allow-write          # or PYGHIDRA_LITE_ALLOW_WRITE=1

然后即可使用 annotate 工具：

annotate("mybinary", target="FUN_00401000", action="rename", name="parse_header")
annotate("mybinary", target="parse_header", action="comment", comment="validates the v2 header")
annotate("mybinary", target="parse_header", action="prototype", prototype="int parse_header(char *buf, int len)")

每次调用都需要人工确认：服务会发送 MCP elicitation 提示词，显示确切的 old -> new 变更，只有在你接受后才会提交。如果服务启动时未使用 --allow-write，该工具会拒绝操作；如果你的 MCP 客户端不支持 elicitation，该工具会返回包含 applied: false 的预览，且不会写入任何内容（默认拒绝）。确认后的变更会在单个 Ghidra 事务中写入，并保存到磁盘上的项目中。

审计日志。 由于 MCP elicitation 最终依赖客户端（自主的“自动批准”客户端可以自行确认），每次写入都会记录在项目旁的 annotate_audit.jsonl 中；每次拒绝或失败的尝试也会记录在内。每行都会记录 old -> new，因此该日志既是问责记录，也是撤销日志；如果条目激增，就说明自动 Agent 正在反复操作，此外，随着写入量增加，服务也会发出提示（ctx.warning）。该日志采用默认拒绝并强化保护的设计：变更应用前会先记录（如果无法写入日志，就不会提交变更）；文件创建时权限为 0o600，并使用 O_NOFOLLOW 打开（拒绝符号链接日志）；日志还会按大小轮换，避免无限增长。

分析配置

配置	用途
fast	快速初步分析，停用 20 个速度较慢的分析器（默认）
default	均衡模式，执行完整的 Ghidra 分析
deep	对混淆代码进行彻底分析

服务默认使用 fast，以满足 MCP 超时限制。需要时，可使用 load(fresh=True) 执行更深入的分析：

# Default import uses fast profile
load("/path/to/binary")

# Re-analyze with deep profile
load("/path/to/binary", profile="deep", fresh=True)

Token 效率

pyghidra-lite 专为尽量减少 Token 用量而设计：

• 紧凑 JSON——序列化结果不带缩进，每次调用返回一个文本块 （实测：在一个示例二进制文件的所有工具中，字符数比美化打印的输出少 33%）
• 不含空字段——省略 false 标志、空标签列表和 null 上下文
• 切片而非转储——code("func,var", what="pcode") 只返回值流入的运算 （在 ws2_32.dll 的 WSAStartup 上：约 1.9K 个字符，而完整列表约 22K 个字符）
• 默认紧凑输出——functions(binary, type="all") 返回最简 {name, addr} 键值对
• 按需获取详情——仅在需要时使用 info(detail="full")、code(cfg=True) 或更丰富的 type/what 模式
• 进度报告——大型导入每 10% 或每 60s 报告一次进度
• 字符串截断——长字符串限制为 500 个字符

架构

默认情况下，pyghidra-lite 会作为轻量级 stdio 代理（约 10MB）运行，并将请求转发到持久运行的共享 HTTP 后端（约 500MB JVM）。多个会话共享同一个 JVM，而不是各自启动一个。

Claude Code session 1 ──stdio──> proxy ──┐
Claude Code session 2 ──stdio──> proxy ──┼──HTTP──> shared backend (1 JVM)
Claude Code session 3 ──stdio──> proxy ──┘        localhost:19101

代理会在首次使用时自动启动后端，并通过文件锁和端口检查防止并发代理重复启动后端。后端会持续运行，直到执行 pyghidra-lite stop；空闲 30 分钟的二进制文件会从内存中卸载（最近使用的 2 个会保留在内存中），需要时会从磁盘透明地重新加载。

重要

代理会复用当前正在监听的后端，无论其版本为何。升级 pyghidra-lite 后，请运行 pyghidra-lite stop，以便下一个会话启动新代码。（serve 和 Claude Code 插件会在每个会话中运行一个服务器，因此不会 遇到此问题。）

命令	功能
pyghidra-lite	Stdio 代理（默认）——自动启动后端
pyghidra-lite serve	直接运行 stdio 服务器（每个会话 1 个 JVM）
pyghidra-lite serve -t streamable-http	手动启动持久运行的 HTTP 后端
pyghidra-lite stop	停止共享后端
pyghidra-lite doctor [--json]	诊断环境（只读；如果分析会失败，则退出码为 1）

设置 PYGHIDRA_LITE_NO_AUTOSTART=1 可禁用自动启动（适用于 systemd）。

配置

每项设置都可以通过 serve 标志或环境变量配置（便于在 MCP env 块中使用）：

变量	标志	默认值	用途
GHIDRA_INSTALL_DIR	--ghidra-dir	自动检测	Ghidra 安装目录
PYGHIDRA_LITE_PROJECT_DIR	--project-dir	见下文	分析缓存
PYGHIDRA_LITE_RESTRICT_PATHS	--restrict-path（可重复）	不限制	仅加载这些目录下的二进制文件（环境变量使用 OS 路径分隔符）
PYGHIDRA_LITE_ALLOW_WRITE	--allow-write	关闭	启用 annotate（仍需人工确认）
PYGHIDRA_LITE_DEFAULT_PROFILE	--profile	fast	默认分析配置
PYGHIDRA_LITE_TOOL_TIMEOUT	—	300 秒	每次调用的时间上限，防止卡住的 JVM 调用使客户端无限期等待；0 表示禁用
PYGHIDRA_LITE_AUTH_TOKEN	--auth-token	无	HTTP 传输使用的 Bearer token（非回环地址必需）
PYGHIDRA_LITE_NO_AUTOSTART	—	关闭	代理绝不启动后端
—	--evict-after / --min-loaded	30 分钟 / 2	卸载空闲二进制文件以释放内存
—	--autopurge-days	关闭	删除 N 天内未打开的项目

多 Agent 支持

每个二进制文件都有自己的 Ghidra 项目，支持：

• 并行分析不同的二进制文件
• 在多个 Agent 间共享结果
• 持久化分析（重启后仍然保留）
• 内容寻址存储（相同的二进制文件 = 相同的分析结果）

项目存储在 ~/pyghidra-lite/projects/（Windows：%LOCALAPPDATA%\pyghidra-lite\projects\）， 或者，如果该目录已存在，则存储在旧版 0.8 之前的位置 ~/.local/share/pyghidra-lite/projects/。 可通过 --project-dir 或 PYGHIDRA_LITE_PROJECT_DIR 覆盖。Ghidra 12+ 不接受路径中包含以 . 开头的 路径组件，因此旧版 ~/.local 目录仅适用于 Ghidra 11.x — pyghidra-lite doctor 会对此发出提示。

链接

• PyPI 软件包
• AUR 软件包
• MCP Registry
• 问题跟踪器
• 贡献指南
• 安全策略
• 变更日志

许可证

MIT