给 AI agent 的固件藏宝图
地图标出地形, 宝藏由你的 agent 去挖。
Treasure Map 对解包后的固件做全量静态分析,识别命令执行、内存拷贝、格式化字符串、文件路径四类危险调用点,记录参数来源、可控性、可达性等事实,并给出函数级的补丁对比。agent 通过 MCP 查询:事实由工具提供,判断由模型完成。
安装
curl -LsSf https://github.com/JoeyZzZzZz/treasure-map/releases/latest/download/install.sh | sh
装好 tmap 命令后自动运行 tmap init:配置工具链,把 MCP 服务器注册到你的 agent,并装上 diff 审查 skill。完成后重启 agent。
任何支持 MCP 的 agent 都能用;Claude Code、Codex、Cursor、Claude Desktop 和 dsh 由 tmap init 直接配好。
Treasure Map,运行在你的机器上不带自己的 agent,不运行模型,不需要 API key
./firmware.extracted tmap scan每个二进制跑一遍 Ghidrafw-v1, fw-v2tmap diffGhidra、BinExport、BinDiffAtlas~/.treasure-map/atlas.db
事实层只读
扫描和对比得出的事实,每条都指向具体的二进制、函数和地址。
判断以事实为依据
标注层绝不影响事实层
标注层可写
你的 agent 写下的判断,每条都记录它依据的事实。
tmap mcp事实:是、否,或写明原因的未知
判断:annotate、annotate_diff
你的 agentClaude Code、Codex、Cursor 等
读伪代码,追数据来源,判断哪个候选是真漏洞,并写下理由。
案例
在公开固件上从头跑到尾:命令和输出、agent 的发现和依据,还有它没看到的部分。
固件地图
每个危险调用点是地图上的一个候选,在六张同等重要的图层上各有一个读数:参数来源、可控性、写入者、可达性、途中过滤,以及所在函数是否分析完整。每个读数只有三种:是、否,或者明确的未知;“未知”会写明缺什么、为什么没查到。
示例:agent 读到的候选列表
示意数据,并非来自真实固件;字段名做了简化。
- 没有分数。 默认视图把影响最大、又没有任何事实证明安全的调用排在最前面;agent 可以按任意图层重新排序或筛选。
- 重新排序只改变顺序,不改变候选集合。 换一种排序不会藏起任何候选;只有你主动选择的筛选才会缩小列表。
- 只有已证明安全的事实能让候选下沉。 无论在哪个视图里,“未知”都不会让候选下沉。未知不等于安全。
- 是
- 否
- 未知,并写明原因
#1
system() 命令执行
/usr/sbin/httpd FUN_0040a1f0 +0x000124
- 数据来自外部是
- 同一函数里先调用了 recv()
- 攻击者能控制是
- 请求内容流到这个参数
- 写入者已查明是
- snprintf() 拼出命令字符串
- 调用能被走到未知
- 没找到直接调用者,可能经由分发表调用
- 途中有过滤否
- 输入和调用之间没有检查
- 函数已完整分析是
- 函数完整反编译
为什么排在这里影响最大的一类,且没有任何事实证明它安全。
evidence_refdemo-fw#7c4e2b19:0x0040a1f0@cmd@0x000124
命令执行、内存拷贝、格式化字符串三类调用点带有函数内的参数来源分析。文件路径类调用点目前只做识别和排序,可控性只来自文本层面的读取,结果里会标明这一点。
补丁对比
tmap diff 并行对比两个版本里所有内容有变化的二进制,Ghidra、BinExport、BinDiff 全程自动完成,不用碰中间文件,最后给出函数级的补丁对比。agent 据此回答三个问题:
- 这是不是安全修复?修的是旧版本里哪个弱点?
- 修完整了吗?
- 同样的调用在别处还有没有?
一次真实对比是怎么收敛的
-
文件Treasure Map
110到4
每格一个二进制
110 个二进制里,106 个两边逐字节相同,直接跳过;变了的只有 4 个,只有它们进入函数级对比。
-
函数Treasure Map
2262到23
每点一对函数
光 Challenge 这一个二进制,就有 2262 对函数被标为 changed。把地址归一化以后,绝大多数只是整体平移,判为真有代码改动的是 23 对。
-
结论agent
23到3
把这 23 对放大
agent 读完这 23 对,报告指向三处没修彻底的地方:删了入口、没删代码的后门;只把缓冲区改大、没加长度检查的假修复;只加在浏览器里的校验。
前两步由 Treasure Map 算出,不经过模型。只有最后一步是 agent 的判断。
- 函数级补丁视图。
- 每对改动过的函数一条,按危险调用点周围的变化分组:调用的目标换了,危险调用点还在原处,或者无法判定。找不到对应函数的标为“未定”,绝不报成“删除”或“新增”。
- 相似度看不到的改动。
- BinDiff 可能给出
similarity=1.0,而缓冲区长度其实已从0x40改成0x3f。Treasure Map 会再比较地址归一化后的伪代码,标出拷贝和格式化调用处改动过的长度常量。 - 知道自己漏了什么的审查。
- 服务器选出必读改动,按工作单元分发,并统计判过多少。没读的改动标为“未读”,不算“没发现问题”;必读清单没判完,审查就不算完成。
- 脚本和配置也比。
- 脚本和配置文件按路径对比,每个文件都可以单独判断。没能对比的二进制会单独列出,绝不计为“没变”。
示例:分好组的补丁视图
示意,并非来自真实固件。
-
调用的目标换了
同一处调用,新版本调到了另一个函数。
httpd · FUN_0040b9e0旧版本:strcpy(local_48, pcVar1);新版本:snprintf(local_48, 0x40, "%s", pcVar1); -
危险调用点还在原处
调用本身没换,只改了一个参数。
httpd · FUN_0040b2a4旧版本:strncpy(local_48, pcVar1,0x40);新版本:strncpy(local_48, pcVar1, 0x3f); -
无法判定
两边的函数对不齐,不硬拿来比。
upnpd · FUN_00409a10不给比较结果
盲区
libcfg.so没能对比:单独列出,不计为“没变”
logd · FUN_00410c00找不到对应函数:标为未定,可能被内联或挪走
为什么 agent 需要地图
agent 读懂单个函数已经不成问题。但面对整个根文件系统(上百个二进制、几万个函数),它往往看了前几条线索就收手,对没读过的代码也报“没发现问题”。有些问题,只看一个二进制回答不了:
-
值是谁写的?
一个程序读取的配置值(比如 nvram 键),常常是另一个程序写进去的。地图会列出每个 nvram 键由哪些程序写入、哪些程序读取,以及能不能从网页上修改。
-
程序是谁启动的?
Web 服务器常把活交给外部程序,哪些守护进程会跑起来由启动脚本决定。地图记录了每个程序由哪些二进制和脚本启动,
/bin/sh → busybox这类符号链接也已解析。 -
哪些还没读?
进度按固件里的全部候选统计,没能完整分析的函数和二进制会逐个列出,“没发现问题”和“根本没读”不会混在一起。
-
更新改了什么?
对比两个固件版本时,地图会找出所有改动过的二进制和文件(包括脚本、配置和网页),以及只在一个版本里存在的二进制。补丁的改动分散在几个文件里,也能一次看全。
读代码、下判断由 agent 完成。Treasure Map 记录哪些已读、已判,结论会留到下一次会话。
快速开始
开发者预览版。命令、配置、atlas 数据库和 MCP 工具字段在版本之间可能不兼容。
-
安装
一条命令装好
tmap并自动运行tmap init:配置工具链,把 MCP 服务器注册到你选择的 agent,并为能读取 skill 的 agent 装上 diff 审查 skill。完成后重启 agent。curl -LsSf https:// github.com/ JoeyZzZzZz/ treasure-map/ releases/ latest/ download/ install.sh | sh -
给一个固件画地图
输入是已解包的文件系统,用你习惯的工具解包,或者让 agent 来解。
-w是给它起的名字。tmap scan ./firmware.extracted -w my-fw 然后对你的 agent 说
用 Treasure Map 审计固件 my-fw。 最后列出值得跟进的线索,每条附上 evidence_ref 和理由。 -
对比两个版本
先分别扫描两个版本,再对比。一对固件会按二进制分成多个对比,非二进制文件单独对比。
tmap scan ./fw_v1.extracted -w fw-v1 tmap scan ./fw_v2.extracted -w fw-v2 tmap diff --before fw-v1 --after fw-v2然后对你的 agent 说
用 Treasure Map 审查固件对比 fw-v1 → fw-v2: 找出其中的安全修复,判断每处修得是否完整, 并检查新代码有没有引入新的攻击面。
scan 最耗时:每个二进制跑一遍 Ghidra,会显示进度。用同一个 -w 重新运行即可续跑。所有扫描和对比结果都存在同一个 atlas(~/.treasure-map/atlas.db)里,由 agent 自己选择处理哪个固件、哪次对比。
安装细节
完整的参数、手动注册方式和故障排查,见 README。
平台
- Linux x86_64(含 WSL2)支持
- Apple Silicon 的 macOS支持
- Intel 的 macOS工具链相同,未做验收测试
- Linux arm64、原生 Windows不支持:Ghidra 反编译器和 BinDiff 都没有对应的构建。Windows 请用 WSL2
安装过程
- 来源固定所有下载都来自固定的 URL。
- 先校验解压前核对文件大小和 sha256。
- 再确认
tmap init先给出计划,你确认才动手。
只看计划、不做改动:tmap init --dry-run。
日常维护
tmap doctor- 检查工具链、配置和 agent 注册情况,不做任何改动。
tmap update- 装上最新版本,再运行它的
tmap init。 tmap rescan- 重扫因工具升级而过期的 run;
--dry-run只列出。 tmap uninstall- 移除
tmap init装的东西,数据保留。
用途与法律声明
Treasure Map 用于固件的防御性安全审计和漏洞研究。它产出的是分析线索;按设计,它不会生成漏洞利用 PoC、payload、shellcode 或其他可直接武器化的输出。只分析你合法持有的固件:你自己拥有的设备,或由厂商真正公开发布、且获取时没有绕过任何登录、付费墙或访问控制的固件。结果是候选,不是结论,需要独立的人工验证。本工具按“原样”提供,不附带任何担保。