Trailmark

ソースコードを関数、クラス、呼び出し、およびセマンティックメタデータの有向グラフに解析し、セキュリティ分析に使用します。

使用する場面

• ユーザー入力から機密関数への呼び出しパスをマッピングする
• 監査優先順位付けのための複雑性ホットスポットを特定する
• 攻撃面とエントリーポイントを識別する
• 不慣れなコードベースの呼び出し関係を理解する
• ポリグロットプロジェクト全体のセキュリティレビューまたは監査準備
• コードユニットへの LLM 推論アノテーション (仮定、前提条件) を追加する
• ミューテーションテスト (genotoxic スキル) またはダイアグラミング前の事前分析

使用してはいけない場面

• 呼び出しグラフに価値がない単一ファイルスクリプト (ファイルを直接読む)
• コード由来でないアーキテクチャダイアグラム (diagramming-code スキルを使用するか手作業で作成する)
• ミューテーションテスト トリアージ (genotoxic スキルを使用。内部で trailmark を呼び出す)
• ランタイム動作分析 (trailmark は静的解析であり動的ではない)

却下すべき正当化

正当化	誤りの理由	必要なアクション
「ソースファイルを手動で読むだけでいい」	手動読み取りでは呼び出しパス、爆発半径、テイントデータが見落とされる	trailmark をインストールして API を使用する
「クイッククエリには事前分析は不要」	爆発半径、テイント、特権データは preanalysis() の後にのみ利用可能	他のスキルに引き渡す前に常に engine.preanalysis() を実行する
「グラフが大きすぎるので、サンプリングする」	サンプリングではクロスモジュール攻撃パスが見落とされる	完全なグラフを構築してサブグラフクエリで焦点を絞る
「不確実なエッジは重要でない」	動的ディスパッチは型混乱バグが隠れている場所	セキュリティの主張で uncertain エッジを考慮する
「単一言語分析で十分」	ポリグロットリポジトリは FFI 境界にバグが集中している	コンポーネントごとに正しい --language フラグを使用する
「複雑性ホットスポットだけが確認する価値がある」	テイント化されたパス上の低複雑性関数は高価値ターゲット	複雑性をテイントデータと爆発半径データと組み合わせる

---

インストール

必須: uv run trailmark が失敗した場合 (コマンドが見つからない、インポートエラー、ModuleNotFoundError)、他に何もする前に trailmark をインストールします:

uv pip install trailmark

しないこと — trailmark の実行の代わりに「手動検証」「手動分析」またはソースファイルの手動読み取りにフォールバックしてはいけません。このツールはインストールされ、プログラム的に使用される必要があります。インストールに失敗した場合は、黙ってソースコード読み取りに切り替えるのではなく、ユーザーにエラーを報告してください。

クイックスタート

# ツリー内のすべてのサポート言語を自動検出してマージ
uv run trailmark analyze --language auto --summary {targetDir}

# 明示的な言語 (単一言語またはカンマ区切りリスト)
uv run trailmark analyze --language rust {targetDir}
uv run trailmark analyze --language python,rust {targetDir}

# 複雑性ホットスポット
uv run trailmark analyze --language auto --complexity 10 {targetDir}

プログラマティック API

from trailmark.parse import detect_languages, supported_languages
from trailmark.query.api import QueryEngine

# インストール済み Trailmark ビルドがサポートしているものを確認
supported_languages()
detect_languages("{targetDir}")

# 不明またはポリグロットツリーでは auto を優先；必要に応じて明示的なリストを使用
engine = QueryEngine.from_directory("{targetDir}", language="auto")
engine = QueryEngine.from_directory("{targetDir}", language="python,rust")

engine.callers_of("function_name")
engine.callees_of("function_name")
engine.paths_between("entry_func", "db_query")
engine.complexity_hotspots(threshold=10)
engine.attack_surface()
engine.summary()
engine.to_json()

# 事前分析を実行 (爆発半径、エントリーポイント、特権
# 境界、テイント伝播)
result = engine.preanalysis()

# 事前分析で作成されたサブグラフをクエリ
engine.subgraph_names()
engine.subgraph("tainted")
engine.subgraph("high_blast_radius")
engine.subgraph("privilege_boundary")
engine.subgraph("entrypoint_reachable")

# LLM 推論アノテーションを追加
from trailmark.models import AnnotationKind

engine.annotate("function_name", AnnotationKind.ASSUMPTION,
                "input is URL-encoded", source="llm")

# アノテーション (事前分析結果を含む) をクエリ
engine.annotations_of("function_name")
engine.annotations_of("function_name",
                       kind=AnnotationKind.BLAST_RADIUS)
engine.annotations_of("function_name",
                       kind=AnnotationKind.TAINT_PROPAGATION)

事前分析パス

genotoxic または diagramming-code スキルに引き渡す前に常に engine.preanalysis() を実行してください。 事前分析は 4 つのパスでグラフを充実させます:

1. 爆発半径推定 — 関数ごとの下流および上流ノード数をカウント、高複雑性の重要な子孫を識別
2. エントリーポイント列挙 — 信頼レベル別エントリーポイントをマッピング、到達可能なノードセットを計算
3. 特権境界検出 — 信頼レベルが変わる呼び出しエッジを検出 (信頼できない -> 信頼できる)
4. テイント伝播 — 信頼できないエントリーポイントから到達可能なすべてのノードをマーク

結果はグラフ上のアノテーションおよび名前付きサブグラフとして保存されます。

詳細なドキュメントについては、references/preanalysis-passes.md を参照してください。

言語選択

ダウンストリームワークフローで言語テーブルをハードコーディングしないでください。インストール済み Trailmark ビルドがサポートしているものを確認してください:

from trailmark.parse import detect_languages, supported_languages

supported_languages()
detect_languages("{targetDir}")

CLI パターン:

# 自動検出とマージ
uv run trailmark analyze --language auto {targetDir}

# 既知のポリグロットターゲット向けの明示的なリスト
uv run trailmark analyze --language python,rust {targetDir}

グラフモデル

ノードの種類: function、method、class、module、struct、 interface、trait、enum、namespace、contract、library、 template

エッジの種類: calls、inherits、implements、contains、imports

エッジの信頼度: certain (直接呼び出し、self.method())、inferred (非 self オブジェクトの属性アクセス)、uncertain (動的ディスパッチ)

コードユニットごと

• 型付きパラメータ、戻り値型、例外型
• 循環的複雑度とブランチメタデータ
• ドックストリング
• アノテーション: assumption、precondition、postcondition、invariant、 blast_radius、privilege_boundary、taint_propagation、finding、 audit_note (最後の 2 つは augment_sarif / augment_weaudit で設定)

エッジごと

• ソース/ターゲットノード ID、エッジの種類、信頼度レベル

プロジェクトレベル

• 依存関係 (インポートされたパッケージ)
• 信頼レベルと資産値を持つエントリーポイント
• 名前付きサブグラフ (事前分析で作成)

主要概念

宣言されたコントラクト対実効入力ドメイン: Trailmark は関数が受け入れると宣言するものと、呼び出しパス経由で実際に到達できるものを分離します。不一致は脆弱性が隠れている場所です:

• 拡大: 検証されていないデータが検証を想定している関数に到達
• 偶然によって安全: 検証がないが、現在は安全な呼び出し元のみが存在

エッジの信頼度: 動的ディスパッチは uncertain エッジを生成します。セキュリティの主張を行う際に信頼度を考慮してください。

サブグラフ: 事前分析で生成されたノード ID の名前付きコレクション。engine.subgraph("name") でクエリします。engine.preanalysis() の後で利用可能です。

クエリパターン

一般的なセキュリティ分析パターンについては references/query-patterns.md を参照してください。

事前分析パスのドキュメントについては references/preanalysis-passes.md を参照してください。