audit-augmentation

監査の拡張

外部ツール（SARIF）や人間の監査担当者（weAudit）による指摘を、アノテーションやサブグラフとしてTrailmarkのコードグラフに取り込みます。Trailmark 0.4.0+では、外部のバイナリ解析グラフのJSONエクスポートもengine.augment_binary()でインポートできます。

使用する場面

• Semgrep、CodeQLなど、SARIFを出力するツールの結果をグラフにインポートする
• weAuditの監査アノテーションをグラフにインポートする
• バイナリ解析グラフのデータをソースグラフにインポートする（Trailmark 0.4.0+）
• 静的解析の指摘を、影響範囲や汚染データと相互参照する
• 深刻度の高い指摘がある関数を検索する
• コード構造と併せて監査の網羅状況を可視化する
• trailmark-finding-triage用にSARIFまたはweAuditの結果を準備する

使用しない場面

• 静的解析ツールを実行する場合（まずsemgrep/codeqlを直接使用し、その後インポートします）
• コードグラフ自体を構築する場合（trailmarkスキルを使用します）
• 図を生成する場合（拡張後にdiagramming-codeスキルを使用します）

避けるべき誤った判断

誤った判断	誤りである理由	必須の対応
「ユーザーがSARIFについてだけ尋ねているので、事前解析は省略する」	事前解析を行わないと、指摘を影響範囲や汚染データと相互参照できません	拡張の前に必ずengine.preanalysis()を実行します
「一致しない指摘は重要ではない」	一致しない指摘は、解析の抜けや対象範囲外のファイルを示している可能性があります	一致しなかった件数を報告し、多い場合は調査します
「深刻度サブグラフは1つで十分」	深刻度ごとに異なるトリアージのワークフローが必要です	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>
• 説明：簡潔な 1 行形式： [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 ファイル形式のフィールドリファレンス