Noelo-Lab/kuna

# Kuna

一款以 Agent 为优先的反编译器，旨在通过其他 Agent 来进行完善和优化。 Kuna 使用 Rust 编写，最初是从 [Ghidra](https://github.com/nationalsecurityagency/ghidra) 移植过来的，但随后在多项功能和 pipeline 设计上已经产生了差异。 本项目是一项_实验_，旨在探索反编译器的自主完善能力能在多大程度上推动该领域的研究。 在这篇[文章](https://noelo.org/blog/kuna-release/)中了解更多关于此方法的信息。 ## 安装与使用 Kuna 以单个 Rust 二进制文件的形式分发，可以在大多数系统上运行。 你可以下载最新的发布版本，或者[从源码构建](#building-from-source)。 ### 命令行使用 如果从源码构建，你可以在 `decompiler/target/release/kuna` 中找到 `kuna` 二进制文件。 ``` kuna decompile ./a.out main kuna decompile ./stripped.bin 0x401040 --addr # 反编译完整的 binary，返回 .c、.h 和 .asm 文件 kuna decompile-project ./a.out # 切换 decompiler 内部的 feature（对 LLM 很有用） kuna decompile ./a.out main --option compareform canonical ``` LLM agent 应当参考 `./docs/options.md` 文件，该文件详细说明了可在运行时切换的功能，以及这些功能在哪些情况下可能发挥作用。 如果在使用过程中发现 bug，请通过 issue 提交报告。 ### Web 浏览器使用 由于 Kuna 是用 Rust 编写的，你还可以通过 WebAssembly 在 Web 浏览器中使用它。 所有的计算工作都会在你的本地机器上完成，这意味着二进制文件依然会保持私密。 访问 [kuna.noelo.org/decompile](https://kuna.noelo.org/decompile) 即可使用。 部署你自己的网站所需的代码可以在 `./integrations/web` 中找到。 ### Ghidra GUI 使用 由于 Kuna 最初是从 Ghidra 移植而来，其输出格式在很大程度上与原版 Ghidra 保持兼容。 你可以在传统的 Ghidra GUI 内部，将 Kuna 核心作为 Ghidra 的反编译器使用。 为此，请在 `./integrations/ghidra` 中构建该扩展。 目前尚未支持 Ghidra 的所有功能。 ## 项目目标 像 [Codex](https://chatgpt.com/codex/) 这样的 LLM agent，从根本上改变了我们进行逆向工程乃至保护二进制文件安全的方式。 现在越来越多的情况是，不再是人类直接查看反编译器，而是由 LLM 去使用它们，人类则转而阅读 agent 的日志。 因此，反编译器理应转变思路，围绕 agent 进行设计和优化。 此外，我们可以利用这些 agent 来自动完善它们所依赖的工具。 尽管本项目的大部分代码应该由 agent 编写，但在某些时候，仍然需要对编写什么内容以及如何进行设计提供人类的洞察力。 基于其他取得成功的反编译器，本项目在 pipeline 设计和功能设计上采取了两个主要立场。 总体而言，本项目旨在实现以下目标： 1. **自主完善**：我们必须为 LLM 设计数据集、prompt 和工具，以便在我们睡觉时它们也能持续改进反编译器。这种改进应当建立在科学的基础上，最理想的情况是具备可靠的衡量指标。目前，[DecBench](https://decbench.com/) 负责提供完善所需的数据和指标。 2. **Agent 优先**：我们必须优先考虑反编译文本的质量，而不是反编译器中其他（通常很重要的）方面，如 GUI 或可视化工具。这也意味着我们需要在功能和速度之间取得平衡，因为处理大型二进制文件时的瓶颈将会是反编译器。此外，我们还将探索让 LLM 访问反编译器的最佳方式。 3. **可调节**：当我们指示 LLM 开发新功能时（无论是通过人工干预还是自动化），我们都应该使这些功能能够根据不同场景进行开启和配置。例如，逆向人员可能需要高级语言代码，而 pwn 选手则想要底层代码。这种差异意味着用户有着不同的反编译目标，而我们的功能实现风格应当与此相匹配。 ## 设计 在工程层面，反编译器的设计旨在与另外两个方面保持一致： 1. **基于阶段**：反编译器的每个阶段都应有明确的定义，从而让 LLM 在需要修改时有更大的机会找到对应的功能和代码。这也使得调试和改进更加容易。 2. **自然语言规范**：每一项重要的功能和算法都应当至少部分地在反编译器的自然语言规范（`./docs/spec`）中进行描述。这与基于阶段的模型紧密结合，应当为人类提供一种审计反编译器中高层级概念的方法。 各个阶段在以下文件中进行了描述： - `docs/phases.md` — 阶段模型概览（可通过 `stage list/map/catalog` 控制台命令查询运行时注册表）。 - `docs/options.md` — 分层选项目录（transform = LLM 控制面， 附带生成的症状索引） ## 开发 预计大部分的代码分析和创建工作都将由前沿的 LLM 在 Codex 或 Claude Code 等 agent 框架中完成。 面向 agent 的指南位于 [`AGENTS.md`](AGENTS.md)（指向 `docs/agents.md` 的软链接）中，其中包含了贡献功能时必须遵守的规则，以及指向其他所有内容的文档导航图。 ### 从源码构建 你只需要一个 **Rust 工具链**（`cargo`）。 ``` make binaries # cargo-build the decompiler (decomp_dbg, decomp_test_dbg), # the SLEIGH compiler (slacomp), and the `kuna` CLI make specs # compile every SLEIGH .slaspec -> .sla with slacomp (the decoder needs these) make # = binaries + specs ``` 所有生成的文件都会放在 `decompiler/target/release/` 中。在开发时，请直接在 cargo workspace 中 进行操作：`cd decompiler && cargo build` / `cargo test --workspace`。 ### 测试 共有四道测试关卡，要求在每次提交前都保持全部通过（绿色）： ``` make test # the 675/675 decompiler regression parity (tests/datatests/ vs docs/baseline.json) make test-stages # the kuna-owned issue testcases (tests/stages/ vs docs/baseline-stages.json) make rust-test # the full cargo workspace suite (ported unit tests, golden differential # vectors, SLEIGH-compiler .sla content-parity, docs/options.md freshness, ...) make check-spec # docs/spec/ honesty: anchors and inline code paths resolve, and each # phase folder is owned by exactly one spec chapter ``` `make test` 会使用 Rust SLEIGH 编译器编译规范，并使用 Rust 反编译器对 XML 回归 测试集（`tests/datatests/`，83 个文件 / 675 个断言）进行解码。 ### 目录结构 | 路径 | 说明 | |---|---| | `decompiler/` | 核心引擎 — 一个 cargo workspace。包含 `kuna-decomp`（反编译器，按阶段分为 `p0_knowledge/`…`p9_emit/`），`kuna-analysis`（loader/analyzer 层），`kuna-sleigh`/`kuna-slacomp`（SLEIGH 运行时与编译器，二进制文件 `slacomp`），`kuna-console`（`decomp_dbg`/`decomp_test_dbg` 二进制文件），`kuna-cli`（`kuna` 二进制文件），`kuna-ghidra`/`kuna-wasm`（Ghidra 和浏览器的前端），以及其他辅助 crate | | `tests/datatests/` | 上游的 XML 反编译回归测试（83 个文件 → 675 个断言）；即 `make test` 运行的测试集 | | `tests/stages/` | kuna 自有的 issue 测试用例；即 `make test-stages` 运行的测试集 | | `tests/golden/` | workspace 测试套件（`make rust-test`）使用的对比 golden 向量 | | `specs/Ghidra/Processors/` | 内置的 SLEIGH 处理器规范；`.sla` 是由 `slacomp` 生成的构建产物 | | `integrations/` | 集成引擎的前端模块：`ghidra/`（将 kuna 作为原版 Ghidra 的反编译器核心）和 `web/`（项目网站 + 浏览器内反编译器） | | `scripts/` + `tools/` | 用于完善 pipeline（`docs/improvement-pipeline.md`）和 decbench 任务（`docs/decbench-loop.md`）的 Python 辅助脚本和驱动程序 | | `Makefile` | 顶层的构建/测试驱动（仅限 Rust） | | `docs/history.md` | 项目历史，包括 C++→Rust 的移植及其验证过程 | ## 许可证 kuna 采用 [Apache License 2.0](LICENSE) 发布。它衍生自由美国国家安全局 （National Security Agency）开发并基于 Apache-2.0 协议发布的 [Ghidra](https://github.com/NationalSecurityAgency/ghidra) —— 相关的归属说明请参见 [NOTICE](NOTICE)（包括从 angr 移植的部分，基于 BSD-2-Clause 协议）。

标签：AI工具, AI智能体, Ghidra, LLM集成, Rust, 二进制分析, 云安全运维, 云资产清单, 反编译器, 可视化界面, 网络流量审计, 逆向工具, 逆向工程, 通知系统