
trailmark v0.5.0
ソースコードのグラフデータベース表現を構築し、クエリを実行する
Trailmark
Trailmarkはソースコードを関数、型、呼び出し、その他の関係性のグラフに解析し、そのグラフに対して構造的な問いを投げかけられるようにします:
- どのエントリポイントがこの関数に到達でき、どの呼び出しパスを通るのか?
- 2つのコミット間で攻撃対象領域はどう変化したか?
- どの関数がこのSolidityのストレージ変数に書き込むのか?
- 呼び出し解決はどこで停止したのか、その結果到達可能性の結果が不完全になっているのはなぜか?
対応言語を tree-sitter経由で解析し、 グラフをrustworkxに格納し、 コマンドラインツールとPython APIを通じて公開します。Trailmarkはセキュリティレビューのために 構築されました:すべてのエッジは、構文から直接得られたものかヒューリスティックによるものかを記録し、 解決できなかった呼び出しはグラフに残ります。
長期的なビジョンは、このグラフをミューテーションテストや カバレッジガイド付きファジングと組み合わせ、ユーザー入力から到達可能な 前提とテストカバレッジの間のギャップを特定することです。
機能
- コードグラフ。 関数、メソッド、クラス、構造体、トレイト、コントラクト、モジュールを、呼び出し、継承、包含、型使用で接続します。
--language autoはツリー内のサポート対象言語をすべて1つのグラフに統合します。 - 攻撃対象領域。 フレームワークを認識したエントリーポイント検出(Flask、FastAPI、Spring、ASP.NET Core、actix-web、NestJS、Elysia の HTTP 登録、Solidity の可視性など)を行い、それぞれに信頼レベルと資産価値をタグ付けします。検出は
.trailmark/entrypoints.tomlで上書きまたは拡張できます。 - エントリーポイントの証拠。 呼び出し可能な参照と宣言的な参照、実行可能なファイル本体、未解決の候補をソースの来歴とともに検査します。参照は実行とは分離されたままです。明示的な除外を指定して追加のソースルートを選択できます。
- 到達可能性。 直接の呼び出し元と呼び出し先、推移的なスライス、エントリーポイントからターゲットまでの境界付き呼び出しパス。
- 構造的差分。 2つのディレクトリまたは git ref を比較し、追加・削除された宣言、シグネチャと型の変更、呼び出しエッジの信頼度の変化、エントリーポイントを報告します。
- ダイアグラム。 Mermaid の呼び出しグラフ、クラス階層、モジュール依存関係、包含ビュー、複雑度マップ、エントリーポイントからターゲットへのフロー。
- グラフ上の検出事項。 SARIF と weAudit の結果をインポートし、独自の注釈を付加し、事前解析パス(ブラスト半径、特権境界、粗いテイント)を実行して、その結果を注釈と名前付きサブグラフとして保存します。
- 可視化されたギャップ。 解決できない呼び出しは消えることなくプロキシノードになり、
trailmark analyze --resolutionがそれらをカウントします。 - 例外の証拠。
exception_events()でソース上の位置が特定された throw、rethrow、ハンドラー、クリーンアップ構文を検査します。不明な throw オペランドも可視のまま残ります。フロントエンドのカバレッジとこの構文証拠の限界についてはグラフモデルを参照してください。 - Trailmark が見えないリンク。 RPC、FFI、サブプロセスのエッジを
.trailmark/links.tomlで宣言するか、バイナリ解析ツールが生成した呼び出しグラフをインポートします。 - コンパイル済みバイナリの証拠。 リンクされた ELF、Mach-O、PE イメージを明示的に検査し、ソース関数と行をコンパイル済みの範囲に接続し、バイナリの呼び出しと推論されたテール転送を復元し、15 のアーキテクチャ/モードのケースにわたって境界付きの逆アセンブリをクエリします。ストリップされたコードのマッピング、ユニバーサルスライス、検証済みのローカルデバッグコンパニオン、折り畳まれたエイリアス、名前付きインポートエントリを含みます。オプションの
trailmark[binary]エクストラとホストツールの要件についてはバイナリ証拠を参照してください。 - Solidity のストレージアクセス。 関数と、それらが触れるコントラクトの状態変数との間の
readsおよびwritesエッジ。
インストール
uv tool install trailmark # the CLI
uv add trailmark # the library, in a uv-managed project
Python ≥ 3.12 が必要です。CI では Python 3.12 から 3.15 までをテストしています。
Nix を使用する場合、nix run github:trailofbits/trailmark で CLI を直接実行できます。
この README と各ガイドは main ブランチを追跡しています。
変更履歴
には各公開リリースに含まれる内容が記載されており、CLI ガイドと Python API ガイドには
各新機能を追加したバージョンが記載されています。
ほとんどの文法は初回使用時にダウンロードされキャッシュされます。バンドルされた文法は 初回使用時にコンパイルされ、C コンパイラが必要です。オフラインマシン、TLS 検査を行うプロキシ、 チェックアウトからのビルドについては インストール を参照してください。
スキル統合を行う開発者向け: スキーマ、ID、状態、到達可能性のチェックについては v0.7 互換性 を参照してください。
クイックスタート
# Node and edge counts for a Python project (Python is the default language)
trailmark analyze --summary path/to/project
# The same summary as JSON, including source-file counts per language (v0.7+)
trailmark analyze --summary --json --language auto path/to/project
# Full JSON graph of every supported language in the tree
trailmark analyze --language auto path/to/project > graph.json
# Detected entrypoints with trust level and asset value
trailmark entrypoints --language auto path/to/project
# How the attack surface changed between two git refs
trailmark diff --repo . main HEAD
# Mermaid call graph around one function
trailmark diagram -t path/to/project -T call-graph -f handle_request
# How many call sites could not be resolved, grouped by callee name
trailmark analyze --language rust --resolution path/to/project
ディレクトリ解析は、存在しないルートや一致するソースファイルがゼロの場合は拒否します。サマリーには選択された言語と検査されたファイル数が含まれます。意図的に空の入力を使用する場合は --allow-empty を使用してください。
グラフ JSON には、エクスポートした Trailmark のバージョンとエクスポートスキーマのバージョン(v0.7 以降)が含まれます。同じ Trailmark バージョンと言語で構築されたスナップショットを比較してください。
Python での同じ質問:
from trailmark.query.api import QueryEngine
engine = QueryEngine.from_directory("path/to/project", language="auto")
engine.attack_surface() # entrypoints and their trust levels
engine.callers_of("verify_signature") # direct callers
engine.ancestors_of("verify_signature") # everything that can reach it
engine.entrypoint_paths_to("verify_signature")
engine.complexity_hotspots(10) # cyclomatic complexity >= 10
名前はベア(verify_signature)、修飾付き(Auth.verify)、または完全なノードID(auth:Auth.verify)で指定できます。クエリ結果はプレーンなdictとlistであり、JSONに直接シリアライズされます。
仕組み
flowchart LR
A["Source files"] --> B["tree-sitter parsers"]
B --> C["CodeGraph"]
C --> D["GraphStore (rustworkx)"]
D --> E["QueryEngine"]
E --> F["CLI / Python API"]
classDef src fill:#007bff26,stroke:#007bff,color:#007bff
classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef query fill:#ffc10726,stroke:#e6a817,color:#e6a817
class A src
class B parse
class C,D data
class E,F query
- パース。 各言語のパーサーがディレクトリを走査し、ノード
(関数、型、モジュール)、エッジ(呼び出し、継承、包含など)、
およびメタデータ(パラメータ、戻り値の型、分岐、循環的複雑度、
ドキュメント文字列、送出される例外)を抽出します。その後、リンク処理のパスが
ファイルをまたいだ呼び出しを解決し、型をその宣言にリンクし、
.trailmark/links.tomlを適用します。 - インデックス。
GraphStoreはグラフを rustworkx の有向グラフに読み込み、 高速な走査を可能にします。QueryEngine.from_directory()はエントリーポイントの検出も実行します。 - クエリ。
QueryEngineは名前をノード ID に解決し、走査を実行し、 JSON シリアライズ可能な結果を返します。
例
次の app.py が与えられた場合:
class Auth:
def verify(self, token):
return self._check_sig(token)
def _check_sig(self, token): ...
def handle_request(req):
auth = Auth()
if auth.verify(req.token):
return process(req)
return deny()
def process(req): ...
def deny(): ...
Trailmarkはこのグラフを生成します(モジュール包含エッジは省略):
graph TD
HR["app:handle_request"] -->|calls| A["app:Auth"]
HR -->|calls| PV["proxy.unresolved:auth.verify"]
HR -->|calls| P["app:process"]
HR -->|calls| D["app:deny"]
AV["app:Auth.verify"] -->|calls| CS["app:Auth._check_sig"]
A -->|contains| AV
A -->|contains| CS
classDef fn fill:#007bff26,stroke:#007bff,color:#007bff
classDef cls fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef proxy fill:#dc354526,stroke:#dc3545,color:#dc3545
class HR,P,D fn
class A,AV,CS cls
class PV proxy
self._check_sig(...) は、self が外側のクラスを指すため解決されます。
auth.verify(...) は解決されません。Trailmark はローカル変数 auth が
Auth を保持していると推論しないためです。この呼び出しは破棄されず、
プロキシノードとして保持されます。その結果、engine.ancestors_of("Auth._check_sig")
は app:Auth.verify のみを返し、engine.unresolved_calls("handle_request")
はパスが失われた正確な呼び出し箇所を示します。すべてのノード種別、エッジ種別、
ID 規則については
Graph model
を、プロキシの扱いについては
Call resolution
を参照してください。