Recurse

面向智能体的逆向工程环境——一款 Ghidra 级别的桌面应用，秉承 “面向逆向工程的 Cursor”理念。基于 Tauri 2（React + TypeScript 前端）构建， 底层是可插拔的分析后端。默认是纯 Rust 原生引擎——无 外部进程、无 copyleft 依赖、通过 Capstone 支持多架构。你也可以通过 r2（radare2）运行分析：安装它，将其选为引擎，整个应用—— 智能体工具和 UI——都会改为驱动它。智能体工具和 UI 均与后端无关—— 参见 docs/backends.md。

仓库布局

根目录为 Cargo 工作区；桌面应用是其中的一个包。

tauri/                   桌面应用（Tauri + React）
  src/                     React 前端
  src-tauri/               Tauri Rust 后端（引擎会话、智能体接线）
  package.json             应用脚本（Vite、Vitest、Tauri CLI）
crates/
  recurse-agent/              智能体框架：LLM 循环、工具运行时、SQLite 记忆
  recurse-static/          静态分析：ELF/PE/Mach-O 解析、多架构反汇编、
                           CFG 与交叉引用恢复、引擎接缝
  recurse-vtil/            受 VTIL 启发的去混淆/去虚拟化 IL、提升器、优化器
  recurse-mcp/             基于引擎的独立无头 MCP 服务器（stdio）——无 Tauri、无 IDA
  recurse-debug/           跨平台调试器（ptrace/Mach/Win32、断点、单步执行）
  recurse-eval/            无头评估框架（YAML 配置的分层）
justfile                 两部分的统一入口

recurse-agent 只是智能体；静态分析位于 recurse-static，调试器 位于 recurse-debug，因此智能体不会引入它用不到的 系统代码。没有任何 crate 依赖 Tauri，每个都能独立构建/测试； recurse-eval 以无头方式驱动智能体。它们都是工作区成员，因此一个 Cargo.lock 和一个 target/ 即可覆盖整个仓库。

功能特性

• Cursor 风格工作区：函数列表、反汇编/字符串/导入标签页、CFG 图， 以及聊天智能体侧边栏（用 Chat 按钮或 Ctrl+L 切换）
• 侦察页面：二进制信息、MD5/SHA1/SHA256/CRC32 哈希、熵、链接库、 自包含的加固报告（RELRO / PIE / NX / canary / FORTIFY / RPATH—— 无需外部 checksec），以及分析计数
• 从列表中重命名函数（双击或 ✎ 按钮）；名称持久化到 SQLite，并显示在函数列表、反汇编注释以及智能体面前
• 有据可依的智能体：每个地址都是可点击对象（函数列表、图节点、 交叉引用、反编译器注释）——而非可能被模型幻觉出来的粘贴文本
• 对任意二进制文件（包括无扩展名文件）的实时分析会话
• SQLite 中的持久化项目记忆，带 FTS5/BM25 检索——重命名、发现 和笔记在 /clear 和重新打开后依然保留，并为下一次会话提供种子
• 无头核心（recurse-agent），带逐轮调试追踪；同一智能体循环 在 UI 和评估框架中运行
• 由 OpenAI 兼容端点（默认 OpenRouter）支持的 LLM 智能体，带 模型选择器；直接驱动会话（反汇编、交叉引用、字符串、导入、反编译）
• 使用 Tailwind CSS v4 + shadcn/ui 构建的暗色优先 UI
• lift 操作：将函数提升为 VTIL 风格的去混淆 IL，并对其运行 整例程传播/折叠/死代码消除/分支解析 遍——当反汇编看起来像 VM 分发器或 不透明谓词链时很有用（参见 docs/vtil-lift.md）
• 原生反编译器：decompile 从同一 recurse-vtil 流水线渲染类 C 伪代码（if/while 结构化、全指令覆盖）——无需外部工具，无需 r2
• 独立的 recurse-mcp 服务器：通过 MCP stdio 为任何 支持 MCP 的智能体（Claude Code、Cursor、Claude Desktop 等）提供同一 ——无 Tauri、无 IDA 席位、无 Python 桥接（参见 ）

分析后端

分析通过单一的 Engine trait（crates/recurse-static/src/engine.rs）进行，因此 引擎是一种选择，而非硬依赖：

• native（默认）——纯 Rust 的 ELF/PE/Mach-O 解析和多架构反汇编 （object + capstone）：x86/x86-64、ARM、AArch64、MIPS、PowerPC、RISC-V、SPARC、SystemZ、 M68K、BPF。无子进程、无外部工具、构建中无 LGPL。包含反编译器 （recurse-vtil 的提升 → 优化 → 结构化流水线——参见 docs/vtil-lift.md）以及用于 VTIL 风格去混淆的 lift 操作。
• r2（radare2）——作为可选替代方案受支持，适用于想要其自身 更完整反编译器或原始控制台的安装。安装 r2 并将其选为引擎；它作为 独立进程运行，从不与 Recurse 链接或捆绑。

通过设置菜单、RECURSE_BACKEND 环境变量或存储的 配置来选择。智能体获得一个后端中立的 analyze 工具（functions、disasm、graph、 lift、decompile、xrefs、strings、imports、info，外加用于引擎控制台的 raw）—— 过滤为活动引擎实际支持的操作，因此 raw（原生无控制台）仅在可用时 才会被公布。UI 消费规范结果类型，而非任何引擎的 JSON。 关于该 trait、crate 选择以及许可理由，参见 docs/backends.md。 打开大型二进制文件很快，因为分析是惰性的——发现过程以低成本索引 函数，基本块仅在查看函数时才解码；参见 docs/lazy-analysis.md。

为什么不直接用 MCP-to-IDA / 在 Claude Code 里莽一把？

把 MCP 服务器钉到 IDA/Ghidra 上，或者把反汇编粘贴到 CLI 智能体里， 对 5 个函数的 CTF 有效，但在真实二进制文件上就会崩溃。Recurse 是一个 专门构建的环境，而非聊天机器人包装器：

• 二进制世界模型，而非文本抓取。 函数、交叉引用、字符串和 CFG 是智能体和 UI 共享的一等状态。无需每轮重新解析 pdF 转储到上下文中，也不会有凭空捏造的 0x401023。
• 验证 > 生成。 在逆向工程中没有 npm test——验证是 视觉化的。智能体重命名会立即传播到函数列表、图和反编译 中，因此人类可以一键确认或拒绝。
• 为规模而构建。 真实恶意软件有 1 万个函数。按需驱动的工具 + 持久化记忆胜过转储完整反编译直到上下文 OOM。
• 可智能体化的引擎。 可脚本化、可管道化的引擎意味着智能体可以运行 100 轮、分叉、 重置和差异比较——而且你确实可以发布它。默认原生引擎完全不需要外部 工具。
• 默认恶意软件安全。 本地优先、自带密钥/OpenRouter 路由，以及通往 离线模型的路径——不会强制将样本外泄到云端聊天机器人。

先决条件

1. 核心工具链

验证：

node --version && npm --version && rustc --version && cargo --version

2. 分析引擎

默认的 native 引擎是纯 Rust——无需安装任何东西。若要改用 r2（radare2） 作为分析引擎，请安装它并选择它（设置菜单，或 RECURSE_BACKEND=r2）；Recurse 会驱动你 PATH 上的 r2 二进制文件。r2 是可选的， 构建从不要求它，也从不随 Recurse 分发——请自带安装。

3. Tauri Linux 系统依赖

Debian/Ubuntu/Pop!_OS：

sudo apt update
sudo apt install -y libwebkit2gtk-4.1-dev build-essential \
  curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

其他发行版：遵循官方 Tauri 先决条件。

4. 反编译器

两个引擎都提供一个：native 通过 recurse-vtil 渲染伪代码（提升 → 优化 → 结构化——参见 docs/vtil-lift.md）， 无需安装；r2 在其插件安装后可提供它自己更完整的反编译器。

构建

应用依赖位于 tauri/；Rust 来自工作区根目录。just 包装了 两者（参见 just --list），或者直接驱动它们。

开发

just dev
# 等价于：cd tauri && npm install && npm run tauri dev

这会启动 Vite 开发服务器并启动 Tauri 窗口。首次编译需要 一段时间（Rust 构建）；后续编译很快。

生产二进制文件

just build
# 等价于：cd tauri && npm run tauri build

打包产物位于 target/release/bundle/（工作区 target）：

• Linux 的 .deb / .rpm / .AppImage
• 独立二进制文件位于 target/release/recurse

在 Arch 和其他滚动发行版上，AppImage 步骤需要一次性本地修复 （上游 linuxdeploy 落后于发行版工具链）——参见 docs/linux-appimage-build.md。

仅前端（无桌面外壳）

just preview
# 等价于：cd tauri && npm run build && npm run preview

质量检查

just lint        # cargo clippy --workspace + eslint
just fmt         # cargo fmt --all + prettier
just fmt-check   # 验证而不写入
just test        # cargo test --workspace + vitest

等价的直接命令：根目录下的 cargo clippy --workspace --all-targets、 cargo test --workspace；tauri/ 内的 npm run lint / npm run format / npm run build。

评估

智能体针对 crackme 分层进行无头评估（参见 crates/recurse-eval/README.md）。分层为 YAML： 对数据集的选择过滤器，或冻结的 hexid 列表，外加运行旋钮。

just eval-fetch   # 下载该分层的二进制文件
just eval-test    # 框架自测（无需 API 密钥，无 LLM 调用）
just eval-run     # 运行该分层——执行评估 YAML 的唯一方式

eval-run 是一个二进制文件，而非测试，因此 cargo test 从不在 智能体上花费金钱或时间。端点和密钥放在 crates/recurse-eval/.env（复制 .env.example）。 每次运行写入 target/eval-traces/<tier>/<backend>/run.log（完整叙述） 外加每个任务一个 <hexid>.json，包含完整的逐轮对话。后端 （native 或 r2）可按运行选择——参见评估 README。

智能体 LLM

智能体聊天面板可运行在任何 OpenAI 兼容端点上。从应用内的 Model & Provider 对话框配置 API 密钥、基础 URL 和模型（持久化在 ~/.recurse/recurse.db），或通过环境变量：

# 托管提供商（默认）
export RECURSE_LLM_API_KEY=sk-or-...   # 或 OPENROUTER_API_KEY
export RECURSE_LLM_ENDPOINT=https://openrouter.ai/api/v1/chat/completions  # 可选
export RECURSE_LLM_MODEL=openrouter/auto  # 可选

本地模型 / 自定义基础 URL

将智能体指向任何本地或自托管的 OpenAI 兼容服务器——Ollama、LM Studio、llama.cpp 的 llama-server、vLLM、text-generation-webui 或远程网关。 在对话框中设置 Base URL（裸基础 URL 或完整的 /chat/completions 路由均可），并从该服务器的目录中选择模型，或直接输入模型 id （llama3.1:8b、qwen2.5-coder 等）：

export RECURSE_LLM_ENDPOINT=http://localhost:11434/v1   # Ollama
export RECURSE_LLM_MODEL=llama3.1:8b
export RECURSE_LLM_API_KEY=           # 本地通常不需要

本地端点无需 API 密钥：当密钥为空时，请求发送时不带 Authorization 头，模型列表从端点自身的 {base}/models 读取。自定义端点被视为无需密钥即已配置，因此 聊天可开箱即用地针对本地服务器工作。

没有凭据时，它会回退到 echo 客户端，以便接线保持可演练。

智能体看到实时二进制上下文（架构、位数、类型），并可通过会话驱动完整的分析 表面（反汇编、交叉引用、字符串、导入、反编译）。

许可证

Apache-2.0 — © 2026 Aayush Khanna