返回更新列表
新发布Jul 24, 2026

trailmark v0.5.0

构建和查询源代码的图数据库表示

分享

Trailmark

CI Mutation Testing

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
  1. 解析。 每种语言的解析器遍历目录并提取节点 (函数、类型、模块)、边(调用、继承、包含等) 以及元数据(参数、返回类型、分支、圈复杂度、 文档字符串、抛出的异常)。随后进行链接处理,解析跨文件的调用, 将类型链接到其声明,并应用 .trailmark/links.toml。
  2. 索引。 GraphStore 将图加载到 rustworkx 有向图中, 以便快速遍历。QueryEngine.from_directory() 还会运行入口点检测。
  3. 查询。 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。

支持的语言

分类