
trailmark v0.5.0
构建和查询源代码的图数据库表示
Trailmark
Trailmark 将源代码解析为函数、类型、调用及其他关系的图,然后让你能够针对该图提出结构性问题:
- 哪些入口点可以到达此函数,以及通过哪些调用路径?
- 两次提交之间攻击面发生了什么变化?
- 哪些函数写入了这个 Solidity 存储变量?
- 调用解析在哪里停止,从而导致可达性结果不完整?
它通过 tree-sitter 解析支持的语言, 将图存储在 rustworkx 中,并通过命令行工具和 Python API 对外暴露。 Trailmark 专为安全审查而构建:每条边都会记录它是直接来自语法还是来自启发式规则,而无法解析的调用会保留在图中。
长期愿景是将此图与变异测试和覆盖率引导的模糊测试相结合,以识别从用户输入可达的、假设与测试覆盖率之间的差距。
功能
- 代码图。 函数、方法、类、结构体、trait、合约和模块,通过调用、继承、包含和类型使用相互连接。
--language auto会将目录树中所有受支持的语言合并为一张图。 - 攻击面。 框架感知的入口点检测(Flask、FastAPI、Spring、ASP.NET Core、actix-web、NestJS、Elysia HTTP 注册、Solidity 可见性等),每个入口点都标记了信任级别和资产价值。可通过
.trailmark/entrypoints.toml覆盖或扩展检测。 - 入口点证据。 检查可调用和声明式引用、可执行文件主体以及带源溯源的未解析候选。引用与执行保持分离。可通过显式排除来选择额外的源根目录。
- 可达性。 直接调用者和被调用者、传递切片,以及从入口点到目标的有界调用路径。
- 结构差异。 比较两个目录或 git 引用,报告新增或删除的声明、签名和类型变更、调用边置信度变化以及入口点。
- 图表。 Mermaid 调用图、类层次结构、模块依赖、包含视图、复杂度图和入口点到目标的流程。
- 图上的发现。 导入 SARIF 和 weAudit 结果,附加你自己的注释,并运行预分析过程(爆炸半径、权限边界、粗粒度污点),将其结果存储为注释和命名子图。
- 可见缺口。 无法解析的调用会变成代理节点而不是消失,
trailmark analyze --resolution会统计它们。 - 异常证据。 使用
exception_events()检查源定位的抛出、重新抛出、处理器和清理语法;未知的抛出操作数保持可见。有关前端覆盖范围和此语法证据的局限性,请参阅图模型。 - Trailmark 无法看到的链接。 在
.trailmark/links.toml中声明 RPC、FFI 和子进程边,或导入由二进制分析工具生成的调用图。 - 编译二进制证据。 显式检查链接的 ELF、Mach-O 和 PE 映像,将源函数和行连接到编译范围,恢复二进制调用和推断的尾转移,并在 15 种架构/模式情况下查询有界反汇编。包括剥离代码映射、通用切片、经验证的本地调试伴随文件、折叠别名和命名导入条目。有关可选的
trailmark[binary]附加组件和宿主工具要求,请参阅二进制证据。 - Solidity 存储访问。 函数与其所触及的合约状态变量之间的
reads和writes边。
安装
uv tool install trailmark # the CLI
uv add trailmark # the library, in a uv-managed project
需要 Python ≥ 3.12。CI 测试覆盖 Python 3.12 至 3.15。
使用 Nix 时,nix run github:trailofbits/trailmark 可直接运行 CLI。
本 README 及各指南跟踪 main 分支。
变更日志
列出了每个已发布版本包含的内容,CLI 和 Python API 指南
则注明了新增各较新功能的版本。
大多数语法在首次使用时下载并缓存。内置语法在首次使用时 编译,这需要 C 编译器。有关离线机器、TLS 检查代理以及从检出构建的信息,请参阅安装。
Skills 集成者:有关 schema、身份、状态和可达性检查,请参阅 v0.7 兼容性。
快速开始
# Node and edge counts for a Python project (Python is the default language)
trailmark analyze --summary path/to/project
# The same summary as JSON, including source-file counts per language (v0.7+)
trailmark analyze --summary --json --language auto path/to/project
# Full JSON graph of every supported language in the tree
trailmark analyze --language auto path/to/project > graph.json
# Detected entrypoints with trust level and asset value
trailmark entrypoints --language auto path/to/project
# How the attack surface changed between two git refs
trailmark diff --repo . main HEAD
# Mermaid call graph around one function
trailmark diagram -t path/to/project -T call-graph -f handle_request
# How many call sites could not be resolved, grouped by callee name
trailmark analyze --language rust --resolution path/to/project
目录分析会拒绝缺失的根目录和零匹配的源文件。摘要包含所选语言和已检查的文件数量;对于有意为之的空输入,请使用 --allow-empty。
图 JSON 包含导出所用的 Trailmark 版本和导出 schema 版本(v0.7+);请比较使用相同 Trailmark 版本和语言构建的快照。
来自 Python 的相同问题:
from trailmark.query.api import QueryEngine
engine = QueryEngine.from_directory("path/to/project", language="auto")
engine.attack_surface() # entrypoints and their trust levels
engine.callers_of("verify_signature") # direct callers
engine.ancestors_of("verify_signature") # everything that can reach it
engine.entrypoint_paths_to("verify_signature")
engine.complexity_hotspots(10) # cyclomatic complexity >= 10
名称可以是裸名称(verify_signature)、限定名称(Auth.verify)或完整节点 ID(auth:Auth.verify)。查询结果是可直接序列化为 JSON 的普通字典和列表。
工作原理
flowchart LR
A["Source files"] --> B["tree-sitter parsers"]
B --> C["CodeGraph"]
C --> D["GraphStore (rustworkx)"]
D --> E["QueryEngine"]
E --> F["CLI / Python API"]
classDef src fill:#007bff26,stroke:#007bff,color:#007bff
classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef query fill:#ffc10726,stroke:#e6a817,color:#e6a817
class A src
class B parse
class C,D data
class E,F query
- 解析。 每种语言的解析器遍历目录并提取节点
(函数、类型、模块)、边(调用、继承、包含等)
以及元数据(参数、返回类型、分支、圈复杂度、
文档字符串、抛出的异常)。随后进行链接处理,解析跨文件的调用,
将类型链接到其声明,并应用
.trailmark/links.toml。 - 索引。
GraphStore将图加载到 rustworkx 有向图中, 以便快速遍历。QueryEngine.from_directory()还会运行入口点检测。 - 查询。
QueryEngine将名称解析为节点 ID,执行遍历, 并返回可 JSON 序列化的结果。
示例
给定 app.py:
class Auth:
def verify(self, token):
return self._check_sig(token)
def _check_sig(self, token): ...
def handle_request(req):
auth = Auth()
if auth.verify(req.token):
return process(req)
return deny()
def process(req): ...
def deny(): ...
Trailmark 生成此图(省略了模块包含边):
graph TD
HR["app:handle_request"] -->|calls| A["app:Auth"]
HR -->|calls| PV["proxy.unresolved:auth.verify"]
HR -->|calls| P["app:process"]
HR -->|calls| D["app:deny"]
AV["app:Auth.verify"] -->|calls| CS["app:Auth._check_sig"]
A -->|contains| AV
A -->|contains| CS
classDef fn fill:#007bff26,stroke:#007bff,color:#007bff
classDef cls fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef proxy fill:#dc354526,stroke:#dc3545,color:#dc3545
class HR,P,D fn
class A,AV,CS cls
class PV proxy
self._check_sig(...) 能够解析,是因为 self 指向了所在的类。
auth.verify(...) 则无法解析,因为 Trailmark 不会推断局部变量 auth 持有的是一个 Auth 实例。该调用会保留为代理节点,而不是被丢弃。因此,engine.ancestors_of("Auth._check_sig") 只返回 app:Auth.verify,而 engine.unresolved_calls("handle_request") 会显示路径丢失的确切调用位置。关于所有节点类型、边类型和 ID 规则,请参阅
Graph model,
关于如何使用代理,请参阅
Call resolution。