監査拡張（Audit Augmentation）

外部ツール（SARIF）と人間の監査者（weAudit）からの結果を Trailmark コードグラフにアノテーションとサブグラフとして投影します。

使用する場合

• Semgrep、CodeQL、またはその他の SARIF 生成ツールの結果をグラフにインポートする場合
• weAudit 監査アノテーションをグラフにインポートする場合
• 静的解析結果を blast radius または taint データと相互参照する場合
• 高重要度の結果を持つ関数をクエリする場合
• コード構造と並行して監査カバレッジを可視化する場合

使用しない場合

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

拒否すべき判断根拠

判断根拠	何が間違っているのか	必要なアクション
「ユーザーは SARIF についてのみ尋ねたため、事前分析をスキップする」	事前分析なしでは、結果を blast radius や taint と相互参照できない	拡張前に必ず engine.preanalysis() を実行する
「マッチしない結果は重要ではない」	マッチしない結果は、解析ギャップやスコープ外のファイルを示す可能性がある	マッチしない件数を報告し、件数が多い場合は調査する
「1つの重要度サブグラフで十分」	異なる重要度は異なるトリアージワークフローが必要	error だけでなく、すべての重要度のサブグラフをクエリする
「SARIF 結果は自明」	グラフコンテキストなしの結果は、blast radius と taint 到達可能性を欠く	事前分析サブグラフと相互参照する
「weAudit と SARIF は重複しており、どちらかを選ぶ」	人間の監査者とツールは異なるものを見つける	両方が利用可能な場合は両方をインポートする
「ツールがインストールされていないため、手作業で行う」	手作業による分析はツーリングが見つけるものを見逃す	まず trailmark をインストールする

---

インストール

必須: uv run trailmark が失敗する場合、まず trailmark をインストールしてください：

uv pip install trailmark

クイックスタート

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

プログラム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")

# 結果をクエリ
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: グラフを構築し、blast radius と taint コンテキストの事前分析を実行します：

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 に保存

ステップ 3: engine.augment_sarif() または engine.augment_weaudit() で拡張を実行します。結果の unmatched_findings を確認してください — これらは、ファイル/行位置が解析されたコードユニットとオーバーラップしなかった結果です。

ステップ 4: 結果とサブグラフをクエリします。engine.findings() を使用してアノテーション付きのすべてのノードを一覧表示します。engine.subgraph_names() を使用して利用可能なサブグラフを確認します。

ステップ 5: 事前分析データと相互参照して優先順位を付けます：

• Tainted ノード上の結果: sarif:error を tainted サブグラフと重ね合わせる
• 高い blast radius ノード上の結果: high_blast_radius と重ね合わせる
• 特権境界上の結果: privilege_boundary と重ね合わせる

アノテーション形式

結果は標準 Trailmark アノテーションとして保存されます：

• Kind: finding（ツール生成）または audit_note（人間のメモ）
• Source: sarif:<tool_name> または weaudit:<author>
• Description: コンパクトな 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）

マッチング方法

結果は、ファイルパスと行範囲のオーバーラップによってグラフノードにマッチします：

1. 結果のファイルパスはグラフの root_path に対して正規化されます
2. location.file_path がマッチし、かつ行範囲がオーバーラップするノードが選択されます
3. 最もタイトなマッチ（最小スパン）が優先されます
4. 結果の位置がノードとオーバーラップしない場合、マッチしないとカウントされます

SARIF パスは相対パス、絶対パス、または file:// URI である可能性があり、すべて処理されます。weAudit は 0 インデックスの行を使用し、自動的に 1 インデックスに変換されます。

関連ドキュメント

• references/formats.md — SARIF 2.1.0 および weAudit ファイル形式フィールドリファレンス