audit-augmentation

审计增强

将来自外部工具（SARIF）和人工审计员（weAudit）的发现作为注释和子图投影到 Trailmark 代码图上。Trailmark 0.4.0+ 还可以通过 engine.augment_binary() 导入外部二进制分析图 JSON 导出。

何时使用

• 将 Semgrep、CodeQL 或其他产生 SARIF 的工具的结果导入到图中
• 将 weAudit 审计注释导入到图中
• 将二进制分析图数据导入到源图中（Trailmark 0.4.0+）
• 将静态分析发现与爆炸半径或污点数据交叉引用
• 查询哪些函数具有高严重性发现
• 在代码结构旁边可视化审计覆盖范围
• 为 trailmark-finding-triage 准备一个 SARIF 或 weAudit 结果

何时不使用

• 运行静态分析工具（直接使用 semgrep/codeql，然后导入）
• 构建代码图本身（使用 trailmark 技能）
• 生成图表（增强后使用 diagramming-code 技能）

应拒绝的理由

理由	错误原因	必要操作
"用户只问了 SARIF，跳过预分析"	没有预分析，无法将发现与爆炸半径或污点交叉引用	在增强前始终运行 engine.preanalysis()
"未匹配的发现无关紧要"	未匹配的发现可能表明解析差距或范围外文件	报告未匹配数量，如果较高则调查
"一个严重性子图就够了"	不同严重性需要不同的分类工作流	查询所有严重性子图，而不仅仅是 error
"SARIF 结果本身就能说明问题"	没有图上下文的发现缺乏爆炸半径和污点可达性	与预分析子图交叉引用
"weAudit 和 SARIF 重叠，选一个"	人工审计员和工具发现不同的问题	如果可用，两者都导入
"工具未安装，我手动做"	手动分析会遗漏工具能捕获的内容	首先安装 trailmark

---

安装

必须： 如果 uv run trailmark 失败，请先安装 trailmark：

uv pip install trailmark

版本门控

SARIF 和 weAudit 增强是 v0.2 安全的。二进制图增强仅限 Trailmark 0.4.0+。在调用 engine.augment_binary() 之前，请检查：

if not hasattr(engine, "augment_binary"):
    raise RuntimeError("Binary augmentation requires Trailmark >= 0.4.0")

在 Trailmark 0.5.0+ 上，源函数与导入的二进制或外部端点之间的已知链接也可以在 .trailmark/links.toml 中声明一次（请参阅主 trailmark 技能的 Repository Links 部分），而不是每次会话重新派生。声明的外部端点在每次解析时作为 proxy.external:<symbol> 节点实现。

快速开始

CLI

# 使用 SARIF 增强
uv run trailmark augment {targetDir} --sarif results.sarif

# 使用 weAudit 增强
uv run trailmark augment {targetDir} --weaudit .vscode/alice.weaudit

# 同时使用两者，输出 JSON
uv run trailmark augment {targetDir} \
    --sarif results.sarif \
    --weaudit .vscode/alice.weaudit \
    --json

二进制图增强在 Trailmark 0.4.0+ 中是编程式的；如果 trailmark augment --help 没有显示 CLI 标志，请不要发明一个。

编程 API

from trailmark.query.api import QueryEngine

engine = QueryEngine.from_directory("{targetDir}", language="auto")

# 首先运行预分析以进行交叉引用
engine.preanalysis()

# 使用 SARIF 增强
result = engine.augment_sarif("results.sarif")
# result: {matched_findings: 12, unmatched_findings: 3, subgraphs_created: [...]}

# 使用 weAudit 增强
result = engine.augment_weaudit(".vscode/alice.weaudit")

# 使用外部二进制图导出增强（v0.4+）
if hasattr(engine, "augment_binary"):
    result = engine.augment_binary("binary_graph.json")

# 查询发现
engine.findings()                                       # 所有发现
engine.subgraph("sarif:error")                          # 高严重性 SARIF
engine.subgraph("weaudit:high")                         # 高严重性 weAudit
engine.subgraph("sarif:semgrep")                        # 按工具名称
engine.annotations_of("function_name")                  # 按节点查找

如果目标语言的自动检测错误，请使用显式语言或逗号分隔列表重新运行，例如 python,rust。

工作流

增强进度：
- [ ] 步骤 1：构建图并运行预分析
- [ ] 步骤 2：定位 SARIF/weAudit/二进制图文件
- [ ] 步骤 3：运行增强
- [ ] 步骤 4：检查结果和子图
- [ ] 步骤 5：与预分析交叉引用

步骤 1： 构建图并运行预分析以获取爆炸半径和污点上下文：

engine = QueryEngine.from_directory("{targetDir}", language="auto")
engine.preanalysis()

如果目标语言的自动检测错误，请使用显式语言或逗号分隔列表重新运行，例如 python,rust。

步骤 2： 定位输入文件：

• SARIF：通常由工具输出，例如 semgrep --sarif -o results.sarif 或 codeql database analyze --format=sarif-latest
• weAudit：存储在工作区中的 .vscode/<username>.weaudit 中
• 二进制图（v0.4+）：外部 JSON，包含 artifact、functions 和 calls 字段。Trailmark 导入此图；它本身不反汇编二进制文件。

步骤 3： 通过 engine.augment_sarif() 或 engine.augment_weaudit() 运行增强。对于二进制图，仅在版本门控成功后运行 engine.augment_binary()。检查 SARIF 和 weAudit 结果中的 unmatched_findings——这些是文件/行位置未与任何已解析代码单元重叠的发现。

步骤 4： 查询发现和子图。使用 engine.findings() 列出所有带注释的节点。使用 engine.subgraph_names() 查看可用的子图。

步骤 5： 与预分析数据交叉引用以确定优先级：

• 污点节点上的发现：将 sarif:error 与 tainted 子图重叠
• 高爆炸半径节点上的发现：与 high_blast_radius 重叠
• 权限边界上的发现：与 privilege_boundary 重叠

对于一个需要可达性判断或 PoC 交接的候选发现，继续使用 trailmark-finding-triage，并将增强后的节点作为绑定候选。

注释格式

发现存储为标准 Trailmark 注释：

• 种类：finding（工具生成）或 audit_note（人工注释）
• 来源：sarif:<tool_name> 或 weaudit:<author>
• 描述：紧凑单行：
  [SEVERITY] rule-id: message (tool)

创建的子图

子图	内容
sarif:error	具有 SARIF 错误级别发现的节点
sarif:warning	具有 SARIF 警告级别发现的节点
sarif:note	具有 SARIF 注意级别发现的节点
sarif:<tool>	被特定工具标记的节点
weaudit:high	具有高严重性 weAudit 发现的节点
weaudit:medium	具有中严重性 weAudit 发现的节点
weaudit:low	具有低严重性 weAudit 发现的节点
weaudit:findings	所有 weAudit 发现（entryType=0）
weaudit:notes	所有 weAudit 注释（entryType=1）
binary:<artifact>	从 v0.4+ 二进制图导入的二进制函数节点

匹配原理

发现通过文件路径和行范围重叠匹配到图节点：

1. 发现文件路径相对于图的 root_path 进行规范化
2. 选择 location.file_path 匹配且行范围重叠的节点
3. 优先选择最紧密的匹配（最小跨度）
4. 如果发现的位置不与任何节点重叠，则计为未匹配

SARIF 路径可以是相对路径、绝对路径或 file:// URI——所有这些都会被处理。weAudit 使用从 0 开始索引的行，这些行会自动转换为从 1 开始索引。

二进制图导入创建 origin=binary 函数节点、用于未解析二进制调用的 origin=proxy 外部代理节点，以及当二进制函数映射回源节点时的推断 corresponds_to 边。预期的 JSON 形状故意很小：

{
  "artifact": {"name": "libexample", "architecture": "x86_64", "sha256": "..."},
  "functions": [
    {"symbol": "parse_packet", "address": "0x401000",
     "source": {"file": "src/parser.c", "line": 42}}
  ],
  "calls": [
    {"source": "parse_packet", "target": "malloc", "confidence": "inferred"}
  ]
}

支持文档

• references/formats.md — SARIF 2.1.0 和 weAudit 文件格式字段参考