graph evolution

AI Community

Skill notes

When to Use

Comparing two git refs to understand what structurally changed Auditing a range of commits for security-relevant evolution Detecting new attack paths created by code changes Finding functions whose blast radius or complexity grew silently Identifying taint propagation changes across refactors

When NOT to Use

Line-level code review (use differential-review for text-diff analysis) Single-snapshot analysis (use the trailmark skill directly) Diagram generation from a single snapshot (use the diagramming-code skill) Mutation testing triage (use the genotoxic skill)

Rationalizations to Reject

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

Prerequisites

trailmark must be installed. If uv run trailmark fails, run: 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.

Phase 1: Create Snapshots

Use git worktrees to get clean copies of each ref without disturbing the working tree. If comparing two directories instead of git refs, skip this phase and use the directory paths directly in Phase 2.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@trailofbits · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
macOS · Linux · Windows
Runtime requirements
Node.js · Python
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1: Create Snapshots

Use git worktrees to get clean copies of each ref without disturbing the working tree. If comparing two directories instead of git refs, skip this phase and use the directory paths directly in Phase 2.

02
Phase 2: Build Graphs and Run Pre-Analysis

Build Trailmark graphs for both snapshots and run pre-analysis on each. Pre-analysis computes blast radius, taint propagation, privilege boundaries, and entrypoint enumeration. Verify both graphs built successfully by checking the summary output. If either fails, rerun with an explicit language or comma-separated list

03
Phase 3: Compute Structural Diff

Run both: Trailmark's native structural diff for nodes, edges, and entrypoints The plugin's `graph_diff.py` helper for subgraph membership changes Use the same `work_dir` from Phase 2, and pass the same `--language` value Phase 2 built with. `trailmark diff` defaults that flag to `python`, so on any other

04
Phase 4: Interpret Diff and Generate Report

Read both diff JSON files and generate a security-focused markdown report. See references/report-format.md for the full template. Interpretation priorities (highest to lowest):

05
Phase 5: Clean Up

Remove git worktrees after the report is written:

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.