ghidralens

GhidraLens

在 AI 客户端中呈现 Ghidra。点击符号即可重命名，点击调用即可跟踪。

迄今为止，每个 Ghidra MCP 服务都只返回文本。模型能读取它，你却无法浏览其中内容。GhidraLens 会以交互式视图返回相同的分析结果——该视图基于 MCP Apps （io.modelcontextprotocol/ui）构建，这是一个让服务能够将真实 HTML 内容直接呈现在对话中的扩展。

你和模型看到的是同一个实时程序。点击变量即可重命名，模型下一次反编译时就会看到新名称。

这是一张真实截图：where.exe 经 Ghidra 反编译后，每个标识符都带有其来源地址。

---

你将获得

视图	功能
反编译器	将 Ghidra 的 C 输出呈现为实时令牌流——每个标识符都带有其地址和类型。点击局部变量即可重命名，点击调用即可跟踪。侧边栏显示调用者、被调用函数和变量。
函数浏览器	二进制文件中的所有函数，支持按地址、名称、大小或调用者数量筛选和排序。点击一行即可反编译该函数。
调用图	左侧是调用者，右侧是被调用函数，中间是你查询的函数。点击任意节点即可将其居中。

函数浏览器

调用图

总共有 10 个工具。3 个用于打开视图，其余用于查询和写入，其中有 2 个模型看不到——它们只用于响应视图中的点击操作。

工作原理

  MCP client  ──stdio──▶  server/  ──HTTP──▶  bridge/  ──JPype──▶  Ghidra (JVM)
  (Claude,                 TypeScript         PyGhidra            program stays
   Cursor, …)              MCP server         session             resident
       ▲
       │  ui:// HTML in a sandboxed iframe
       └──  ui/  three self-contained views

桥接程序有意作为独立的长期运行进程。Ghidra 的自动分析是耗时步骤，而且只会执行一次。以下是在一个 64 KB 的 Windows 系统实用程序（198 个函数）上测得的数据：

首次打开并进行分析	25 s
重新打开同一二进制文件	0.3 s
反编译一个 2 KB 的函数	0.4 s
87 个节点的调用图	< 0.1 s

重启 MCP 服务或客户端后，已分析的程序仍会保留。

安装

前置条件： Ghidra 11.3+、JDK 21+、Python 3.9–3.13（不包括 3.14 — JPype 目前还没有对应的 wheel）和 Node 20+。请参阅 bridge/setup.py.md — Python 端比较棘手，该文件涵盖了所有可能出错的情况。如果未设置 JAVA_HOME，GhidraLens 会为你查找 JDK，可解决常见的“已安装 Java，但 shell 尚未重启”问题。

git clone https://github.com/hellosverre/ghidralens
cd ghidralens
npm install
npm run build

然后，在你想查看的二进制文件上启动桥接服务：

python bridge/serve.py --binary /path/to/target.exe

它会打印一个令牌。将令牌和已构建服务的路径加入 MCP 客户端配置：

{
  "mcpServers": {
    "ghidralens": {
      "command": "npx",
      "args": ["-y", "ghidralens"],
      "env": {
        "GHIDRALENS_BRIDGE_URL": "http://127.0.0.1:8799",
        "GHIDRALENS_TOKEN": "paste-the-printed-token-here"
      }
    }
  }
}

如果是从克隆的仓库运行？将 command 指向 node，并将 args 指向 /absolute/path/to/ghidralens/server/dist/index.js。

然后向客户端提问：“反编译处理许可证验证的函数”。

该项目也已列入官方 MCP Registry，名称为 io.github.hellosverre/ghidralens。

手动编辑配置？ 请先完全退出客户端，包括退出系统托盘图标。Claude Desktop 会将自己的 claude_desktop_config.json 副本保存在内存中，并在退出时覆盖你的修改，因此，在客户端运行时所做的编辑会在下次重启时悄然消失。通过“设置” → “开发者” → “编辑配置”进行编辑，可完全避免此问题。

工具

工具	对谁可见	渲染内容
open_binary	模型	—
program_info	模型	—
decompile	模型 + 视图	反编译器
list_functions	模型 + 视图	函数浏览器
call_graph	模型 + 视图	调用图
find_strings	模型	—
xrefs_to	模型 + 视图	—
rename_symbol	模型 + 视图	—
add_comment	仅视图	—
save_program	模型	—

add_comment 刻意不向模型公开。可见性是 MCP Apps 区分“Agent 可以执行此操作”和“用户可以点击执行此操作”的方式；不把写入工具列入模型的工具清单，既能让清单保持精简，也能防止模型擅自重命名内容。

重命名和注释会保留在内存中，直到 save_program 将它们写入 Ghidra 项目。之后，它们会像其他编辑一样显示在 Ghidra GUI 中。

无需 Ghidra 即可开发视图

npm run dev:ui
# open http://localhost:5173/dev/harness.html

ui/dev/harness.ts 是一个真正的 MCP Apps 宿主 — 它会在 iframe 中运行 SDK 的 AppBridge，因此 ui/initialize 握手、初始的 ui/notifications/tool-result，以及每次点击触发的 tools/call，都会通过真实的 postMessage JSON-RPC 进行传递。右侧有消息跟踪记录和宿主主题切换开关，因为视图必须在两种主题下都显示正常。

可在工具栏中切换两种数据源：

• fixtures — 无需 Ghidra，也无需安装任何内容
• live bridge — 代理到正在运行的桥接服务，让你基于真实的分析程序进行开发

请先使用 live，再决定是否信任任何内容。Fixtures 内容规整；真实输出则可能是一个有 56 个局部变量、调用图包含 87 个节点的 400 行函数，而布局问题往往就在这种情况下出现。

在本地模型上运行

逆向工程正是人们通常不愿发送给托管模型处理的工作，因此 agent/ollama-agent.mjs 是一个小型 MCP 宿主，可通过 Ollama 运行 GhidraLens。无需 API 密钥，任何内容都不会离开本机。

OLLAMA_MODEL=qwen3:14b node agent/ollama-agent.mjs "what does this binary do?"

它会遵循 _meta.ui.visibility，因此仅限应用使用的工具会继续对模型隐藏 — 这与图形客户端执行的隔离方式相同。约 9B 的模型足以通过 find_strings 和 list_functions 熟悉程序；14B 模型在阅读反编译后的 C 代码方面明显更出色。

测试

套件	需要 Ghidra	覆盖范围
node server/smoke.mjs	否	MCP 接口：工具、ui:// 资源、工具可见性，以及没有桥接服务时的优雅失败
python bridge/test_serve.py	否	桥接服务身份验证、CSRF 拒绝、路由、输入验证
python bridge/test_session.py	是	每项 Ghidra 调用：分析、缓存、反编译器令牌、导入、重命名、写入
node server/live.mjs	是（桥接服务正在运行）	整个调用链，以及每个负载都符合视图索引所需的结构

前两项是 CI 可以运行的测试。修改 bridge/session.py 后，test_session.py 才是关键测试——它是唯一能证明 Ghidra API 调用正确的测试，而且编写当天就发现了 3 个真实错误。

容器化

Dockerfile 会为希望自行启动服务的客户端或注册表构建服务端和视图。有一点需要注意：

CMD ["node", "server/dist/index.js"]     # correct
CMD ["npm", "run", "start"]              # breaks the protocol

使用 stdio 的 MCP 服务会在 stdout 上通过 JSON-RPC 通信，而 npm run / pnpm run 会先在那里打印脚本横幅：

> [email protected] start
> node server/dist/index.js

这些行会在握手前进入数据流，导致客户端在初始化过程中途放弃连接。这个问题不容易从症状看出来——容器构建成功、启动后干净退出，而客户端只报告没有工具——因此值得避免。直接调用 node。

实际分析仍需要在主机上运行桥接服务：容器内的 127.0.0.1 指向容器本身，因此请将 GHIDRALENS_BRIDGE_URL 指向 host.docker.internal 或实际地址。

安全

桥接服务仅绑定到 127.0.0.1，要求在 X-GhidraLens-Token 中提供每次运行的令牌，并拒绝任何携带 Origin 或 Referer 标头的请求——因此，浏览器中打开的网页无法访问反编译器。它不支持多用户，也不适合对外公开；--host 只接受回环地址。

分析二进制文件不会执行它，但 Ghidra 可以轻松打开恶意软件。请采取与其他逆向工程工作相同的隔离措施。

许可证

MIT。