Treasure Map

给 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。

快速开始 GitHub 源码

任何支持 MCP 的 agent 都能用;Claude Code、Codex、Cursor、Claude Desktop 和 dsh 由 tmap init 直接配好。

事实归工具,判断归模型。

Treasure Map,运行在你的机器上不带自己的 agent,不运行模型,不需要 API key

解包后的固件./firmware.extracted
tmap scan每个二进制跑一遍 Ghidra
两个版本fw-v1, fw-v2
tmap diffGhidra、BinExport、BinDiff

Atlas~/.treasure-map/atlas.db

事实层只读

扫描和对比得出的事实,每条都指向具体的二进制、函数和地址。

判断以事实为依据

标注层绝不影响事实层

标注层可写

你的 agent 写下的判断,每条都记录它依据的事实。

内置 MCP 服务器tmap mcp

事实:是、否,或写明原因的未知

判断:annotate、annotate_diff

你的 agentClaude Code、Codex、Cursor 等

读伪代码,追数据来源,判断哪个候选是真漏洞,并写下理由。

固件地图

每个危险调用点是地图上的一个候选,在六张同等重要的图层上各有一个读数:参数来源、可控性、写入者、可达性、途中过滤,以及所在函数是否分析完整。每个读数只有三种:是、否,或者明确的未知;“未知”会写明缺什么、为什么没查到。

示例:agent 读到的候选列表

示意数据,并非来自真实固件;字段名做了简化。

本视图显示 6 / 6 个候选

  • 没有分数。 默认视图把影响最大、又没有任何事实证明安全的调用排在最前面;agent 可以按任意图层重新排序或筛选。
  • 重新排序只改变顺序,不改变候选集合。 换一种排序不会藏起任何候选;只有你主动选择的筛选才会缩小列表。
  • 只有已证明安全的事实能让候选下沉。 无论在哪个视图里,“未知”都不会让候选下沉。未知不等于安全。
  • 是
  • 否
  • 未知,并写明原因

#1

system() 命令执行

/usr/sbin/httpd FUN_0040a1f0 +0x000124

数据来自外部是
同一函数里先调用了 recv()
攻击者能控制是
请求内容流到这个参数
写入者已查明是
snprintf() 拼出命令字符串
调用能被走到未知
没找到直接调用者,可能经由分发表调用
途中有过滤否
输入和调用之间没有检查
函数已完整分析是
函数完整反编译

为什么排在这里影响最大的一类,且没有任何事实证明它安全。

evidence_refdemo-fw#7c4e2b19:0x0040a1f0@cmd@0x000124

命令执行、内存拷贝、格式化字符串三类调用点带有函数内的参数来源分析。文件路径类调用点目前只做识别和排序,可控性只来自文本层面的读取,结果里会标明这一点。

补丁对比

tmap diff 并行对比两个版本里所有内容有变化的二进制,Ghidra、BinExport、BinDiff 全程自动完成,不用碰中间文件,最后给出函数级的补丁对比。agent 据此回答三个问题:

  • 这是不是安全修复?修的是旧版本里哪个弱点?
  • 修完整了吗?
  • 同样的调用在别处还有没有?

一次真实对比是怎么收敛的

数字来自案例里的那次运行。

  1. 文件Treasure Map

    110到4

    每格一个二进制

    110 个二进制里,106 个两边逐字节相同,直接跳过;变了的只有 4 个,只有它们进入函数级对比。

  2. 函数Treasure Map

    2262到23

    每点一对函数

    光 Challenge 这一个二进制,就有 2262 对函数被标为 changed。把地址归一化以后,绝大多数只是整体平移,判为真有代码改动的是 23 对。

  3. 结论agent

    23到3

    把这 23 对放大

    agent 读完这 23 对,报告指向三处没修彻底的地方:删了入口、没删代码的后门;只把缓冲区改大、没加长度检查的假修复;只加在浏览器里的校验。

前两步由 Treasure Map 算出,不经过模型。只有最后一步是 agent 的判断。

函数级补丁视图。
每对改动过的函数一条,按危险调用点周围的变化分组:调用的目标换了,危险调用点还在原处,或者无法判定。找不到对应函数的标为“未定”,绝不报成“删除”或“新增”。
相似度看不到的改动。
BinDiff 可能给出 similarity=1.0,而缓冲区长度其实已从 0x40 改成 0x3f。Treasure Map 会再比较地址归一化后的伪代码,标出拷贝和格式化调用处改动过的长度常量。
知道自己漏了什么的审查。
服务器选出必读改动,按工作单元分发,并统计判过多少。没读的改动标为“未读”,不算“没发现问题”;必读清单没判完,审查就不算完成。
脚本和配置也比。
脚本和配置文件按路径对比,每个文件都可以单独判断。没能对比的二进制会单独列出,绝不计为“没变”。

示例:分好组的补丁视图

示意,并非来自真实固件。

  1. 调用的目标换了

    同一处调用,新版本调到了另一个函数。

    httpd · FUN_0040b9e0

    旧版本:strcpy(local_48, pcVar1);新版本:snprintf(local_48, 0x40, "%s", pcVar1);
  2. 危险调用点还在原处

    调用本身没换,只改了一个参数。

    httpd · FUN_0040b2a4

    旧版本:strncpy(local_48, pcVar1, 0x40);新版本:strncpy(local_48, pcVar1, 0x3f);
  3. 无法判定

    两边的函数对不齐,不硬拿来比。

    upnpd · FUN_00409a10

    不给比较结果

盲区

libcfg.so没能对比:单独列出,不计为“没变”

logd · FUN_00410c00找不到对应函数:标为未定,可能被内联或挪走

为什么 agent 需要地图

agent 读懂单个函数已经不成问题。但面对整个根文件系统(上百个二进制、几万个函数),它往往看了前几条线索就收手,对没读过的代码也报“没发现问题”。有些问题,只看一个二进制回答不了:

  • 值是谁写的?

    一个程序读取的配置值(比如 nvram 键),常常是另一个程序写进去的。地图会列出每个 nvram 键由哪些程序写入、哪些程序读取,以及能不能从网页上修改。

  • 程序是谁启动的?

    Web 服务器常把活交给外部程序,哪些守护进程会跑起来由启动脚本决定。地图记录了每个程序由哪些二进制和脚本启动,/bin/sh → busybox 这类符号链接也已解析。

  • 哪些还没读?

    进度按固件里的全部候选统计,没能完整分析的函数和二进制会逐个列出,“没发现问题”和“根本没读”不会混在一起。

  • 更新改了什么?

    对比两个固件版本时,地图会找出所有改动过的二进制和文件(包括脚本、配置和网页),以及只在一个版本里存在的二进制。补丁的改动分散在几个文件里,也能一次看全。

读代码、下判断由 agent 完成。Treasure Map 记录哪些已读、已判,结论会留到下一次会话。

快速开始

开发者预览版。命令、配置、atlas 数据库和 MCP 工具字段在版本之间可能不兼容。

  1. 安装

    一条命令装好 tmap 并自动运行 tmap init:配置工具链,把 MCP 服务器注册到你选择的 agent,并为能读取 skill 的 agent 装上 diff 审查 skill。完成后重启 agent。

    curl -LsSf https://github.com/JoeyZzZzZz/treasure-map/releases/latest/download/install.sh | sh
  2. 给一个固件画地图

    输入是已解包的文件系统,用你习惯的工具解包,或者让 agent 来解。-w 是给它起的名字。

    tmap scan ./firmware.extracted -w my-fw

    然后对你的 agent 说

    用 Treasure Map 审计固件 my-fw。
    最后列出值得跟进的线索,每条附上 evidence_ref 和理由。
  3. 对比两个版本

    先分别扫描两个版本,再对比。一对固件会按二进制分成多个对比,非二进制文件单独对比。

    tmap scan ./fw_v1.extracted -w fw-v1tmap scan ./fw_v2.extracted -w fw-v2tmap 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

安装过程

  1. 来源固定所有下载都来自固定的 URL。
  2. 先校验解压前核对文件大小和 sha256。
  3. 再确认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 或其他可直接武器化的输出。只分析你合法持有的固件:你自己拥有的设备,或由厂商真正公开发布、且获取时没有绕过任何登录、付费墙或访问控制的固件。结果是候选,不是结论,需要独立的人工验证。本工具按“原样”提供,不附带任何担保。

README 里的完整声明