Anthropic Claudeセキュリティ⭐ リポ 0品質スコア 50/100

graph-evolution

Name: graph-evolution
Author: trailofbits

Trailmarkのコードグラフを2つのソースコードスナップショット（gitコミット、タグ、またはディレクトリ）間で比較し、セキュリティに関わる構造的変化を検出します。テキストdiffでは見落とされがちな、新たな攻撃パス・複雑性の変化・影響範囲の拡大・汚染伝播の変化・権限境界の変更などを明らかにします。コミットやタグ間の構造的な進化の分析、攻撃対象領域の拡大検出、監査スナップショット間の変更レビューに活用できます。

description の原文を見る

> Compares Trailmark code graphs at two source code snapshots (git commits, tags, or directories) to surface security-relevant structural changes. Detects new attack paths, complexity shifts, blast radius growth, taint propagation changes, and privilege boundary modifications that text diffs miss. Use when comparing code between commits or tags, analyzing structural evolution, detecting attack surface growth, reviewing what changed between audit snapshots, or finding security-relevant changes that text diffs miss.

SKILL.md 本文

Graph Evolution

2つのソースコードスナップショットで Trailmark コードグラフを構築し、構造的な差分を計算します。テキストレベルの差分では検出できないセキュリティ関連の変化を明らかにします：新しい攻撃パス、複雑性の変化、ブラストラディウスの増加、汚染伝播の変化、特権境界の修正。

いつ使用するか

2つの git ref を比較して構造的な変化を理解する
コミット範囲を監査してセキュリティ関連の進化を検出する
コード変更で作成された新しい攻撃パスを検出する
ブラストラディウスまたは複雑性が無視されて増加した関数を見つける
リファクタリング全体での汚染伝播の変化を識別する
リリース前の構造的比較 (タグ間またはブランチ間)

いつ使用しないか

行レベルのコード検査 (テキスト差分分析には differential-review を使用)
単一スナップショットの分析 (trailmark skill を直接使用)
単一スナップショットからのダイアグラム生成 (diagramming-code skill を使用)
ミューテーションテストのトリアージ (genotoxic skill を使用)

却下すべき正当化

正当化	なぜ間違っているか	必要なアクション
「構造的な差分だけが必要、事前分析はスキップ」	事前分析なしでは汚染の変化、ブラストラディウスの増加、特権境界の変化を見落とします	両方のスナップショットで `engine.preanalysis()` を実行
「テキスト差分で変化をカバーできている」	テキスト差分は新しい攻撃パス、推移的な複雑性の変化、サブグラフのメンバーシップ変化を見落とします	構造的な差分を用いてテキスト差分を補完
「追加されたノードだけが重要」	削除されたセキュリティ関数と変化した特権境界は同様に危険です	追加だけでなく、削除と変更も確認
「低重大度の構造的変化は無視できる」	INFO レベルの変化 (デッドコード削除) は削除されたセキュリティチェックを隠す可能性があります	すべての変化を分類し、削除された機能の置き換えを確認
「1つのスナップショットのグラフで十分」	単一スナップショット分析では進化を検出できません。変更前後の両方が必要です	常に両方のグラフを構築・エクスポート
「ツールがインストールされていない、手動で比較します」	手動比較はグラフ分析が検出するものを見落とします	まず trailmark をインストール

前提条件

trailmark がインストールされていることが必須です。uv run trailmark が失敗する場合は以下を実行してください：

uv pip install trailmark

手動比較やソースファイルの読み込みを trailmark の実行の代替として使用してはいけません。ツールはインストールされ、プログラム的に使用される必要があります。インストールが失敗した場合は、エラーを報告してください。

クイックスタート

# 2つの git ref を比較 (例: タグ、ブランチ、コミット)
# 1. 各スナップショットでグラフを構築
# 2. 両方で事前分析を実行
# 3. 構造的な差分を計算
# 4. レポートを生成

# ステップバイステップ: 下記のワークフローを参照

デシジョンツリー

├─ 各メトリックの意味を理解する必要がある?
│  └─ 参照: references/evolution-metrics.md
│
├─ レポート出力フォーマットが必要?
│  └─ 参照: references/report-format.md
│
├─ 2つのグラフ JSON エクスポートがすでにある?
│  └─ Phase 3 にジャンプ (ネイティブ差分 + graph_diff.py を実行)
│
└─ 2つの git ref から開始?
   └─ Phase 1 から開始

ワークフロー

Graph Evolution Progress:
- [ ] Phase 1: スナップショット作成 (git worktrees)
- [ ] Phase 2: グラフ構築 + 両方のスナップショットで事前分析
- [ ] Phase 3: 構造的な差分を計算
- [ ] Phase 4: 差分を解釈しレポートを生成
- [ ] Phase 5: worktrees をクリーンアップ

Phase 1: スナップショット作成

git worktree を使用して、作業ツリーを邪魔することなく各 ref のクリーンなコピーを取得します。

# worktree 用の一時ディレクトリを作成
BEFORE_DIR=$(mktemp -d)
AFTER_DIR=$(mktemp -d)

# worktree を作成 (リポジトリルートから実行)
git worktree add "$BEFORE_DIR" {before_ref}
git worktree add "$AFTER_DIR" {after_ref}

git ref ではなく2つのディレクトリを比較する場合は、このフェーズをスキップして、Phase 2 でディレクトリパスを直接使用してください。

Phase 2: グラフ構築と事前分析の実行

両方のスナップショットで Trailmark グラフを構築し、各グラフで事前分析を実行します。事前分析はブラストラディウス、汚染伝播、特権境界、およびエントリポイント列挙を計算します。

from trailmark.query.api import QueryEngine

def build_and_export(target_dir, output_path, language="auto"):
    """グラフを構築、事前分析を実行、JSON をエクスポート。"""
    engine = QueryEngine.from_directory(target_dir, language=language)
    engine.preanalysis()
    json_str = engine.to_json()
    with open(output_path, "w") as f:
        f.write(json_str)
    return engine.summary()

import tempfile, os
work_dir = tempfile.mkdtemp(prefix="trailmark_evolution_")
before_json = os.path.join(work_dir, "before_graph.json")
after_json = os.path.join(work_dir, "after_graph.json")

before_summary = build_and_export(
    "{before_dir}", before_json
)
after_summary = build_and_export(
    "{after_dir}", after_json
)

サマリー出力をチェックして、両方のグラフが正常に構築されたことを確認してください。どちらかが失敗した場合は、auto の代わりに明示的な言語またはコンマ区切りのリストで再実行してください。

Phase 3: 構造的な差分を計算

以下の両方を実行してください：

ノード、エッジ、エントリポイント用の Trailmark ネイティブ構造的差分
サブグラフメンバーシップ変化用のプラグイン graph_diff.py ヘルパー

Phase 2 の同じ work_dir を使用：

trailmark diff --json "{before_dir}" "{after_dir}" > "{work_dir}/trailmark_diff.json" || \
  uv run trailmark diff --json "{before_dir}" "{after_dir}" > "{work_dir}/trailmark_diff.json"

uv run {baseDir}/scripts/graph_diff.py \
    --before "{before_json}" \
    --after "{after_json}" > "{work_dir}/subgraph_diff.json"

どちらかの差分コマンドが失敗するか、空の JSON ファイルを書き込む場合は、Phase 4 に進まずにエラーを報告してください。

ネイティブ Trailmark diff には以下が含まれます：

キー	内容
`summary_delta`	ノード/エッジ/エントリポイント数の変化
`nodes.added`	新しい関数、クラス、メソッド
`nodes.removed`	削除された関数、クラス、メソッド
`nodes.modified`	CC、パラメータ、行スパンが変化した関数
`edges.added`	新しいコール/継承/インポート関係
`edges.removed`	削除された関係
`entrypoints`	追加、削除、変更されたエントリポイント

サブグラフ差分には以下が含まれます：

キー	内容
`subgraphs`	サブグラフごとのメンバーシップ変化 (汚染、高ブラストラディウスなど)

Phase 4: 差分を解釈しレポートを生成

両方の差分 JSON ファイルを読み込み、セキュリティ重視のマークダウンレポートを生成します。完全なテンプレートについては references/report-format.md を参照してください。

解釈優先度 (高から低)：

新しい汚染パス — tainted サブグラフに入るノード、特に機密関数をターゲットとする追加エッジにも表示される場合
特権境界の変化 — ネイティブエントリポイント/エッジ差分とサブグラフ差分からの新しいまたは削除された信頼遷移
攻撃面の増加 — trailmark_diff.json からの新しいエントリポイント、特に untrusted_external
ブラストラディウスの増加 — high_blast_radius に入るノード
複雑性スパイク — 汚染されたノードまたはエントリポイント到達可能なノード上での CC 増加 > 3
構造的な追加 — 新しいノードとエッジ (レビュー必要)
構造的な削除 — 削除されたセキュリティ関数が置き換えられたことを確認

構造的変化を git diff {before_ref}..{after_ref} と相互参照して、検出結果にソースレベルのコンテキストを追加してください。

重大度分類：

重大度	構造的シグナル
CRITICAL	機密関数への新しい汚染パス、削除された認証境界
HIGH	新しいエントリポイント + 高ブラストラディウス、汚染ノード上の大規模な CC 増加
MEDIUM	新しい信頼境界横断エッジ、適度な CC 増加
LOW	エントリポイント到達性のない追加ノード
INFO	デッドコード削除、複雑性削減

詳細なメトリック定義については references/evolution-metrics.md を参照してください。

Phase 5: クリーンアップ

レポート作成後、git worktree を削除します：

git worktree remove "{before_dir}"
git worktree remove "{after_dir}"

差分リファレンス

trailmark diff --json BEFORE AFTER
uv run {baseDir}/scripts/graph_diff.py [OPTIONS]

以下には trailmark diff を使用してください：

ノード/エッジの変化
追加/削除/変更されたエントリポイント
人間が読める構造的差分レポート

以下には graph_diff.py を使用してください：

engine.preanalysis() から導出されたサブグラフメンバーシップの変化
tainted、high_blast_radius、privilege_boundary および関連するセット

引数	デフォルト	説明
`--before`	必須	「前」グラフ JSON へのパス
`--after`	必須	「後」グラフ JSON へのパス
`--indent`	`2`	JSON 出力インデント

graph_diff.py 入力フォーマット：engine.to_json() からの Trailmark JSON エクスポート。 graph_diff.py 出力：ノード、エッジ、サブグラフの JSON 構造的差分。

品質チェックリスト

レポートを提出する前に：

統合

trailmark skill： Phase 2 はグラフ構築と事前分析に trailmark API を使用します。すべての trailmark クエリパターンは、どちらかのスナップショットのエンジンで機能します。

differential-review skill： 構造分析には graph-evolution を、行レベルのコード検査には differential-review を使用してください。2つは補完的です。graph-evolution はテキスト差分が見落とす攻撃パスを見つけ、differential-review は git blame コンテキストと微視的敵対分析を提供します。

genotoxic skill： graph-evolution が新しい高 CC 汚染ノードを明らかにした場合は、genotoxic にフィードしてミューテーションテストのトリアージを行ってください。

diagramming-code skill： 変更前後のダイアグラムを生成して構造的変化を視覚化します。変更されたノードに焦点を当てた call-graph または data-flow ダイアグラムを使用してください。

サポート文書

references/evolution-metrics.md — 各構造的メトリックの意味とセキュリティにおける重要性
references/report-format.md — レポートテンプレート、重大度分類、および検出結果の例

ライセンス: CC-BY-SA-4.0(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

詳細情報

作者: trailofbits
リポジトリ: trailofbits/skills
ライセンス: CC-BY-SA-4.0
最終更新: 不明

GitHubで原本を見る →フィードバックを送る

Source: https://github.com/trailofbits/skills / ライセンス: CC-BY-SA-4.0