DatanoiseTV/revenant

# revenant [](LICENSE) [](https://github.com/DatanoiseTV/revenant/releases) [](https://github.com/DatanoiseTV/revenant/pkgs/container/revenant) [](pyproject.toml) **让被遗弃的硬件和软件重获新生。** revenant 是一个由 LLM 驱动、针对厂商不再支持的固件和二进制文件的自动化逆向工程引擎。只需将其指向一个固件镜像或编译好的程序，它就能识别目标、重构其结构，并生成维持设备运行所需的产出物：引脚图、设备树、外设清单、可编译的自定义固件项目、恢复的函数名，以及（可选的）净室开源重写实现。 完全在 Docker 中运行。挂载你的工作文件夹即可开始。

_{Live TUI (scales to your terminal): the stage DAG runs on the left while results fill in on the right — SoC, peripherals, external components (sensors, port expanders, rotary encoders, displays, LED strips, audio DACs) and the pin map. Timings are from a real claude-code run (agentic identification ~96 s / 11 turns over radare2 MCP; full pipeline ~3 min); GIF playback is accelerated. The on-screen data is an illustrative synthetic target, not a real device.}

## 合法与道德使用 — 请先阅读本节 revenant 专为**合法、经授权的**逆向工程而构建： - **修复和保存**已被厂商遗弃的硬件。 - **互操作性** — 让你自己的设备协同工作。 - 在你拥有或被授权测试的系统上进行**安全研究**。 - 计算机历史的教育和存档。 在许多司法管辖区，这些是受保护或被允许的活动（例如，互操作性和维修豁免）。它们也是本项目*唯一*的用途。 **请勿使用 revenant 进行以下操作：** - 侵犯版权或盗取商业机密。revenant 重构*行为和接口*是为了实现互操作性；它不是用于复制专有代码或资产的工具。 - 在你所在司法管辖区属于违法行为的情况下，规避技术保护措施、许可验证或访问控制。 - 分析你不拥有或未经授权检查的固件、二进制文件或设备。 你有责任确保你的使用行为符合适用于你的法律和合同。逆向工程法律因国家和合同而异（例如 EULA、DMCA §1201 及其豁免规定、欧盟软件指令等）。如有疑问，请寻求法律建议。作者“按原样”提供本软件，仅供研究和教育目的，不提供任何担保 — 请参阅 [许可证](LICENSE)。 重构结果是基于**静态分析尽力推断出的结论**。在依赖任何结果之前，请对照真实硬件和权威文档进行验证。 ## 功能说明 revenant 运行并行且带缓存的分析流水线，并根据你的输入将工作路由到两条路径之一。 **硬件固件**（MCU 镜像、嵌入式 Linux）： - 识别 SoC/MCU、CPU 核心、架构和大小端序。 - 通过内存映射的寄存器访问、符号和字符串，盘点外设（UART、I2C、SPI、GPIO、定时器、ADC、USB 等）。 - 以 SoC 本身的命名方式重构**引脚图**（PA9、GPIO17、IO0 等）。 - 生成**设备树源码**（`.dts`）骨架。 - 生成**完整且可编译的自定义固件项目**（ESP-IDF、Arduino、Zephyr、STM32、裸机等） — 如果配置了 provider，LLM 会为特定部件编写真实的寄存器级初始化代码：RCC 时钟使能、匹配恢复引脚的 GPIO 复用功能配置、外设初始化、启动代码 + 向量表、链接脚本和 Makefile。在受控的 STM32F4 测试中，生成的项目使用 `arm-none-eabi-gcc` 顺利编译出了可烧录的镜像。在无 LLM 的情况下，会回退到确定性的骨架代码。 - 优先推荐**最安全的烧录路径** — 如果部件支持，首选不会变砖的路径（USB DFU / ROM bootloader），并以 SWD/JTAG 作为后备方案。 **软件**（原生 ELF/PE/Mach-O，或字节码 — `.pyc`/JVM/`.jar`/wasm）： - 识别语言、运行时、框架和构建系统。 - 将程序拆分为逻辑组件，并重构其行为（输入、输出、副作用、数据格式/协议）。 **两条路径共同支持：** - **确定文件类型并查找压缩内容** — 结合 libmagic 识别和完整的 binwalk 签名扫描，定位每个偏移量处的压缩数据块和嵌入式文件系统，然后递归提取它们。 - **Ghidra 反编译**（`--decompile`，且由 `--reimplement` / `--cross-validate` 隐式启用） — 其反编译器生成的 C 代码可读性远高于 radare2，能为行为重构、命名和重写提供更优质的输入。 - 为被剥离的二进制文件**恢复有意义的函数名**，并生成 radare2 脚本来应用这些名称。 - **对抗性交叉验证**（默认开启；使用 `--no-verify` 禁用）：通过一次独立的扫描尝试*反驳*每一项声明并重新校准置信度，从而确保薄弱或幻觉产生的发现被标记出来，而不是直接输出。 - **能力检测**（`--capabilities` 或 `--deep`）：通过 Mandiant capa 识别二进制文件的功能（网络、加密、反分析、持久化）。 - 可选的 **1:1 开源重写实现**（`--reimplement`）。 - 生成人类可读的 `report.md`、机器可读的 `report.json`，以及用于说明架构和流水线的 Mermaid 图表。 ## 快速开始（Docker） ``` git clone https://github.com/DatanoiseTV/revenant.git cd revenant # First run builds the image automatically (radare2-based; fast). ./revenant.sh analyze firmware.bin ``` `revenant.sh` 会将你的当前目录挂载到 `/work`，因此它会在你的文件夹中读取 `firmware.bin`，并将 `revenant-out/` 工作区写回该目录。宿主机只需要安装 Docker。 ``` # Software binary, with a reimplementation attempt: ./revenant.sh analyze ./app --mode software --reimplement # Give it a hint when you already know the part: ./revenant.sh analyze fw.bin --soc STM32F405RG --load-addr 0x08000000 # Large/complex binary: faster shallow analysis (verify runs by default): ./revenant.sh analyze big.elf --fast # Thorough pass (Ghidra decompile + capa capabilities + SBOM/CVE): ./revenant.sh analyze app.elf --mode software --deep # What tools/providers are available: ./revenant.sh doctor ``` ### 在公开的二进制文件上尝试 revenant 本身不包含任何二进制文件 — 请将指向你有权分析的目标。如果不想触碰任何专有文件就想查看其运行情况，可以使用基于开放许可、可自由分发的目标： ``` # Iconic old software, software track — MS-DOS (MIT, open-sourced by Microsoft). # Pick any .COM/.EXE in the clone; the path layout depends on the version dir. git clone --depth 1 https://github.com/microsoft/MS-DOS.git ./revenant.sh analyze MS-DOS/v2.0/bin/COMMAND.COM --mode software # Open-source MCU firmware, firmware track — e.g. GRBL, Marlin, Betaflight, # QMK (all GPL, distributed as prebuilt images). Convert Intel HEX to raw if # needed, then analyze. Because the source is public, you can check the # reconstruction against it. objcopy -I ihex -O binary firmware.hex firmware.bin ./revenant.sh analyze firmware.bin ``` 你可以用完全相同的方式来分析你自己的固件。切勿将 revenant 指向未经授权检查的镜像 — 请参阅上文的免责声明。 ### 预构建镜像 (GHCR) CI 会在每次推送到 `main` 分支以及每次发布标签时，将镜像发布到 GitHub Container Registry： ``` docker pull ghcr.io/datanoisetv/revenant:latest REVENANT_IMAGE=ghcr.io/datanoisetv/revenant:latest ./revenant.sh analyze firmware.bin ``` 发布的镜像专为 **linux/amd64**（CI 运行器）构建。在 Apple Silicon 上，`revenant.sh` 的本地构建版本是原生 arm64 的，比在模拟环境下运行 amd64 镜像速度更快。镜像中不包含任何凭证 — provider 的认证信息会在运行时通过 `revenant.sh` 从你现有的登录会话中获取，绝不会存储在镜像或代码仓库中。 ## LLM providers 语义阶段（识别、引脚图、行为、命名、验证、重写实现）使用可插拔的 LLM 后端。确定性阶段（筛选、提取、反汇编、设备树、模板）则无需 LLM 即可运行。 | Provider | 标志 | 说明 | |---|---|---| | Claude Code (默认) | `--provider claude-code` | 代理式：在自适应循环中通过 MCP 驱动 radare2。通过挂载的 `~/.claude` 或 `ANTHROPIC_API_KEY` 进行认证。 | | OpenAI | `--provider openai` | 需设置 `OPENAI_API_KEY`。 | | LM Studio (本地) | `--provider lmstudio` | 本地 OpenAI 兼容服务器。在 Docker 中需设置：`REVENANT_BASE_URL=http://host.docker.internal:1234/v1`。 | | none | `--provider none` | 仅运行确定性阶段（不包含识别/引脚图）。 | 在未配置 provider 的情况下，确定性阶段依然会生成一份真实的报告：架构/大小端序、提取树、函数/字符串/导入清单，以及针对固件的 MMIO 基地址候选项。 ## 输出内容 所有结果都会存放在 `revenant-out/` 目录中（可通过 `-o` 配置）： ``` revenant-out/ ├── report.md # human-readable report ├── report.json # machine-readable report ├── artifacts/disasm.txt # radare2 analysis dump └── reconstruction/ ├── peripherals.json # inferred peripherals (firmware) ├── pinmap.json / pinmap.md # reconstructed pin map (firmware) ├── devicetree.dts # device tree skeleton (firmware) ├── firmware-template/ # complete buildable firmware project (firmware) ├── software-profile.json # language/components (software) ├── behavior.md # reconstructed behavior (software) ├── function-names.json # recovered names ├── rename.r2 # apply with: r2 -i rename.r2 ├── verification.json # cross-validation verdicts └── graphs/ # architecture.mmd, pipeline.mmd (Mermaid) ``` ## 工作原理 一个具备依赖感知能力的 DAG 引擎会并发运行每一个处于就绪状态的阶段，并根据其输入的内容哈希值缓存每个阶段的输出，因此重新运行是瞬间完成的，并且只有发生变动的工作才会被重新执行。 ``` recon → triage → extract → disasm → semantic → decompile ─┬─ naming (file type + (Ghidra, when needed) ├─ (firmware) pinmap → devicetree → firmware_template compression scan) ├─ (software) behavior ├─ verify (--cross-validate) └─ reimplement (--reimplement) └────────── report ``` 默认的 `claude-code` 后端是**代理式**的：模型不需要固定的命令脚本，而是通过 [radare2 MCP server](https://github.com/radareorg/radare2-mcp) 在迭代循环中亲自驱动 radare2，从而决定接下来检查什么。其他后端在预先计算的反汇编特征上使用确定性的补全路径，因此本地模型同样适用。 ## 实时 TUI 安装 `tui` 扩展（已内置在 Docker 镜像中）即可获得实时视图 — 包含阶段 DAG 树及各阶段的状态与耗时、动态进度条、滚动日志面板，以及带有外设/引脚/组件表格的最终总结。它基于 [rich](https://github.com/Textualize/rich)（`Tree`/`Table`/`Panel`/`ProgressBar`/`Live`）构建，能够正确计算布局和 Unicode 单元格宽度 — 无需手动对齐 ASCII 字符。该界面在终端环境下会自动启用；使用 `--no-tui` 可切换为纯文本日志（此为 CI/无头环境运行时的默认选项）。

_(示例合成目标：一个 STM32F4 环境控制器 — 包含已识别的 SoC、位于其真实 MMIO 基址的外设、I2C 总线上的外部组件，以及具有正确复用功能的引脚图。)_ ## 工具链 该镜像内置了最新（2026年）的逆向工程工具集；引擎会直接使用它们，且代理式后端能够驱动其中任何一个： - **反汇编 / 反编译：** radare2（从源码构建，包含 arm64 支持），Ghidra（为镜像所属架构原生构建的反编译器）。 - **提取：** unblob（首选的递归提取器）和 binwalk，辅以 jefferson / ubi-reader / squashfs-tools / 7-zip 处理嵌套文件系统。 - **识别：** `file`/libmagic，LIEF（PE/Mach-O/ELF 解析），yara。 - **二进制分析库：** capstone，unicorn，pyelftools，以及用于符号执行和模拟的 angr，qiling，capa。 - **动态分析：** QEMU 用户模式（`--emulate`）。 - **供应链：** Syft (SBOM) + Grype / cve-bin-tool 用于已知 CVE 扫描（`--sbom`）。 运行 `revenant doctor` 可查看您的环境中确切可用的工具。可以通过 `--build-arg INSTALL_HEAVY=false` 移除重量级工具（angr/qiling/capa/SBOM），以生成更小的镜像。 ## 本地运行（不使用 Docker） 引擎仅依赖标准库，因此安装极其迅速；外部工具（radare2、binwalk，可选 Ghidra）必须位于你的 PATH 中。 ``` pip install -e ".[all]" # rich TUI + r2pipe + PyYAML revenant analyze firmware.bin revenant doctor # check tool/provider availability ``` ## CLI 参考 ``` revenant analyze [options] -o, --out DIR output workspace (default: revenant-out) --mode MODE auto | firmware | software (track selection) --provider P claude-code | openai | lmstudio | none --model M model id for the provider --no-agentic disable MCP-driven agentic analysis --toolchain T firmware template: esp-idf|arduino|zephyr|stm32-hal|bare-metal|linux --arch / --soc / --load-addr detection hints --only / --skip STAGE... run/skip specific stages --deep thorough: enable decompile + capabilities + sbom --no-verify disable the default adversarial cross-validation pass --decompile run Ghidra headless decompilation (better C for the LLM) --capabilities capa capability detection (network/crypto/anti-analysis) --emulate run a target Linux ELF under user-mode QEMU (executes it) --sbom software bill of materials + known-CVE scan (syft/grype) --reimplement also produce a 1:1 open-source reimplementation --fast shallower (faster) radare2 analysis for large binaries -j, --concurrency N max parallel stages (default 6) --no-cache ignore the stage cache --tui / --no-tui force/disable the live TUI revenant doctor report tool + provider availability revenant init write a sample revenant.yaml config ``` ## 状态与局限性 - 识别与重构结果属于**尽力而为的静态推断**。置信度评分和默认的对抗性验证扫描有助于捕获薄弱的发现，但仍需对照真实硬件和权威文档进行验证。 - 重写实现阶段是基于代理且受边界限制的 — 请将其输出视为脚手架，而非最终完成的移植版本。 - 默认镜像中包含了 Ghidra；你可以通过 `--build-arg INSTALL_GHIDRA=false` 构建仅包含 radare2 的更小镜像。 - 原生解析 ELF 格式；Mach-O/PE 头信息则通过 radare2/LIEF 识别。 ## 许可证 [Apache-2.0](LICENSE)。请将其用于修复、保存、互操作性、安全研究和教育目的 — 请参阅上文免责声明。

标签：C2, DLL 劫持, Docker, Python, 云资产清单, 固件分析, 大语言模型, 安全防御评估, 嵌入式系统, 无后门, 网络调试, 自动化, 请求拦截, 逆向工具, 逆向工程