# elfparser **Repository Path**: stesen/elfparser ## Basic Information - **Project Name**: elfparser - **Description**: elf文件的解析和反汇编工具，基于rust，caoptone，graphviz，代码全是AI xjbx的 - **Primary Language**: Rust - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-06 - **Last Updated**: 2026-03-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ELF Parser [English Documentation](README_en.md) | **中文文档** --- ## 项目概述 **ELF Parser** 是一个基于 Rust 开发的高性能 ELF 文件解析与反汇编工具，支持多架构反汇编、控制流图生成、DWARF 调试信息解析以及 AI 助手集成。 - **仓库地址**: https://gitee.com/stesen/elfparser/ - **版本**: 0.10.0 - **许可证**: Apache License 2.0 - **语言**: Rust (89.3%), Python (5.7%), Shell (4.1%) --- ## 核心功能 ### 1. ELF 文件解析 - **支持格式**: 32位/64位 ELF - **显示信息**: 节区(Section)、段(Segment)、程序头、节区头、重定位表、动态段、Note段 - **兼容性**: 提供与 `readelf -a` 类似的功能 ### 2. 多架构反汇编 - **支持架构**: - ARM64 (AArch64) - x86 (32-bit) - x86_64 (64-bit) - ARM (32-bit) - **反汇编引擎**: Capstone - **跳转指令支持**: - ARM64: `b`, `b.cond`, `bl`, `blr`, `br`, `cbz`, `cbnz`, `tbz`, `tbnz`, `ret` - x86/x64: `jmp`, `je/jne`, `jz/jnz`, `call`, `ret`, etc. ### 3. 控制流图生成 - **布局算法**: Sugiyama 层次布局算法 - **输出格式**: - **DOT**: Graphviz 图描述文件 - **PDF**: 矢量图格式（需要 Graphviz） - **Excalidraw**: 手绘风格（可导入 excalidraw.com） - **GUI**: 交互式图形界面（支持拖拽、缩放） - **TUI**: 终端交互界面（键盘导航） - **特性**: - 自动优化节点位置，减少边交叉 - 智能处理回边（循环），使用贝塞尔曲线绘制优雅连接 - 彩色语法高亮（Atom Code Dark/Light 主题） ### 4. 类型图生成 - **功能**: 可视化 C++ 类/结构体的成员关系图 - **显示内容**: - 成员变量的偏移和大小 - 继承关系（基类） - 指针/引用类型的引用关系 - 嵌套类型的层级结构 - **支持格式**: DOT, PDF, GUI, TUI, Excalidraw ### 5. DWARF 调试信息解析 - **支持标签**: - `DW_TAG_subprogram`: 函数/子程序 - `DW_TAG_class_type`: 类类型 - `DW_TAG_structure_type`: 结构体类型 - `DW_TAG_union_type`: 联合体类型 - `DW_TAG_member`: 成员变量 - `DW_TAG_inheritance`: 继承关系 - `DW_TAG_typedef`: 类型定义 - `DW_TAG_enumeration_type`: 枚举类型 - `DW_TAG_pointer_type`: 指针类型 - `DW_TAG_reference_type`: 引用类型 - **源码位置**: 显示函数和类的源码文件路径及行号信息 - **精度验证**: 与 `addr2line` 完全一致 ### 6. 智能注释 - **详细模式**: `-v` 参数为每条汇编指令添加自然语言解释 - **函数分析**: 分析函数整体行为（栈分配、条件分支、外部调用等） ### 7. MCP 服务器 - **协议**: Model Context Protocol (MCP) over stdio - **AI 助手集成**: 支持 Claude Desktop, Cursor 等 - **提供的工具**: - `mcp_elf_analyze_file`: 分析 ELF 文件基本信息 - `mcp_elf_list_symbols`: 列出符号表 - `mcp_elf_resolve_address`: 解析地址到源码位置 - `mcp_elf_find_function`: 查找函数信息 - `mcp_elf_disassemble_function`: 反汇编函数 - **提供的资源**: 通过 `elf://` URI 协议访问 ELF 文件数据 --- ## 使用方法 ### 基本用法 ```bash # 显示 ELF 文件基本信息 elfparser -a # 反汇编指定地址 elfparser -d 0x1234 elfparser -d 10342380 # 十进制 # 详细模式（带注释） elfparser -d 0x1234 -v ``` ### 控制流图生成 ```bash # 生成 DOT 格式 elfparser -d 0x1234 --dot # 生成 PDF 格式（需要 Graphviz） elfparser -d 0x1234 --pdf # ⭐ 推荐：生成 DOT 并自动转换为 PDF elfparser -d 0x1234 --dot2pdf # 生成 Excalidraw 格式 elfparser -d 0x1234 --excalidraw # 启动 GUI 图形界面 elfparser -d 0x1234 --gui # 启动 TUI 终端界面 elfparser -d 0x1234 --tui ``` ### 符号查询 ```bash # 查询函数符号 elfparser -s function_name # 查询类/结构体 elfparser -s ClassName # 生成类型图 elfparser -s ClassName --dot elfparser -s ClassName --pdf elfparser -s ClassName --gui elfparser -s ClassName --tui ``` ### MCP 服务器 ```bash # 启动 MCP 服务器 elfparser --mcp ``` **Claude Desktop 配置**: ```json { "mcpServers": { "elfparser": { "command": "/path/to/elfparser", "args": ["--mcp"] } } } ``` **Cursor 配置** (`.cursor/mcp.json`): ```json { "mcpServers": { "elfparser": { "command": "/path/to/elfparser", "args": ["--mcp"] } } } ``` --- ## 项目结构 ``` elfparser/ ├── Cargo.toml # 项目配置 ├── src/ │ ├── main.rs # 主程序入口 │ ├── core/ # 核心类型模块 │ │ ├── mod.rs # 核心类型定义 │ │ ├── types.rs # VirtualAddress 等基础类型 │ │ ├── address.rs # 地址类型（Newtype 模式） │ │ └── location.rs # 源码位置 │ ├── domain/ # 领域模型层 │ │ ├── dwarf/ # DWARF 领域模型 │ │ │ ├── type_graph.rs # 类型图数据结构 │ │ │ └── type_graph_builder.rs # 类型图构建器 │ │ └── elf/ # ELF 领域模型 │ ├── dwarf_parser.rs # DWARF 调试信息解析 │ ├── disasm.rs # 反汇编模块 │ ├── instruction.rs # 指令定义 │ ├── generate_function_graph.rs # 函数控制流图生成 │ ├── layout/ # 布局算法模块 │ │ ├── sugiyama.rs # Sugiyama 层次布局算法 │ │ └── legacy.rs # 传统布局算法 │ ├── gui.rs # GUI 图形界面 │ ├── tui.rs # TUI 终端交互界面 │ ├── output/ # 输出格式模块 │ │ ├── pdf.rs # PDF 生成 │ │ ├── dot.rs # DOT 格式 │ │ ├── mermaid.rs # Mermaid 格式 │ │ ├── excalidraw.rs # Excalidraw 格式 │ │ ├── type_pdf.rs # 类型图 PDF │ │ └── type_dot.rs # 类型图 DOT │ └── mcp/ # MCP 服务器模块 │ ├── mod.rs # MCP 服务器入口 │ ├── handlers.rs # 工具和资源处理器 │ └── protocol.rs # MCP 协议定义 ├── scripts/ # 构建脚本 │ ├── build-release.sh # Linux 多平台构建 │ ├── build-release.bat # Windows 构建 │ └── build-release.py # Python 构建脚本 ├── tests/ # 测试 └── docs/ # 文档 ``` --- ## 依赖项 ### 必需依赖 | 依赖 | 版本 | 用途 | |------------------|----------------|----------------| | capstone | 0.14 | 反汇编引擎 | | gimli | 0.29 | DWARF 解析库 | | object | 0.35 | 对象文件解析 | | goblin | 0.10 | ELF 解析 | | clap | 4.0 | 命令行参数解析 | | memmap2 | 0.9 | 内存映射 | | printpdf | 0.7 | PDF 生成 | | serde | 1.0 | 序列化 | | serde_json | 1.0 | JSON 处理 | | hex | 0.4 | 十六进制编码 | | dirs | 5.0 | 目录操作 | ### 可选依赖 | 依赖 | 版本 | 用途 | 特性标志 | 支持平台 | |------------------|----------------|----------------|------------------------|----------| | iced | 0.13 | GUI 图形界面 | `gui` | Linux, Windows | | clipboard | 0.5 | 剪贴板操作 | `gui` | Linux, Windows | | ratatui | 0.29 | TUI 终端界面 | `tui` | 全平台 | | crossterm | 0.28 | 终端控制 | `tui` | 全平台 | ### 系统依赖 - **Capstone 库**: 反汇编引擎核心 - **Graphviz** (可选): 用于 DOT 到 PDF 的转换 - **X11 开发库** (Linux GUI 需要): libxcb-render0-dev, libxcb-shape0-dev, libxcb-xfixes0-dev ### 平台支持 | 平台 | GUI | TUI | PDF | CLI | 构建方式 | |------|-----|-----|-----|-----|----------| | Linux x86_64 | ✅ | ✅ | ✅ | ✅ | `cargo build --release` | | Windows | ✅ | ✅ | ✅ | ✅ | `cargo build --release` | | Android | ❌ | ❌ | ❌ | ✅ | `scripts/mobile-dev build android-aarch64` | | OpenHarmony | ❌ | ❌ | ❌ | ✅ | `scripts/mobile-dev build ohos-aarch64` | **注意**: Android 和 OpenHarmony 仅支持 CLI 核心功能（ELF 解析、反汇编、符号查询、DOT/Excalidraw 输出），不支持 GUI、TUI 和 PDF 生成。 --- ## 安装方法 ### 从源码编译 ```bash # 克隆仓库 git clone https://gitee.com/stesen/elfparser.git cd elfparser # 构建调试版本 cargo build # 构建发布版本 cargo build --release # 构建特定功能 cargo build --features "gui tui" # 启用 GUI 和 TUI cargo build --no-default-features # CLI only ``` ### 安装 Capstone **Ubuntu/Debian**: ```bash sudo apt-get install libcapstone-dev ``` **macOS**: ```bash brew install capstone ``` **Windows**: 1. 下载预编译版本: https://github.com/capstone-engine/capstone/releases 2. 将 `capstone.dll` 复制到系统目录或项目目录 ### 安装 Graphviz (可选) **Ubuntu/Debian**: ```bash sudo apt-get install graphviz ``` **macOS**: ```bash brew install graphviz ``` **Windows**: ```bash # 使用 Chocolatey choco install graphviz ``` --- ## 命令行参数 ``` Usage: elfparser [OPTIONS] Arguments: ELF文件路径 Options: -a 显示所有 ELF 信息 -d
反汇编指定地址（支持 0x 前缀的十六进制或十进制） -v, --verbose 详细模式：为汇编指令添加自然语言解释 -V, --version 显示版本信息 --dot 生成 DOT 格式控制流图 --dot2pdf 生成 DOT 并自动转换为 PDF（推荐，需要 Graphviz） --pdf 生成 PDF 格式控制流图 --excalidraw 生成 Excalidraw 格式 --tui 启动 TUI 终端交互界面 --gui 启动 GUI 图形界面 --mcp 启动 MCP 服务器（AI 助手集成模式） -s 查询符号名称 -h, --help 显示帮助信息 ``` --- ## 架构设计 ### 分层架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 表现层 (GUI/TUI/MCP/Output) │ ├─────────────────────────────────────────────────────────────┤ │ 应用层 (用例) │ ├─────────────────────────────────────────────────────────────┤ │ 领域层 (业务逻辑) │ ├─────────────────────────────────────────────────────────────┤ │ 核心层 (基础类型) │ ├─────────────────────────────────────────────────────────────┤ │ 基础设施层 (外部系统) │ └─────────────────────────────────────────────────────────────┘ ``` ### 关键设计模式 1. **Newtype 模式**: 类型安全的地址处理 - `VirtualAddress`, `PhysicalAddress`, `FileOffset` 2. **缓存优化**: - `SourceLocationCache`: O(1) 地址到源码位置查询 - `FunctionCache`: 预计算的函数边界 3. **批量查询**: - `get_source_locations_batch()`: 批量地址解析 --- ## 颜色主题 ### Flat 模式 (默认) - **主题**: Atom Code Dark | 元素 | 颜色 | RGB | |---------------|-------------|-----| | 地址 | 橙色 | #d19a66 | | 跳转指令 | 红色 | #e06c75 | | 普通指令 | 紫色 | #c678dd | | 操作数 | 青色 | #56b6c2 | | 注释 | 灰色 | #5c6370 | ### PDF 模式 - **主题**: Atom Code Light | 元素 | 颜色 | RGB | |---------------|-------------|-----| | 地址 | 橙色 | #986801 | | 跳转指令 | 红色 | #ca1243 | | 普通指令 | 紫色 | #a626a4 | | 操作数 | 绿色 | #50a14f | --- ## 测试 ```bash # 运行所有测试 cargo test # 运行库测试 cargo test --lib # 运行特定测试 cargo test test_name # 运行集成测试 cargo test -- --ignored # 显示输出 cargo test -- --nocapture ``` --- ## 交叉编译 ### Android **前提条件**: 安装 Android NDK (r21 或更高版本) ```bash # 1. 下载并安装 Android NDK # https://developer.android.com/ndk/downloads # 2. 设置环境变量 export NDK_HOME=/path/to/android-ndk-r25c export PATH=$NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH # 3. 构建（使用脚本） scripts/mobile-dev build android-aarch64 # 或手动构建 cargo build --release --target aarch64-linux-android --no-default-features ``` ### OpenHarmony **前提条件**: 安装 musl 交叉编译工具链 ```bash # 1. 下载 musl 交叉编译工具链 # aarch64: https://musl.cc/aarch64-linux-musl-cross.tgz # x86_64: https://musl.cc/x86_64-linux-musl-cross.tgz # 2. 解压并设置环境变量 export PATH=/path/to/aarch64-linux-musl-cross/bin:$PATH # 3. 构建（使用脚本） scripts/mobile-dev build ohos-aarch64 # 或手动构建 cargo build --release --target aarch64-unknown-linux-musl --no-default-features ``` **注意**: OpenHarmony 构建需要 musl 交叉编译器。如果没有安装，会报错 `incompatible with elf_x86_64`。 --- ## 故障排除 ### 编译错误：找不到 capstone ```bash # Ubuntu/Debian sudo apt-get install libcapstone-dev # 设置环境变量 export CAPSTONE_LIB_DIR=/usr/lib export CAPSTONE_INCLUDE_DIR=/usr/include ``` ### 链接错误：找不到 xcb 库 ```bash # 错误信息：unable to find library -lxcb-render # 这是 GUI 功能依赖的 X11 库 # 解决方案 1：安装 X11 开发库（需要 GUI 时） sudo apt-get install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev # 解决方案 2：禁用 GUI 功能编译（推荐用于服务器/无图形环境） cargo build --release --no-default-features # 仅 CLI cargo build --release --no-default-features --features tui # CLI + TUI ``` ### PDF 生成失败 ```bash # 检查 Graphviz 安装 dot -V # 手动生成 PDF dot -Tpdf input.dot -o output.pdf ``` ### DWARF 调试信息查询失败 ```bash # 检查 DWARF 信息 readelf --debug-dump=info | head -20 readelf --debug-dump=line | head -20 ``` --- ## 与 addr2line 对比 | 功能 | addr2line | elfparser MCP | |---------------|-----------|---------------| | 地址解析 | ✅ | ✅ | | 符号列表 | ❌ | ✅ | | 函数查找 | ❌ | ✅ | | AI 集成 | ❌ | ✅ | | 批量查询 | ❌ | ✅ | | 文件缓存 | ❌ | ✅ | | 反汇编 | ❌ | ✅ | | 控制流图 | ❌ | ✅ | **精度验证**: elfparser 的地址解析精度与 `addr2line` 完全一致。 --- ## 使用示例 ### 1. 查看 ELF 文件信息 ```bash elfparser /bin/ls -a ``` ### 2. 反汇编并生成 PDF ```bash elfparser libexample.so -d 0x9db94c --dot2pdf -v ``` ### 3. 查询符号信息 ```bash elfparser libexample.so -s ngtcp2_gaptr_free ``` ### 4. 生成类型图 ```bash elfparser libexample.so -s grpc::CompletionQueue --pdf ``` ### 5. 启动 TUI 界面 ```bash elfparser libexample.so -d 0x9db94c --tui ``` --- ## 相关文档 - **测试报告**: [TEST_REPORT.md](TEST_REPORT.md) - **Claude Code 指南**: [CLAUDE.md](CLAUDE.md) - **MCP 设计文档**: [MCP_DESIGN.md](MCP_DESIGN.md) - **发布指南**: [RELEASE_GUIDE.md](RELEASE_GUIDE.md) - **英文文档**: [README_en.md](README_en.md) --- ## 更新日志 ### v0.9.9 (2026-03-05) - **新增**: 类型图可视化功能（DOT/PDF/GUI/TUI/Excalidraw） - **新增**: C++ 类/结构体成员关系图生成 - **新增**: 中英文分离文档（README.md / README_en.md） - **改进**: 编译速度优化（移除未使用依赖，添加编译配置） - **修复**: 修复多个编译警告和测试用例 ### v0.9.8 (2026-03-02) - **新增**: MCP 反汇编工具 (`mcp_elf_disassemble_function`) - **新增**: MCP 测试脚本和测试套件 - **改进**: CLAUDE.md 项目架构文档 ### v0.9.7 (2026-02-24) - **新增**: 类型图生成功能 - **新增**: GUI/TUI 支持类型图查看 - **改进**: Sugiyama 布局算法 ### v0.9.6 (2026-02-18) - **新增**: MCP 服务器完整实现 - **新增**: DWARF 调试信息解析增强 --- ## 贡献者 - **作者**: [stesen](https://gitee.com/stesen) --- **注意**: 代码全部由 AI 生成（xjbx = 瞎几把写）。 --- *文档生成时间*: 2026-03-05