patacca/flatline

# flatline [](https://pypi.org/project/flatline/) [](https://pypi.org/project/flatline/) [](https://pepy.tech/projects/flatline) [](https://patacca.github.io/flatline/) [](https://github.com/patacca/flatline/actions/workflows/ci.yml) Ghidra 反编译器的 Python 封装。提供了一个稳定且可通过 pip 安装的接口， 用于带有结构化输出的单函数反编译——无需安装 Ghidra。 得名于威廉·吉布森（William Gibson）《神经漫游者》（*Neuromancer*，1984 年）中的 迪克西·平线（Dixie Flatline）——一个死亡黑客的 ROM 构造体，从硬件中提取的意识。 秉承这一精神，flatline 将 Ghidra 的反编译器引入库中，用于从二进制文件中提取有意义的结构。 ## 功能 - **单函数反编译** -- 传入内存镜像、基地址和函数入口点；即可返回带有诊断信息的结构化 C 语言输出。 - **多指令集架构（Multi-ISA）** -- 支持任何 Ghidra 支持的目标架构。优先为 x86（32/64 位）、ARM64、RISC-V 64 和 MIPS32 提供基于夹具（fixture）的置信度保障；其他内置的指令集架构则尽力而为。 - **打包的运行时数据** -- 编译好的 Sleigh 运行时资产来自配套的 `ghidra-sleigh` 包，因此生产环境安装不依赖于 vendored 的 `third_party/ghidra` 目录树。 - **确定性** -- 对同一输入重复进行反编译，会产生结构上等效的输出。 ## 系统要求 - Python 3.13+ - 支持的平台：Linux x86_64/aarch64、Windows x86_64、macOS x86_64/arm64 ## 安装 ### 从 PyPI 安装 ``` pip install flatline ``` `pip install flatline` 在有可用 wheel 包时会下载预构建的 wheel。 目前已发布 wheel 的平台包括 Linux x86_64/aarch64、Windows x86_64 和 macOS x86_64/arm64， 因此这些平台的安装不需要本地编译器或构建工具链。如果您的目标平台没有可用的 wheel，`pip` 将回退到源代码构建。 支持的运行时宿主机为 Linux x86_64、Windows x86_64 和 macOS arm64。 Linux aarch64 和 macOS x86_64 是已发布 wheel 的目标平台，仍然可以安装，但它们尚需等待获得同等的宿主机覆盖率提升。 其他平台可能仍可通过源代码构建正常工作，但属于尽力而为的支持范畴。 ### 从源代码构建或从本地代码库安装 当您的目标平台没有预构建的 wheel、当您想从本地代码库安装，或者当您想强制进行本地构建时，请使用此路径。 源代码构建需要 C++20 编译器、Ninja 和 zlib 头文件： | 平台 | 安装命令 | |----------|----------------| | Ubuntu/Debian | `sudo apt-get install g++ ninja-build zlib1g-dev` | | Fedora/RHEL | `sudo dnf install gcc-c++ ninja-build zlib-devel` | | Arch Linux | `sudo pacman -S gcc ninja zlib` | | macOS | `brew install ninja zlib`（Xcode 提供 C++ 编译器） | | Windows | 安装带有 C++ 工作负载的 Visual Studio；`pip install ninja`；`vcpkg install zlib:x64-windows` | 从本地代码库安装： ``` python -m venv .venv source .venv/bin/activate pip install . ``` 用于开发： ``` python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` `flatline` 依赖于 `ghidra-sleigh` 来获取其默认的运行时数据路径，因此 当省略 `runtime_data_dir` 时，`DecompilerSession` 和一次性封装器会自动发现运行时数据。 `runtime_data_dir` 仍然可用作自定义或精简运行时数据根目录的显式覆盖。 ### 原生桥接 真正的反编译需要原生桥接——一个编译好的 C++ 扩展 （`flatline._flatline_native`），该扩展链接到 Ghidra 反编译器库。 已发布的 wheel 中已包含此扩展。 没有它，Python API 仍然可以完全导入，但每次 `decompile_function` 调用都会返回一个 `configuration_error` 结果。`list_language_compilers` 仍然 会返回从已安装的 `ghidra-sleigh` 包中发现的运行时数据对。 构建有三种模式，由 Meson 的 `native_bridge` 选项控制： | 模式 | 设置方法 | 行为 | |------|------------|-----------| | `auto`（默认） | 省略该标志 | 在找到 C++20 编译器和 Ninja 时构建扩展；否则静默回退到纯 Python 存根。 | | `enabled` | `-Dnative_bridge=enabled` | 强制进行原生构建；如果缺少先决条件，则会在安装时失败。使用此选项可验证完整的反编译栈。 | | `disabled` | `-Dnative_bridge=disabled` | 完全跳过原生构建。所有反编译调用均返回 `configuration_error`。 | 显式强制原生构建（需要 C++20 编译器和 Ninja）： ``` pip install -e ".[dev]" -Csetup-args=-Dnative_bridge=enabled ``` 显式禁用原生构建（仅限纯 Python 存根）： ``` pip install -e ".[dev]" -Csetup-args=-Dnative_bridge=disabled ``` 需要原生扩展的测试被标记为 `requires_native`，并且当 `flatline._flatline_native` 无法 导入时，会自动跳过并给出可操作的原因。 ## 快速开始 ``` from flatline import DecompileRequest, decompile_function result = decompile_function(DecompileRequest( memory_image=raw_bytes, base_address=0x400000, function_address=0x401000, language_id="x86:LE:64:default", compiler_spec="gcc", )) print(result.c_code) ``` 仅当您需要覆盖依赖项支持的默认运行时数据根目录时，才传递 `runtime_data_dir=...`。 精确的函数切片不需要手动进行调用者填充。Flatline 默认通过 `tail_padding=b"\x00"` 将超出 `memory_image` 结尾的解码器前瞻零填充；仅当 您需要严格的尾部边界失败时，才设置 `tail_padding=None` 或 `tail_padding=b""`。 对于选择加入的 IR 分析，请请求 `enriched=True`。成功的结果随后会暴露 `result.enriched.pcode`，它保留了原始的 `pcode_ops` / `varnodes`，通过 `get_pcode_op()` / `get_varnode()` 提供 O(1) 查找，并可通过 `to_graph()` 投影出确定性的 `networkx.MultiDiGraph`，以便遍历或后续绘图。 ## 开发 ``` # Activate the venv (required for all commands) source .venv/bin/activate # Run tests + lint across configured environments tox # Run lint only tox -e lint # Run unit tests only tox -e py313,py314 -- -m unit # Run native-dependent tests (skipped automatically when the extension is absent) tox -e py313,py314 -- -m requires_native ``` `tox` 测试环境会在 `.tox/` 内部构建并安装 `flatline[test]` wheel，因此 该测试套件测试的是打包后的工件，而不是 `PYTHONPATH=src`。 仅限代码库的发布和诊断辅助工具位于 `tools/` 下，并且 有意不包含在 wheel 和 sdist 工件中。 ## 文档 文档可在 获取，也可以 在此代码库中本地构建。 安装文档依赖项： ``` pip install -e ".[docs]" ``` **本地预览：** ``` PYTHONPATH=src mkdocs serve ``` 然后打开 http://127.0.0.1:8000。 **构建静态站点：** ``` PYTHONPATH=src mkdocs build ``` 输出目录为 `site/`。 `PYTHONPATH=src` 让 mkdocstrings 能够导入纯 Python 模块以生成 API 参考，而无需进行原生构建。 ## 发行说明 项目历史记录在 [CHANGELOG.md](CHANGELOG.md) 中。每次 发布时，请使用文件中已有的“保持更新日志”（Keep a Changelog）结构对其进行更新。 面向发布的契约保证、支持层级、已知变体限制 以及公共 `0.1.x` 系列的升级策略， 记录在 [docs/release_notes.md](docs/release_notes.md) 中。 公共工件审查清单和手动批准检查点， 记录在 [docs/release_review.md](docs/release_review.md) 中。 发布发布工作流的详细信息， 记录在 [docs/release_workflow.md](docs/release_workflow.md) 中。 GitHub Actions 的发布流程位于 [.github/workflows/release.yml](.github/workflows/release.yml)：已发布的 GitHub 版本会传送到 PyPI，而手动调度则会上传到 TestPyPI。 手动 TestPyPI 调度需要唯一的版本号，现在如果上传重复 将会失败，而不是复用较旧的 TestPyPI 工件。 再分发/合规指南位于 [NOTICE](NOTICE) 中，持久化的 策略记录在 [docs/adr/adr-007.md](docs/adr/adr-007.md) 中。当前的 默认安装占用空间基准和大小策略说明位于 [docs/footprint.md](docs/footprint.md)。 ## 项目状态 当前的公共版本为 `0.1.1`。P6、P6.5 和 P7 已在代码库历史记录中关闭。 支持的运行时宿主机为 Linux x86_64、Windows x86_64 和 macOS arm64；Linux aarch64 和 macOS x86_64 仍然是已发布 wheel 的目标平台，尚待 获得同等的宿主机覆盖率提升。在当前的代码库主分支上，选择加入的丰富化 输出通过 `result.enriched.pcode.to_graph()` 将导出的 pcode / varnode 载荷投影到可遍历的图结构中。 面向发布的保证和支持策略说明位于 [docs/release_notes.md](docs/release_notes.md) 中。`python tools/release.py` 会审查当前的发布候选版本。 ## 致谢 本项目是在 [Quarkslab](https://github.com/quarkslab) 的支持下开发的。 ## 许可证 Apache-2.0。有关项目许可证，请参见 [LICENSE](LICENSE)；有关 再分发时的归属说明，请参见 [NOTICE](NOTICE)。

标签：API封装, ARM64, CTF工具, DAST, DNS 反向解析, flatline, Ghidra, JA3, MIPS, pip安装, Python, RISC-V, Sleigh, x86, 二进制分析, 二进制解析, 云安全监控, 云安全运维, 云资产清单, 反编译器, 多架构支持, 恶意软件分析, 情报收集, 无后门, 漏洞搜索, 漏洞研究, 逆向工具, 逆向工程, 静态分析, 预握手