cn0xroot/IFDA

# IFDA — IoT 固件深度分析 针对 IoT 固件二进制文件的自动化逆向工程与漏洞发现。本仓库实现了 [`firmware-analysis-requirements.md`](firmware-analysis-requirements.md) 中所述的**分析核心**。 ## 迭代 1 范围 根据既定计划，首次迭代交付**二进制逆向工程 (FR-RE)** 和**漏洞发现 (FR-VUL)**。它假定摄取和提取 (FR-ING / FR-EXT) 已经在磁盘上生成了文件 —— 只需将其指向单个 ELF 文件或提取出的固件目录树即可。 引擎封装了现有工具：**capstone**（多架构反汇编，无论主机架构如何均适用于 MIPS/ARM），**pyelftools** + **binutils**（ELF 解析、缓解措施）。更重量级的污点引擎是可选的，未来可作为即插即用模块接入同一接口。 ## 架构 ``` ┌───────────────────────────── Python analysis core (this repo) ──────┐ extr. │ loader/ re/ vuln/ inventory/ scripts/ fs/ │ arts ──┼► load_elf ─► disassemble ─► dangerous_funcs ► secrets shell hard-│─► JSON / (FR- │ (arch, mitigations taint (src→sink) + rules/ (cmd- ening │ Markdown EXT) │ imports, call-graph cve correlation signatures injection) │ + SBOM │ strings) xrefs cross-binary + + entropy │ (CycloneDX) │ prioritize/triage │ └─────────────────────────────────────────────────────────────────────┘ ▲ │ exec `ifda.cli analyze --progress` per job Go service / orchestration layer (service/) ← queue, workers, REST API (FR-INT-1), dedup cache, web UI with live progress ``` Python 核心是一个库 + CLI。项目所选的**混合架构**将批处理/语料库编排、REST API (FR-INT-1)、队列 (FR-ING-4) 和 Web UI 放在独立的 **Go 服务层**（`service/`，已构建）中，该层通过 CLI 一次驱动一个核心任务。JSON 模型 (`ifda/model.py`) 是两者之间的契约；核心会流式传输 `@@IFDA@@` 进度事件，以便服务显示实时任务进度。请参阅 [`service/README.md`](service/README.md) 以构建并运行它。 ## 技术栈 **分析核心 (Python 3.10+)** - [`capstone`](https://www.capstone-engine.org/) — 多架构反汇编 (x86/x86_64, ARM, ARM Thumb-2, AArch64, MIPS LE/BE) - [`pyelftools`](https://github.com/eliben/pyelftools) — ELF 解析与缓解措施检测 (NX/canary/RELRO/PIE/FORTIFY)，无需外部 `binutils` 进程 - [`cve-bin-tool`](https://github.com/intel/cve-bin-tool) — FR-VUL-1 广泛 CVE 关联所需的依赖项 (NVD/OSV/RedHat/GitLab Advisory/Curl，涵盖 350 多个组件) - [`yara-python`](https://github.com/VirusTotal/yara-python)（可选）— 外部化的 YARA 签名规则桥接 - [`angr`](https://angr.io/)（可选，未来计划）— 更重量级的污点/符号执行引擎，计划作为现有污点接口的即插即用替代方案 **服务层 (Go 1.22+)** - 仅使用标准库，零第三方 Go 依赖 — 增强版的 `net/http` `ServeMux`（方法 + 路径参数路由），手动实现的 PBKDF2 (`crypto/hmac` + `crypto/sha256`) 用于密码哈希，`image`/`image/png` 用于登录验证码 - Server-Sent Events（无需轮询，无 WebSocket 依赖）用于实时作业进度 **Web UI** - [Alpine.js](https://alpinejs.dev/) 3.14.1（本地化部署，无需构建步骤，支持离线运行） - 结合自定义属性主题的纯 CSS（7 种内置主题，支持感知浅色/深色模式） **可选扩展** - [Ghidra](https://ghidra-sre.org/) (headless 模式) — 为发现结果提供反编译的伪代码扩展 ## 参考文献与致谢 - [**EMBA**](https://github.com/e-m-b-a/emba) — 开源的 IoT 固件分析器，其在 CVE 关联和敏感数据搜寻方面的方法影响了此处的几项设计决策。 IFDA 遵循 EMBA 的做法，将广泛的 CVE 关联委托给 `cve-bin-tool`，而不是维护一个手动整理的 CVE 列表；其 `config/` 签名文件（`deep_key_search.cfg`、`password_regex.cfg` 以及 `*_files.cfg` 敏感路径列表）为敏感字符串关键字词典以及本项目修复的一个 PEM 密钥检测缺口提供了参考。感谢 EMBA 团队提供的现有技术成果。 - [**cve-bin-tool**](https://github.com/intel/cve-bin-tool)（一个 OpenSSF 项目）— FR-VUL-1 广泛 CVE 覆盖背后的实际引擎，也是 EMBA 自身用于 CVE 关联所封装的同一工具。 ## 安装 ``` # Python 分析核心 apt-get install -y python3-capstone python3-pyelftools # or: pip install -e . pip install cve-bin-tool # required: FR-VUL-1 broad CVE coverage (NVD/OSV/RedHat/GitLab/Curl) pip install yara-python # optional: enables the YARA stage if data/yara/*.yar exist # Go 服务层（可选 — 仅当您需要 REST API + web UI 时） cd service && go build -o ifda-service . # Go 1.22+ ``` `cve-bin-tool` 维护其自己的本地 CVE 数据库（NVD + OSV + RedHat + GitLab Advisory + Curl，大小约 1GB+）；在机器上的首次扫描会下载/更新该数据库，因此预计该次运行速度较慢且需要网络访问权限。如果没有它，`analyze()` 仍会运行，但 CVE 关联将退回到小型的人工整理数据库 `data/vuln_db.json`，并且报告会带有关于缺少该依赖项的明显警告（NFR-USE-1 — 缺少单个组件只会导致降级，不会导致任务崩溃）。 ## 用法 运行 ifda 有两种方式：**CLI**（单次运行，可脚本化）和**service**（队列 + REST API + 带有实时进度的 Web UI）。 ### A. CLI — 一次性分析 ``` # 分析二进制文件或提取的树；默认将 JSON 输出到 stdout。 python3 -m ifda.cli analyze /path/to/extracted_rootfs --json report.json --md report.md # 随报告一并生成 CycloneDX SBOM。 python3 -m ifda.cli analyze ./rootfs --json report.json --sbom sbom.json # 在 stderr 上输出机器可读的进度事件（由服务使用）。 python3 -m ifda.cli analyze ./rootfs --json report.json --progress # 使用 Ghidra 反编译的伪代码丰富发现结果（可选启用；需要 Ghidra， # 设置 GHIDRA_HOME 或安装到 /opt/ghidra）。速度较慢；若未安装则降级为 no-op。 python3 -m ifda.cli analyze ./rootfs --md report.md --decompile # 对发现结果进行 triage；在重新扫描后持久保留（FR-VUL-8）。 python3 -m ifda.cli triage triage.json false_positive python3 -m ifda.cli analyze ./rootfs --triage triage.json # muted findings dropped ``` `analyze` 接受单个 ELF 文件或一个目录（提取出的固件目录树）。它会遍历一次目录树并运行每个阶段：单二进制 RE/漏洞分析、跨二进制污点分析、机密信息 + 签名规则 + 熵分析、shell 和 PHP/Python/Lua 脚本注入，以及文件系统加固。 ### B. Service — 队列、REST API 和 Web UI ``` cd service go build -o ifda-service . # Go 1.22+, first time only ./ifda-service -addr :8080 -core .. # -core = repo dir (auto-detected if omitted) # 打开 http://localhost:8080 ``` Flags：`-addr`、`-core`、`-workers`（默认为 2）、`-queue`、`-data`（分诊状态 + 上传目录；默认为 `$TMPDIR/ifda-service`）、`-auth`（默认为 `true`）、`-user`/`-pass`（仅在首次运行时初始化账户 —— 不会覆盖已通过 Web UI 更改的密码；添加 `-reset-pass` 可强制重置）。完整说明请参阅 [`service/README.md`](service/README.md)。 **Web UI**（基于 Alpine.js，内嵌 —— 无需构建步骤，支持离线环境）：提交服务器路径*或*上传文件，然后观看实时 SSE 进度并进行探索： - **Dashboard** — 包含发现结果/严重/高危/二进制文件/CVE 的卡片 + 严重程度和漏洞类别分布条。 - **Findings** — 按严重程度切换开关、漏洞类别、分诊状态、置信度阈值和全文搜索进行筛选；按严重程度/置信度排序；展开以查看证据、污点路径和 Ghidra 伪代码；**内联分诊**（确认 / 误报 / 接受风险 / 重置）。 - **Binaries** — 针对单个二进制文件的架构、libc、缓解措施芯片（NX/Canary/RELRO/PIE/FORTIFY，颜色编码）、函数数量、CVEs。 - **Export** — 下载 JSON / Markdown / SBOM。 REST 端点（完整表格见 [`service/README.md`](service/README.md)）： ``` # 将作业加入队列（返回 {"id": ...}）；dedup 缓存会返回未更改的缓存目标 curl -XPOST localhost:8080/api/jobs -H 'Content-Type: application/json' \ -d '{"target":"/path/to/extracted_rootfs"}' curl -N localhost:8080/api/jobs//events # live progress (SSE, no polling) curl localhost:8080/api/jobs//report # findings JSON (triage overlaid) curl "localhost:8080/api/jobs//report?format=md" # or format=sbom; add &download=1 # 对发现结果进行 triage — 通过 fingerprint 持久化，在重启和重新扫描后依然保留（FR-VUL-8） curl -XPOST localhost:8080/api/jobs//triage -H 'Content-Type: application/json' \ -d '{"finding_id":"","state":"false_positive"}' # 在服务端上传 artifact，然后将返回的路径作为目标提交 curl -F "file=@firmware.bin" localhost:8080/api/upload # -> {"target": "...", "name": ...} ``` 分诊状态：`new | confirmed | false_positive | accepted_risk`。重新提交未更改的目标会返回缓存的结果。 ### 输出 | 格式 | 方式 | 内容 | |---|---|---| | JSON | `--json` / `GET …/report` | 完整的结构化报告（集成契约） | | Markdown | `--md` | 执行摘要 + 每个发现结果的详情 | | CycloneDX SBOM | `--sbom` | 组件 + 检测到的 CVE（兼容 Dependency-Track） | ## 已实现的功能 | 需求 | 状态 | 位置 | |---|---|---| | FR-RE-1 反汇编（多架构） | ✅ | `re/disasm.py` (capstone) | | FR-RE-3 CFG / 调用图 / 函数边界 | ✅（符号 + 线性回退） | `re/disasm.py` | | 导入调用解析 | ✅ x86/x86_64 + ARM/AArch64 (PLT) + MIPS (GOT/`jalr $t9`) | `re/disasm.py` | | ARM/Thumb-2 + 互操作胶水代码 | ✅（映射符号模式切换，胶水代码跟随） | `re/disasm.py` | | FR-INV-4 内嵌机密/凭据 | ✅（密钥、哈希、硬编码凭据/token、熵回退） | `inventory/secrets.py` | | FR-INT-3 外部化签名规则（YARA 风格） | ✅（可更新的 JSON 规则库；可选 yara-python 桥接） | `rules/engine.py`, `data/secret_rules.json` | | FR-INV-3 脚本分析（shell/CGI 命令注入） | ✅（污点分级） | `scripts/shell.py` | | FR-INV-3 脚本分析（PHP/Python/Lua 注入） | ✅（命令/代码/文件包含/反序列化） | `scripts/langs.py` | | FS 加固（setuid、全局可写、弱权限、init） | ✅ | `fs/hardening.py` | | FR-RE-5 缓解措施 (NX/canary/RELRO/PIE/fortify) | ✅ | `re/mitigations.py` | | FR-RE-6 交叉引用（调用点、字符串） | ✅（调用/导入 xrefs） | `re/disasm.py` | | FR-RE-7 可脚本化 API | ✅（库 + CLI） | `pipeline.py`, `cli.py` | | FR-RE-2 反编译伪代码 | ✅（可选 Ghidra headless；丰富发现结果） | `re/decompile.py` | | FR-VUL-1 已知 CVE 关联 | ✅ 离线人工整理数据库 + 所需的 `cve-bin-tool`（NVD/OSV/RedHat/GitLab/Curl，350+ 组件） | `vuln/cve.py`, `vuln/cve_bin_tool.py`, `data/vuln_db.json` | | FR-VUL-2 危险函数检测 | ✅ | `vuln/dangerous_funcs.py` | | FR-VUL-3 污点 / 可达性 | ✅（调用图启发式） | `vuln/taint.py` | | FR-VUL-4 漏洞类别覆盖 | ◑ overflow/cmdi/code-inj/file-incl/deserialization/fmt/weak-crypto | `vuln/catalog.py`, `scripts/langs.py` | | FR-VUL-5 跨二进制分析 | ✅（全局调用图，CGI→lib） | `vuln/crossbinary.py` | | FR-VUL-7 优先级排序 + 证据 | ✅ | `vuln/findings.py`, `model.py` | | FR-VUL-8 分诊状态持久化 | ✅ | `vuln/findings.py` | | FR-VUL-6 模拟/动态验证 | ⬜ 计划中（可选，沙箱环境） | — | | FR-REP-1 JSON + Markdown 输出 | ✅ | `report/` | | FR-REP-2 SBOM (CycloneDX 1.5) | ✅（SPDX 待办） | `report/sbom.py` | | FR-INT-1 REST API + 队列 + Web UI（仪表盘、过滤、分诊、SSE） | ✅（Go 服务层，Alpine.js） | `service/` | | FR-ING-4 批量提交 + 去重缓存 | ✅（workers + 路径-mtime 缓存） | `service/job.go` | 图例：✅ 已完成 · ◑ 部分完成 · ⬜ 未开始 ## 准确性态势 无反编译的静态分析是一种启发式方法（需求 §5）。发现结果带有**置信度**分数；精确的调用点检测 (0.8) 排名高于导入存在检测 (0.4) 和调用图污点可达性检测 (0.5)。污点发现结果明确是供分析师验证的候选路径，而非已证实的漏洞利用。 ## 测试 ``` python3 -m pytest tests/ -q ``` 安装交叉编译器 + Ghidra 后，25 项通过，2 项跳过（跳过的是可选的实时测试 —— 见 `ENVIRONMENT.md`）。它们构建了真实的交叉编译样本（x86_64、MIPS LE/BE、ARM、ARM Thumb-2、AArch64）并涵盖了：植入的命令注入验收用例（指向 `system()` 的源→汇点路径）、各架构导入调用解析和跨二进制 RCE、缓解措施检测、CVE 关联 —— 包括人工整理的离线数据库（包括不对已修补进行标记）和 `cve-bin-tool` 的条目解析 —— 嵌入式机密（外部化签名规则 + 熵回退，带有脱敏）、shell/CGI 命令注入、PHP/Python/Lua 注入（命令/代码/文件包含/反序列化）、文件系统加固、CycloneDX SBOM、优先级排序和分诊持久化。 ## 下一次迭代 - 在现有的 `detect_taint_paths` / `detect_cross_binary_taint` 接口之后，使用 angr 替换启发式污点分析。 - FR-VUL-6 可选沙箱模拟以确认可达性。 - FR-REP-2 在 CycloneDX 之外输出 SPDX。 - 服务层加固：持久化作业存储、上传/提取前端 (FR-ING/FR-EXT)、authn/z。队列 + REST API + Web UI 已构建（`service/`）。 针对 x86/x86_64、ARM、ARM Thumb-2、AArch64 和 MIPS LE/BE 的调用解析功能均已就绪。

标签：IoT, 云资产清单, 固件分析, 日志审计, 网络测绘, 自动化分析, 跨站脚本, 逆向工具, 逆向工程