91eK9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6Y4K9i4c8Z5N6h3u0Q4x3X3g2U0L8$3#2Q4x3V1k6U0L8U0m8^5M7X3!0G2N6q4)9J5c8V1W2r3c8p5p5`.

面向 IoT 固件二进制的自动化逆向工程与漏洞发现工具。本仓库实现了
firmware-analysis-requirements.md 中描述的分析核心。

仅限防御性/授权用途。 只分析你拥有所有权或已获得授权评估的固件。详见需求文档 §1.3。

按照既定计划，第一迭代交付二进制逆向工程（FR-RE）和漏洞发现（FR-VUL）。默认摄取与解包
（FR-ING / FR-EXT）已经把文件产出到磁盘上——直接指向单个 ELF 文件或已解包的固件目录树即可。

各引擎封装了现有工具：capstone（多架构反汇编，无论宿主机架构如何都能处理 MIPS/ARM）、
pyelftools + binutils（ELF 解析、缓解措施检测）。更重的污点分析引擎（angr）作为未来
可选项，可在同一接口后面替换接入。

Python 核心是一个库 + CLI。项目选择的混合架构把批量/大规模语料的编排、REST API
（FR-INT-1）、排队（FR-ING-4）和 Web UI 放到独立的 Go 服务层（service/，已实现），
由它通过 CLI 一次驱动一个分析任务。JSON 模型（ifda/model.py）是两者之间的契约；核心
以 @@IFDA@@<json> 格式流式输出进度事件，供服务层展示实时任务进度。构建和运行方法见
service/README.md。

分析核心（Python 3.10+）

服务层（Go 1.22+）

Web UI

可选增强能力

完整的分步环境搭建（Go 升级、交叉编译器、Ghidra + JDK 的坑、验证方法）见
ENVIRONMENT.md。

cve-bin-tool 会维护自己的本地 CVE 数据库（NVD + OSV + RedHat + GitLab Advisory + Curl，
约 1GB+）；某台机器上首次扫描时会下载/更新该数据库，所以第一次运行会较慢且需要联网。
没有它的话 analyze() 仍能运行，只是 CVE 关联会退化为使用内置的小型精选数据库
data/vuln_db.json，报告里会带上一条关于该依赖缺失的明显警告（NFR-USE-1——
某个组件缺失时功能降级，而不是让整个任务崩溃）。

运行 ifda 有两种方式：CLI（单次运行，便于脚本化）和服务（队列 + REST API +
带实时进度的 Web UI）。

analyze 接受单个 ELF 文件或一个目录（已解包的固件目录树）。它会遍历目录树一次，
并运行每一个阶段：逐二进制的逆向工程/漏洞检测、跨二进制污点分析、敏感信息 +
签名规则 + 熵值检测、shell 和 PHP/Python/Lua 脚本注入检测、文件系统加固检查。

参数：-addr、-core、-workers（默认 2）、-queue、-data（分诊状态 + 上传目录；
默认 $TMPDIR/ifda-service）、-auth（默认 true）、-user/-pass（仅在账号首次创建时
播种密码——不会覆盖已经通过 Web UI 修改过的密码；加 -reset-pass 可强制覆盖）。
完整说明见 service/README.md。

Web UI（Alpine.js，内嵌——无需构建步骤，可离线使用）：提交一个服务器路径
或上传一个文件，然后查看实时 SSE 进度并浏览：

REST 接口（完整表格见 service/README.md）：

分诊状态：new | confirmed | false_positive | accepted_risk。重复提交一个未变化的
目标会直接返回缓存结果。

        ┌───────────────────────────── Python 分析核心（本仓库） ──────┐
 解包    │ loader/      re/            vuln/           inventory/ scripts/ fs/  │
 产物 ──┼► load_elf ─► disassemble ─► dangerous_funcs ► secrets  shell    加固│─► JSON /
 (FR-   │ (架构、      缓解措施       污点分析(源→汇)   + 规则/ (命令    检查  │  Markdown
  EXT)  │  导入表、    调用图         CVE 关联          签名     注入)         │  + SBOM
        │  字符串)     交叉引用       跨二进制 +        + 熵值检测              │  (CycloneDX)
        │                             优先级/分诊                             │
        └─────────────────────────────────────────────────────────────────────┘
                         ▲
                         │ 每个任务执行一次 `ifda.cli analyze --progress`
            Go 服务/编排层（service/）  ← 队列、worker、
            REST API（FR-INT-1）、去重缓存、带实时进度的 Web UI

# Python 分析核心
apt-get install -y python3-capstone python3-pyelftools   # 或: pip install -e .
pip install cve-bin-tool   # 必需: FR-VUL-1 广域 CVE 覆盖（NVD/OSV/RedHat/GitLab/Curl）
pip install yara-python    # 可选: 存在 data/yara/*.yar 时启用 YARA 阶段

# Go 服务层（可选——仅在需要 REST API + Web UI 时安装）
cd service && go build -o ifda-service .                # Go 1.22+

# 分析一个二进制文件或已解包的目录树；默认把 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）。较慢；缺失时优雅降级为空操作。
python3 -m ifda.cli analyze ./rootfs --md report.md --decompile

# 对某个发现做分诊；跨重新扫描持久保存（FR-VUL-8）。
python3 -m ifda.cli triage triage.json <finding_id> false_positive
python3 -m ifda.cli analyze ./rootfs --triage triage.json   # 已静音的发现会被剔除

cd service
go build -o ifda-service .                 # Go 1.22+，仅首次需要
./ifda-service -addr :8080 -core ..        # -core = 仓库目录（省略时自动探测）
# 打开 http://localhost:8080

# 提交一个任务（返回 {"id": ...}）；去重缓存对未变化的目标直接返回缓存结果
curl -XPOST localhost:8080/api/jobs -H 'Content-Type: application/json' \
     -d '{"target":"/path/to/extracted_rootfs"}'

curl -N  localhost:8080/api/jobs/<id>/events             # 实时进度（SSE，无需轮询）
curl     localhost:8080/api/jobs/<id>/report             # 发现结果 JSON（叠加了分诊状态）
curl     "localhost:8080/api/jobs/<id>/report?format=md" # 或 format=sbom；加 &download=1 下载

# 对某个发现做分诊——按指纹持久化，跨重启和重新扫描依然有效（FR-VUL-8）
curl -XPOST localhost:8080/api/jobs/<id>/triage -H 'Content-Type: application/json' \
     -d '{"finding_id":"<finding_id>","state":"false_positive"}'

# 把文件上传到服务器端，再把返回的路径当作 target 提交
curl -F "file=@firmware.bin" localhost:8080/api/upload   # -> {"target": "...", "name": ...}

仅限防御性/授权用途。 只分析你拥有所有权或已获得授权评估的固件。详见需求文档 §1.3。

完整的分步环境搭建（Go 升级、交叉编译器、Ghidra + JDK 的坑、验证方法）见
ENVIRONMENT.md。

[招生]科锐逆向工程师培训(2026年7月3日实地，远程教学同时开班, 第56期)！