一、基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 正式名称 | trailmark（合集仓库子技能，完整标识见下） | 合集仓库子目录名 |
| 所属合集仓库 | trailofbits/skills（Trail of Bits Skills Marketplace，官方安全技能市场） | GitHub API |
| 所属插件 | trailmark（同名插件，内含 13 个子技能 + 1 个子代理，本报告聚焦其中的核心图查询技能 trailmark） |
plugin.json |
| 作者/维护者 | Scott Arciszewski（Trail of Bits 工程师，GitHub 账号 tob-scott-a） | plugin.json |
| 来源链接 | https://github.com/trailofbits/skills/tree/main/plugins/trailmark/skills/trailmark | — |
| 许可证 | 仓库内容 CC-BY-SA-4.0；底层依赖 Trailmark 工具库为 Apache-2.0 | GitHub API |
| 合集仓库整体 Stars/Forks | 6,411 / 554（注：该数字属整个合集仓库，不代表本技能自身热度，仅供了解所属市场规模） | GitHub API |
| Trailmark 工具库自身 Stars | 454（trailofbits/trailmark 独立仓库，2026-03-03 创建，5 个月内积累） | GitHub API |
| 该技能自身活跃度 | 2026-03-31 首次加入（PR #133）；2026-04-29 适配公开 0.2.x 版本（PR #153）；2026-07-29 新增 v0.4/v0.5 版本特性支持（PR #183）；同一插件内其余 12 个子技能于 2026-06-11～07-28 期间逐个加入 | GitHub API（按路径过滤提交历史 + PR 记录） |
| 插件版本 | v0.10.0 | plugin.json |
| 安装方式 | Claude Code / Codex 插件市场安装（见第十章） | 官方 README |
二、功能介绍与亮点
trailmark 把源代码解析为一张包含函数、类、调用关系与语义标注的有向图，供安全分析查询使用——官方博客称之为“让防御者也能像攻击者一样用图思考”：传统工具产出扁平问题列表，而“某输入能否到达某危险函数”天然是图上的可达性问题。
- 多语言统一图模型：基于 tree-sitter 做语言无关的 AST 解析，覆盖 Python、JS/TS、C/C++、Rust、Go、Java、C#、Solidity、Cairo 等 22+ 种语言，可在同一张图里跨语言查询
- 四阶段预分析：影响半径估算、可信度分级的入口点枚举、信任边界跃迁检测、污点传播标注——运行一次
preanalysis()即可为后续查询提供统一证据基础 - 版本特性门控：SKILL.md 要求先探测已安装的 Trailmark 版本（0.2.x/0.4.x/0.5.x）再决定调用哪些 API，并给出降级示例，避免在旧版本环境误用新特性
- 与同插件内其余 12 个技能共享同一张图：可直接交给变异测试分诊、结构化差异比对、PR 安全门禁、单条发现分诊等技能复用，避免重复解析
- 可导入外部证据：支持把 SARIF、weAudit 标注甚至二进制分析图投影到源码图上，形成统一审计证据视图
三、适用场景
固定分类：安全与合规
适合安全审计师、渗透测试工程师面对不熟悉的中大型代码库时，快速建立“输入从哪里进来、能到达哪些敏感函数、改动会波及多大范围”的结构化认知；也适合在提交漏洞报告前，用可达性与影响半径数据支撑“是否真的可被利用”的判断，替代逐文件人工翻阅理解调用关系。
四、跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 官方安装方式即 Claude Code 插件市场机制（/plugin marketplace add + /plugin menu），SKILL.md 遵循 Claude Agent Skills 标准格式 |
| Codex | 原生支持 | 仓库根 README 明确写明“Codex supports Claude plugin marketplaces directly”，并给出 codex plugin marketplace add / codex plugin add <name>@trailofbits 专用安装命令（已抓取原文验证） |
| OpenClaw | 未验证 | 已抓取材料未提及 OpenClaw 支持，未为此单独搜索 |
| Hermes Agent | 未验证 | 已抓取材料未提及 Hermes 支持 |
五、推荐理由
代码审计里最耗时的往往不是找到一个可疑函数，而是回答“它到底能不能被外部输入触达、改了它会牵连多少下游代码”——通读调用链才能回答，人工做既慢又容易漏。trailmark 把这个过程变成一次图构建加几行查询：预分析一次性给出可达性、影响半径、信任边界、污点传播四类结构化证据，且证据可直接喂给同工具家族的下游技能复用。作为 Trail of Bits 官方出品且近期刚完成大版本适配的技能，文档与版本兼容性说明都相当扎实。
六、评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 合集仓库整体热度不计入本技能个体分；Trail of Bits 官方博客发文《Trailmark turns code into graphs》专题介绍该工具，第三方技术媒体 Starlog 亦独立撰文覆盖；底层 Trailmark 工具库独立仓库 5 个月内积累 454 星，同插件家族 2026-03～07 期间持续有 9 个 PR 迭代，热度证据来自官方发文与独立第三方报道两条渠道 |
| 可用性 | 8 | 需先执行 uv pip install trailmark 安装底层工具库（免费开源，无付费依赖），随后一条 CLI 命令或几行 Python API 即可查询；SKILL.md 文档详实，含快速开始示例、版本特性门控指南与常见误用纠正表；技能内容最近一次实质更新为 2026-07-29（距今 5 天），维护活跃度高 |
| 安全性 | 8 | 见下方安全检查清单 |
| 综合评分 | 8.0 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | 需通过 Bash 调用 uv run trailmark CLI 或 Python API 在本地解析代码，权限范围明确且用途透明（构建/查询代码图），无隐藏的额外 shell 操作 |
| ② 运行时联网外发 | 安装阶段从 PyPI 拉取 trailmark 包（公开注册表，来源透明）；日常分析阶段纯本地文件解析，未发现向第三方服务器外发代码或数据的行为 |
| ③ API Key/凭据 | 不涉及，技能本身不接触任何凭据 |
| ④ 可疑指令排查 | 已完整抓取并阅读 SKILL.md 全文，未发现 prompt injection 或隐藏指令迹象；文档中的“Rationalizations to Reject”表是引导 Agent 遵循正确流程的设计模式，非可疑指令 |
| ⑤ 作者/组织信誉 | Trail of Bits——知名安全研究与审计公司，plugin.json 具名声明维护工程师及 GitHub 主页 |
| ⑥ License | 仓库内容 CC-BY-SA-4.0，底层 Trailmark 工具库 Apache-2.0，均为清晰的开源许可证 |
| ⑦ 最近维护 | 技能自身最近一次实质更新 2026-07-29（5 天前）；所属插件仓库当日（2026-08-03）仍有提交，维护活跃 |
未给可用性满分的原因：需要额外安装底层 Python 工具库这一前置步骤，并非“复制即用”，版本特性门控逻辑对初级用户也有一定理解门槛。
七、跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本 skill 的差异 |
|---|---|---|
| static-analysis（同市场） | 整合 CodeQL、Semgrep 与 SARIF 解析的规则型静态分析工具箱 | 依赖预定义规则库匹配已知模式；本 skill 构建可自由查询的调用图，回答规则库难以覆盖的可达性问题，二者可互补 |
| differential-review（同市场） | 基于 git 历史的文本级安全差异审查 | 比较代码文本改动；本 skill 的姊妹技能比较两个快照间“结构”变化（新增攻击路径、权限边界漂移），能发现文本 diff 很小但调用图变化很大的情况 |
| CodeQL（GitHub 官方查询引擎） | 将代码编译为关系型数据库，用专用查询语言 QL 检索漏洞模式 | 功能定位相近，但 CodeQL 需学习专用查询语言且主要面向已编译语言；本 skill 用 tree-sitter 支持更广的动态语言与 DSL（如 Solidity），并原生设计为由 LLM Agent 直接调用 Python API |
核心差异化：市面安全分析工具多是“规则匹配”或“文本比对”路线，trailmark 把代码变成一张可编程查询的图，且能被同家族其余技能直接复用，形成共享一份结构化证据的分析链路。
八、用户评价
Trail of Bits 官方博客发文《Trailmark turns code into graphs》介绍该工具的设计动机与技术细节，第三方技术媒体 Starlog 亦发布独立报道《Trailmark: Building Security-Focused Code Graphs Across 22+ Languages》。目前未发现来自 Reddit、Hacker News 等社区平台的具名用户评价。
九、其他补充
trailmark 所属插件打包了 13 个协同子技能（图查询、代码切片、Mermaid 生成、变异测试分诊、协议验证、审计证据投影等）与 1 个子代理，安装插件即获得完整工具链；本报告聚焦承担图构建与基础查询职责的核心技能 trailmark。
十、安装使用方式
Claude Code 插件市场（推荐）：
/plugin marketplace add trailofbits/skills
/plugin install trailmark@trailofbits（或执行 /plugin menu 交互式浏览并选择安装 trailmark 插件）
Codex：
codex plugin marketplace add trailofbits/skills
codex plugin add trailmark@trailofbits安装后注意事项： 插件安装无需重启；首次分析代码前需执行 uv pip install trailmark 安装底层工具库（需本机已具备 uv），命令缺失或报错时应先完成安装而非退化为人工读码。就绪后向 Agent 描述“分析调用链/攻击面/影响半径”等需求即可触发。
十一、注意事项
- 前置依赖：需要 Python 环境、
uv包管理工具及联网安装trailmark包，非零配置开箱即用； - 能力边界：Trailmark 为静态分析工具，不做动态运行时分析；污点传播是粗粒度信号，官方文档要求不能将其直接当作“输入确实到达汇点”的证明；
- 该技能是合集仓库插件内的子技能，来源链接与安装命令务必使用本报告给出的路径；
- 除 Claude Code / Codex 外，OpenClaw、Hermes Agent 兼容性尚无可验证材料，如需使用请自行测试。