# Trailmark
[](https://github.com/trailofbits/trailmark/actions/workflows/ci.yml)
[](https://github.com/trailofbits/trailmark/actions/workflows/mutation.yml)
Trailmark 将源代码解析为函数、类型、调用及其他关系的图,然后让你能够针对该图提出结构性问题:
- 哪些入口点可以到达此函数,以及通过哪些调用路径?
- 两次提交之间攻击面发生了什么变化?
- 哪些函数写入了这个 Solidity 存储变量?
- 调用解析在哪里停止,从而导致可达性结果不完整?
它通过 [tree-sitter](https://tree-sitter.github.io/) 解析[支持的语言](https://github.com/trailofbits/trailmark#supported-languages),
将图存储在 [rustworkx](https://www.rustworkx.org/) 中,并通过命令行工具和 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()` 检查源定位的抛出、重新抛出、处理器和清理语法;未知的抛出操作数保持可见。有关前端覆盖范围和此语法证据的局限性,请参阅[图模型](https://github.com/trailofbits/trailmark/blob/main/docs/graph-model.md#exception-evidence)。
- **Trailmark 无法看到的链接。** 在 `.trailmark/links.toml` 中声明 RPC、FFI 和子进程边,或导入由二进制分析工具生成的调用图。
- **编译二进制证据。** 显式检查链接的 ELF、Mach-O 和 PE 映像,将源函数和行连接到编译范围,恢复二进制调用和推断的尾转移,并在 15 种架构/模式情况下查询有界反汇编。包括剥离代码映射、通用切片、经验证的本地调试伴随文件、折叠别名和命名导入条目。有关可选的 `trailmark[binary]` 附加组件和宿主工具要求,请参阅[二进制证据](https://github.com/trailofbits/trailmark/blob/main/docs/binaries.md)。
- **Solidity 存储访问。** 函数与其所触及的合约状态变量之间的 `reads` 和 `writes` 边。
## 安装
```bash
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` 分支。
[变更日志](https://github.com/trailofbits/trailmark/blob/main/CHANGELOG.md)
列出了每个已发布版本包含的内容,CLI 和 Python API 指南
则注明了新增各较新功能的版本。
大多数语法在首次使用时下载并缓存。内置语法在首次使用时
编译,这需要 C 编译器。有关离线机器、TLS 检查代理以及从检出构建的信息,请参阅[安装](https://github.com/trailofbits/trailmark/blob/main/docs/installation.md)。
Skills 集成者:有关 schema、身份、状态和可达性检查,请参阅 [v0.7 兼容性](https://github.com/trailofbits/trailmark/blob/main/docs/skills-compatibility.md)。
## 快速开始
```bash
# 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 的相同问题:
```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 的普通字典和列表。
## 工作原理
```mermaid
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`:
```python
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 生成此图(省略了模块包含边):
```mermaid
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](https://github.com/trailofbits/trailmark/blob/main/docs/graph-model.md),
关于如何使用代理,请参阅
[Call resolution](https://github.com/trailofbits/trailmark/blob/main/docs/call-resolution.md)。
## 支持的语言
| 语言 | 扩展名 | `--language` | 提取内容 |
| --- | --- | --- | --- |
| Python | `.py` | `python` | 函数、类、方法 |
| R | `.r` | `r` | 命名/匿名函数、闭包、默认值、分支、调用、包/源依赖 |
| JavaScript | `.js`、`.jsx`、`.mjs`、`.cjs` | `javascript` | 函数、类、箭头函数 |
| TypeScript | `.ts`、`.tsx` | `typescript` | 函数、类、接口、枚举 |
| PHP | `.php`、`.phtml` | `php` | 函数、类、接口、trait、脚本/模板主体、管道调用和部分可调用引用 |
| Perl | `.pl`、`.pm` | `perl` | 包、子程序、签名/原型、匿名子程序、脚本调用、导入 |
| Ruby | `.rb` | `ruby` | 方法、类、模块 |
| Lua | `.lua` | `lua` | 局部/全局函数、表方法、匿名函数、代码块、导入、直接调用 |
| C | `.c`、`.h` | `c` | 函数、结构体、枚举 |
| Bash | `.sh`、`.bash` | `bash` | 函数、脚本执行、分支、命令、字面源依赖 |
| C++ | `.cpp`、`.cc`、`.cxx`、`.hpp`、`.hh`、`.hxx` | `cpp` | 函数、类、结构体、命名空间 |
| C# | `.cs` | `c_sharp` | 方法、类、接口、结构体、枚举、命名空间 |
| PowerShell | `.ps1`、`.psm1` | `powershell` | 函数、筛选器、类、方法、脚本块、参数、命令调用、导入 |
| Java | `.java` | `java` | 方法、类、接口、枚举 |
| VB.NET | `.vb` | `vb` | 命名空间、模块、类型、方法、构造函数/访问器、lambda、重载、直接调用 |
| Go | `.go` | `go` | 函数、方法、结构体、接口 |
| Rust | `.rs` | `rust` | 函数、结构体、trait、枚举、impl 块、`verus!` 块 |
| Solidity | `.sol` | `solidity` | 合约、接口、库、函数、修饰器、结构体、枚举、状态变量 |
| Aiken | `.ak` | `aiken` | 验证器、处理器、辅助函数、自定义类型、导入、直接调用和管道调用 |
| Cairo | `.cairo` | `cairo` | 函数、trait、结构体、枚举、impl 块、StarkNet 合约 |
| Circom | `.circom` | `circom` | 模板、函数、信号、组件 |
| Haskell | `.hs` | `haskell` | 函数、数据类型、类型类、实例 |
| Lean 4 | `.lean` | `lean` | 定义、定理、命名空间、结构体、类、归纳类型、导入、项应用、显式符号和类型化字段引用 |
| Dafny | `.dfy` | `dafny` | 模块、类、数据类型、函数、方法、引理、契约和显式引用 |
| F* | `.fst`、`.fsti` | `fstar` | 声明、接口、精化、模块导入、显式引用和计算应用 |
| Rocq/Coq | `.v` | `rocq` | Gallina 声明、模块、假设、定理陈述和显式引用;需显式选择 `rocq` |
| WhyML | `.mlw`、`.why` | `whyml` | 模块和隐式文件模块、程序、数组、幽灵代码、契约和显式引用(部分语法覆盖) |
| TLA+ | `.tla` | `tlaplus` | 模块、状态变量、运算符、假设、定理和规范引用 |
| Tamarin | `.spthy` | `tamarin` | 规则、函数和事实符号、宏、谓词、包含、条件语句和规范引用 |
| ProVerif | `.pv`、`.pvl` | `proverif` | 类型化 pi 演算函数、事件、进程、查询和符号引用 |
| Julia | `.jl` | `julia` | 模块、类型、长/短函数、闭包、签名、分支、导入、保守的局部调用 |
| Erlang | `.erl` | `erlang` | 函数、记录、行为、模块 |
| Miden Assembly | `.masm` | `masm` | 过程、入口点、常量、调用 |
| Swift | `.swift` | `swift` | 函数、类、结构体、枚举、协议、扩展 |
| Objective-C | `.m`、`.mm`、`.h` | `objc` | C 函数、类、方法(基于选择器的命名) |
| Kotlin | `.kt`、`.kts` | `kotlin` | 函数、类、接口、数据类、对象、方法 |
| Dart | `.dart` | `dart` | 函数、类、抽象类、方法、构造函数 |
| Move | `.move` | `move` | 模块、函数、导入、直接调用 |
| Tact | `.tact` | `tact` | 合约、结构体、接收器、函数 |
| Func | `.fc`、`.func` | `func` | 函数、包含、直接调用 |
| Sway | `.sw` | `sway` | ABI 接口、结构体、impl 方法、函数 |
| Zig | `.zig` | `zig` | 函数、具名结构体/枚举/联合体、容器方法、导入、直接调用 |
| Rego | `.rego` | `rego` | 包、导入、策略规则、规则调用 |
| Proto | `.proto` | `proto` | 服务、RPC、消息、字段、枚举 |
| Thrift | `.thrift` | `thrift` | 服务、函数、结构体、字段、枚举 |
| GraphQL | `.graphql`、`.gql`、`.graphqls` | `graphql` | 对象类型、根操作、字段、枚举 |
| SQL | `.sql` | `sql` | 模式、表、视图、函数、存储过程 |
传入 `--language auto` 以自动检测语言,或传入逗号分隔的列表,例如
`--language python,rust`。[语言说明](https://github.com/trailofbits/trailmark/blob/main/docs/languages.md)
涵盖 Rust 与 Verus 的作用域、Solidity 存储访问、头文件处理,以及
其他各语言特有的行为。
## 文档
| 指南 | 涵盖内容 |
| --- | --- |
| [CLI 参考](https://github.com/trailofbits/trailmark/blob/main/docs/cli.md) | 每个子命令、标志和输出格式 |
| [Python API](https://github.com/trailofbits/trailmark/blob/main/docs/python-api.md) | `QueryEngine` 方法、名称查找、路径查询、仅解析 API |
| [图模型](https://github.com/trailofbits/trailmark/blob/main/docs/graph-model.md) | 节点与边类型、置信度、节点 ID、代理、目录遍历 |
| [入口点](https://github.com/trailofbits/trailmark/blob/main/docs/entrypoints.md) | 检测层、框架覆盖范围、`.trailmark/entrypoints.toml` |
| [跨语言链接](https://github.com/trailofbits/trailmark/blob/main/docs/links.md) | 用于 RPC、FFI 和外部边的 `.trailmark/links.toml` |
| [发现与预分析](https://github.com/trailofbits/trailmark/blob/main/docs/augmenting.md) | SARIF、weAudit、二进制调用图、注解、预分析遍历 |
| [调用解析](https://github.com/trailofbits/trailmark/blob/main/docs/call-resolution.md) | 衡量未解析的调用及其对可达性的意义 |
| [语言说明](https://github.com/trailofbits/trailmark/blob/main/docs/languages.md) | Rust 与 Verus、Solidity 状态、TypeScript、SQL、C 系头文件 |
| [解析器覆盖范围](https://github.com/trailofbits/trailmark/blob/main/docs/parser-coverage.md) | 可调用对象归属、声明标识与语法限制 |
| [安装](https://github.com/trailofbits/trailmark/blob/main/docs/installation.md) | 语法缓存、离线安装、捆绑语法、Nix、检出 |
| [变更日志](https://github.com/trailofbits/trailmark/blob/main/CHANGELOG.md) | 每个版本的变更内容 |
## 智能体技能
[Trailmark 插件](https://github.com/trailofbits/skills/tree/main/plugins/trailmark)
将 Trailmark 工作流打包为智能体技能,包括调用图
摘要、图表生成、发现分类和差异审查。
## 局限性
Trailmark 基于语法和命名构建其图。它不编译代码,因此:
- 路径是调用图可达性,而非攻击者控制的数据流。
预分析污点是粗略且独立的信号。
- 动态分派、需要参数类型的重载,以及通过
需要推断类型的接收者发起的调用,均保持未解析状态。
- 宏处理是部分的:有界的 C 声明包装器可以展开,
而任意预处理和隐式调用(如析构函数)则不会被
建模。
- 缺失的边并不能证明某个调用或存储访问不可能发生。
每份指南都列出了其功能特有的限制。
## 贡献
参见 [CONTRIBUTING.md](https://github.com/trailofbits/trailmark/blob/main/CONTRIBUTING.md)
了解环境搭建、检查、变异测试,以及如何添加语言解析器。
## 许可证
Apache-2.0