audit-augmentation

稽核擴充

將外部工具（SARIF）與人工稽核員（weAudit）的發現投射到 Trailmark 程式碼圖形上，作為註解與子圖。Trailmark 0.4.0+ 也可透過 engine.augment_binary() 匯入外部二進位分析圖形 JSON 匯出。

使用時機

• 將 Semgrep、CodeQL 或其他產生 SARIF 的工具結果匯入圖形
• 將 weAudit 稽核註解匯入圖形
• 將二進位分析圖形資料匯入原始碼圖形（Trailmark 0.4.0+）
• 將靜態分析發現與爆炸半徑或汙染資料交叉參照
• 查詢哪些函式有高嚴重性發現
• 在程式碼結構脈絡中視覺化稽核覆蓋率
• 準備單一 SARIF 或 weAudit 結果供 trailmark-finding-triage 使用

不應使用時機

• 執行靜態分析工具（請直接使用 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 檔案格式欄位參考