FirmScope 是一个 Go 固件安全分析 CLI。当前实现聚焦可独立验证的底层能力:递归固件解包、文件系统还原、完整目录树、内容安全检查和 ELF checksec,并输出供后续 Web 端使用的 JSON 报告。
当前版本:v0.3.0-dev
- V0.1:递归解析 ZIP/TAR/GZIP/XZ、uImage/FIT、Android boot/sparse/payload/liblp、MBR/GPT、UBI,以及 SquashFS/EXT4/FAT 文件系统,并生成 artifact 父子链和完整目录树。
- V0.2:插件化内容安全检查。
- V0.3:基于 Go
debug/elf的静态 checksec。 - JSON 报告包含输入哈希、解包统计、全部路径、插件结果、发现和 ELF 检查结果。
项目当前不包含 Web、GUI、HTTP API、数据库和 CVE 匹配。V0.4 会在组件签名与版本识别准确后再设计实施。
- Linux:一级支持环境,用于完整解包、真实样本验收和后续格式开发。
- WSL2:Windows 用户的推荐运行方式;固件输入可放在
/mnt/*,解包输出建议放在 WSL 的 Linux 文件系统。 - 原生 Windows:保留兼容支持;无法物化的 Linux 特殊节点使用元数据表达,部分格式需要项目引导的兼容后端。
FirmScope 本身不依赖 Codex。克隆仓库后,代码、测试、开发计划、报告格式和样本基线共同构成后续开发依据。Linux 迁移和交接步骤见 docs/LINUX_DEVELOPMENT.md。
Linux:
go build -o ./bin/firmscope ./cmd/firmscope
go test ./...
go vet ./...项目当前要求 Go 1.25。标准路径中的 7z/7zz、rdsquashfs 和 sasquatch 会被自动发现,也可以通过下述环境变量显式指定。
Windows 首次使用先安装固定版本的兼容后端(用于 XZ BCJ、厂商 SquashFS 和部分 EXT4 特性):
pwsh -NoProfile -File .\scripts\bootstrap-tools.ps1部分路由器使用非标准 LZMA/厂商修改版 SquashFS。FirmScope 会优先使用标准解析器;若报告明确提示需要 sasquatch,可在 Linux/WSL 中安装 devttys0/sasquatch,并通过 FIRMSCOPE_SASQUATCH 指定可执行文件。未成功解码时报告为 partial,不会把魔数识别误报为完整解包。
程序优先使用 Go 库;只有纯 Go 解码器不支持的格式特性才调用 rdsquashfs/7z。也可通过 FIRMSCOPE_RDSQUASHFS 和 FIRMSCOPE_7ZIP 指定已有工具。
go build -o .\bin\firmscope.exe .\cmd\firmscope也可以直接运行:
go run .\cmd\firmscope analyze `
-input .\firmware.zip `
-extract-dir .\output\rootfs `
-report .\output\report.json `
-through v0.3逐阶段验证时,将 -through 设置为 v0.1、v0.2 或 v0.3。目标解包目录必须不存在或为空。
查看参数:
go run .\cmd\firmscope analyze -helpartifacts/保存各层镜像,filesystems/*/root/保存还原后的文件系统;目录树覆盖两者。- Linux 符号链接和特殊节点无法在普通 Windows 目录中可靠重建时,其路径和属性保存在
.firmscope-metadata或.firmscope-special中,不会静默丢弃。 extraction.status=partial表示至少一个识别出的层未完整解出,不能视为完整成功。- 文件类型基于内容魔数和有限的文本判断,不单独信任扩展名。
not_detected表示静态证据中没有检测到,不能自动解释为安全机制已关闭。- FirmScope 不执行固件中的二进制或脚本。
- V0.2 的内容发现是安全审计线索;V0.3 是 ELF 静态属性,不等同于漏洞或可利用性结论。
完整设计和版本边界见 docs/DEVELOPMENT_PLAN.md,Linux 续接方式见 docs/LINUX_DEVELOPMENT.md,新增格式流程见 docs/ADDING_UNPACK_FORMAT.md,报告字段见 docs/REPORT_FORMAT.md,真实样本结果见 docs/SAMPLE_VALIDATION.md,版本变化见 CHANGELOG.md。