Trailmark 構造解析

Trailmark グラフを構築し、engine.preanalysis() を実行して、4 つのすべての 事前解析パスを計算します。

使用すべき場合

• Vivisect Phase 1 が完全な構造データ（ホットスポット、汚染、爆発半径、権限境界）を必要とする場合
• 特定のターゲットスコープに対する詳細な事前解析パス
• 監査優先度付けのための複雑性と汚染データの生成

使用すべきでない場合

• 概要のみが必要な場合（代わりに trailmark-summary を使用してください）
• アドホックなコードグラフクエリ（メインの trailmark スキルを直接使用してください）
• ターゲットが単一の小さなファイルで、構造解析に価値がない場合

却下すべき根拠

根拠	誤りの理由	必要なアクション
「概要解析で十分」	概要は汚染、爆発半径、権限境界データをスキップする	詳細なデータが必要な場合は完全な構造解析を実行してください
「1 つのパスで十分」	パスは相互参照される — 爆発半径のない汚染分析は重要なノードを見落とす	4 つすべてのパスを実行してください
「ツールがインストールされていないので、手動で解析します」	手動解析はツーリングが検出するものを見落とす	「trailmark がインストールされていない」とレポートして戻してください
「パス出力が空というのはパスが失敗したことを意味する」	いくつかのパスは一部のコードベースでデータを生成しない（例：権限境界がない）	出力内容に関わらず完全な出力を返してください

使用方法

ターゲットディレクトリは args パラメータを通じて渡されます。

実行

Step 1: trailmark が利用可能であることを確認します。

trailmark analyze --help 2>/dev/null || \
  uv run trailmark analyze --help 2>/dev/null

どちらのコマンドも動作しない場合は、「trailmark がインストールされていない」とレポートして 戻してください。pip install、uv pip install、 git clone、またはその他のインストールコマンドを実行しないでください。ユーザーが 自分自身で trailmark をインストールする必要があります。

Step 2: Trailmark の parse API で言語を検出します。

python3 - "{args}" <<'PY'
import json
import sys

from trailmark.parse import detect_languages

print(json.dumps(detect_languages(sys.argv[1])))
PY

インポートが失敗した場合は、uv run python - "{args}" で同じスニペットを再実行してください。 結果が [] の場合は、「Trailmark がターゲット下でサポートされている言語を見つけられませんでした」とレポートして戻してください。

Step 3: QueryEngine 経由で完全な構造解析を実行します。

このスニペットを python3 で実行してください。インポートが失敗した場合は、 uv run python - "{args}" で同じスニペットを再実行してください。

python3 - "{args}" <<'PY'
import json
import sys

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

target = sys.argv[1]
languages = detect_languages(target)
engine = QueryEngine.from_directory(target, language="auto")
preanalysis = engine.preanalysis()

def summarize_subgraph(name: str, limit: int = 25) -> dict[str, object]:
    nodes = engine.subgraph(name)
    return {
        "count": len(nodes),
        "sample_ids": [node["id"] for node in nodes[:limit]],
    }

payload = {
    "languages": languages,
    "summary": engine.summary(),
    "preanalysis": preanalysis,
    "attack_surface": engine.attack_surface()[:25],
    "hotspots": engine.complexity_hotspots(10)[:25],
    "subgraphs": {
        name: summarize_subgraph(name)
        for name in engine.subgraph_names()
    },
}

print(json.dumps(payload, indent=2))
PY

Step 4: 出力を検証します。

出力には以下が含まれるべきです:

• languages
• summary
• preanalysis
• hotspots（空の可能性あり）
• subgraphs（カウントとサンプル ID を含む）

一部のコードベースでは一部のサブグラフがゼロノードを持つ場合があります（これは 正常です）。内容に関わらず完全な JSON ペイロードを返してください。