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 tool install trailmark
# Python snippets: uv run --with trailmark python -   (a tool env is not importable)

版本要求

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 技能中的“存储库链接”部分），无需在每个会话中重新推导。每次解析时，声明的外部端点都会实例化为 proxy.external:<symbol> 节点。

快速入门

CLI

# Augment with SARIF
uv run trailmark augment {targetDir} --sarif results.sarif

# Augment with weAudit
uv run trailmark augment {targetDir} --weaudit .vscode/alice.weaudit

# Both at once, output 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")

# Run pre-analysis first for cross-referencing
engine.preanalysis()

# Augment with SARIF
result = engine.augment_sarif("results.sarif")
# result: {matched_findings: 12, unmatched_findings: 3, subgraphs_created: [...]}

# Augment with weAudit
result = engine.augment_weaudit(".vscode/alice.weaudit")

# Augment with an external binary graph export (v0.4+)
if hasattr(engine, "augment_binary"):
    result = engine.augment_binary("binary_graph.json")

# Query findings
engine.findings()                                       # All findings
engine.subgraph("sarif:error")                          # High-severity SARIF
engine.subgraph("weaudit:high")                         # High-severity weAudit
engine.subgraph("sarif:semgrep")                        # By tool name
engine.annotations_of("function_name")                  # Per-node lookup

如果自动检测到的语言不适用于目标对象，请使用显式语言或逗号分隔的语言列表（如 python,rust）重新运行。

工作流

Augmentation Progress:
- [ ] Step 1: Build graph and run pre-analysis
- [ ] Step 2: Locate SARIF/weAudit/binary graph files
- [ ] Step 3: Run augmentation
- [ ] Step 4: Inspect results and subgraphs
- [ ] Step 5: Cross-reference with pre-analysis

步骤 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+）：包含 artifact、functions 和 calls 字段的外部 JSON。Trailmark 会导入此图，但不会自行反汇编二进制文件。

步骤 3： 通过 engine.augment_sarif() 或 engine.augment_weaudit() 运行增强。对于二进制图，仅在 Version Gate 成功后运行 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 文件格式字段参考