npx claudepluginhub trailofbits/skills --plugin trailmarkThis skill uses the workspace's default tool permissions.
Builds Trailmark code graphs at two source snapshots and computes a
Analyzes git diffs or pull requests against a knowledge graph to identify changed components, affected dependencies via edges, touched architectural layers, and risks based on complexity and blast radius.
Analyzes blast radius of code changes with risk scoring using code knowledge graph or git diff/grep fallback. Shows affected nodes, untested functions, and review priorities.
Builds persistent knowledge graph of codebase using Tree-sitter and SQLite, enabling Claude to query blast radius of changes and reduce tokens up to 49x on code reviews and tasks.
Share bugs, ideas, or general feedback.
Builds Trailmark code graphs at two source snapshots and computes a structural diff. Surfaces security-relevant changes that text-level diffs miss: new attack paths, complexity shifts, blast radius growth, taint propagation changes, and privilege boundary modifications.
differential-review for text-diff analysis)trailmark skill directly)diagramming-code skill)genotoxic skill)| Rationalization | Why It's Wrong | Required Action |
|---|---|---|
| "We just need the structural diff, skip pre-analysis" | Without pre-analysis, you miss taint changes, blast radius growth, and privilege boundary shifts | Run engine.preanalysis() on both snapshots |
| "Text diff covers what changed" | Text diffs miss new attack paths, transitive complexity shifts, and subgraph membership changes | Use structural diff to complement text diff |
| "Only added nodes matter" | Removed security functions and shifted privilege boundaries are equally dangerous | Review removals and modifications, not just additions |
| "Low-severity structural changes can be ignored" | INFO-level changes (dead code removal) can mask removed security checks | Classify every change, review removals for replaced functionality |
| "One snapshot's graph is enough for comparison" | Single-snapshot analysis can't detect evolution — you need both before and after | Always build and export both graphs |
| "Tool isn't installed, I'll compare manually" | Manual comparison misses what graph analysis catches | Install trailmark first |
trailmark must be installed. If uv run trailmark fails, run:
uv pip install trailmark
DO NOT fall back to "manual comparison" or reading source files as a substitute for running trailmark. The tool must be installed and used programmatically. If installation fails, report the error.
# Compare two git refs (e.g., tags, branches, commits)
# 1. Build graphs at each snapshot
# 2. Run pre-analysis on both
# 3. Compute structural diff
# 4. Generate report
# Step-by-step: see Workflow below
├─ Need to understand what each metric means?
│ └─ Read: references/evolution-metrics.md
│
├─ Need the report output format?
│ └─ Read: references/report-format.md
│
├─ Already have two graph JSON exports?
│ └─ Jump to Phase 3 (run graph_diff.py directly)
│
└─ Starting from two git refs?
└─ Start at Phase 1
Graph Evolution Progress:
- [ ] Phase 1: Create snapshots (git worktrees)
- [ ] Phase 2: Build graphs + pre-analysis on both snapshots
- [ ] Phase 3: Compute structural diff
- [ ] Phase 4: Interpret diff and generate report
- [ ] Phase 5: Clean up worktrees
Use git worktrees to get clean copies of each ref without disturbing the working tree.
# Create temp directories for worktrees
BEFORE_DIR=$(mktemp -d)
AFTER_DIR=$(mktemp -d)
# Create worktrees (run from repo root)
git worktree add "$BEFORE_DIR" {before_ref}
git worktree add "$AFTER_DIR" {after_ref}
If comparing two directories instead of git refs, skip this phase and use the directory paths directly in Phase 2.
Build Trailmark graphs for both snapshots and run pre-analysis on each. Pre-analysis computes blast radius, taint propagation, privilege boundaries, and entrypoint enumeration.
import json
from trailmark.query.api import QueryEngine
def build_and_export(target_dir, language, output_path):
"""Build graph, run pre-analysis, export 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}", "{lang}", before_json
)
after_summary = build_and_export(
"{after_dir}", "{lang}", after_json
)
Verify both graphs built successfully by checking the summary output. If either fails, check that the language parameter matches the codebase and that trailmark supports all file types present.
Run the diff script on the two exported JSON files (using the same
work_dir from Phase 2):
uv run {baseDir}/scripts/graph_diff.py \
--before "{before_json}" \
--after "{after_json}" > "{work_dir}/evolution_diff.json"
The output JSON contains:
| Key | Contents |
|---|---|
summary_delta | Changes in node/edge/entrypoint counts |
nodes.added | New functions, classes, methods |
nodes.removed | Deleted functions, classes, methods |
nodes.modified | Functions with changed CC, params, return type, span |
edges.added | New call/inheritance/import relationships |
edges.removed | Deleted relationships |
subgraphs | Per-subgraph membership changes (tainted, high_blast_radius, etc.) |
Read the diff JSON and generate a security-focused markdown report. See references/report-format.md for the full template.
Interpretation priorities (highest to lowest):
tainted subgraph,
especially if they also appear in added edges targeting sensitive
functionsuntrusted_externalhigh_blast_radiusCross-reference structural changes with git diff {before_ref}..{after_ref}
to add source-level context to findings.
Severity classification:
| Severity | Structural Signal |
|---|---|
| CRITICAL | New tainted path to sensitive function, removed auth boundary |
| HIGH | New entrypoint + high blast radius, large CC increase on tainted node |
| MEDIUM | New trust-boundary-crossing edges, moderate CC increase |
| LOW | Added nodes without entrypoint reachability |
| INFO | Dead code removal, complexity reductions |
For detailed metric definitions, see references/evolution-metrics.md.
Remove git worktrees after the report is written:
git worktree remove "{before_dir}"
git worktree remove "{after_dir}"
uv run {baseDir}/scripts/graph_diff.py [OPTIONS]
| Argument | Default | Description |
|---|---|---|
--before | required | Path to the "before" graph JSON |
--after | required | Path to the "after" graph JSON |
--indent | 2 | JSON output indentation |
Input format: Trailmark JSON exports from engine.to_json().
Output: JSON structural diff to stdout.
Before delivering the report:
GRAPH_EVOLUTION_*.mdtrailmark skill: Phase 2 uses the trailmark API for graph building and pre-analysis. All trailmark query patterns work on either snapshot's engine.
differential-review skill: Use graph-evolution for structural analysis, differential-review for line-level code review. The two are complementary — graph-evolution finds attack paths that text diffs miss, while differential-review provides git blame context and micro-adversarial analysis.
genotoxic skill: If graph-evolution reveals new high-CC tainted nodes, feed them to genotoxic for mutation testing triage.
diagramming-code skill:
Generate before/after diagrams to visualize structural changes.
Use call-graph or data-flow diagrams focused on changed nodes.