Skill graph-evolution
✓ OfficielscriptsCompare les graphes de code entre deux instantanés de la source pour détecter les changements structurels critiques pour la sécurité, tels que de nouveaux chemins d'attaque ou des modifications des limites de privilèges.
- Étoiles GitHub
- 8 136
- Fichiers
- 6
- Dernier commit
- 11 nov. 2026
- Licence
- CC-BY-SA-4.0
- Outils autorisés
- —
Que fait la skill graph-evolution ?
Compare les graphes de code entre deux instantanés de la source pour détecter les changements structurels critiques pour la sécurité, tels que de nouveaux chemins d'attaque ou des modifications des limites de privilèges.
Résumé généré à partir du SKILL.md de la skill.
À propos du skill graph-evolution
Les ingénieurs de sécurité et les développeurs qui doivent identifier des vulnérabilités structurelles lors des mises à jour de code utilisent ce SKILL pour comparer les graphes de code entre deux instantanés. En analysant les commits git, les tags ou les répertoires, il fait émerger des changements pertinents pour la sécurité que les diffs textuels classiques ignorent souvent, comme de nouveaux chemins d'attaque, des modifications des limites de privilèges et des changements dans la propagation de la contamination.
Un agent doit charger ce SKILL lors de comparaisons structurelles pré-release ou lors de l'audit d'une série de commits pour détecter une augmentation de la surface d'attaque. Le processus consiste à construire les graphes de code Trailmark pour les deux instantanés, à effectuer une pré-analyse pour calculer des métriques telles que le rayon d'impact et la complexité, puis à calculer un diff structurel. L'outil repose sur l'installation de trailmark et produit des diffs JSON détaillés ainsi que des rapports markdown axés sur la sécurité. Il identifie spécifiquement les changements d'appartenance aux sous-graphes, par exemple des nœuds rejoignant des ensembles contaminés ou à fort rayon d'impact, offrant ainsi une couche d'analyse plus profonde que les revues de code ligne par ligne.
Ce qu'un agent peut faire avec
- 1Détecter de nouveaux chemins d'attaqueIdentifier si les récents changements de code ont créé de nouveaux chemins permettant à un attaquant d'atteindre des fonctions sensibles.
- 2Suivre la croissance du rayon d'impactRepérer les fonctions dont l'impact potentiel sur le système a augmenté silencieusement en raison de changements structurels.
- 3Auditer les changements de propagation de la contaminationDéterminer si les caractéristiques des flux de données ont changé entre différentes versions de la base de code.
Rédigé à partir du SKILL.md du skill. Chaque cas d'utilisation est vérifié par rapport à une citation de celui-ci.
Comment installer la skill graph-evolution
Chaque commande copie le dossier de la skill dans le répertoire des skills du client. Redémarrez le client ou démarrez une nouvelle session pour la charger.Installer la skill graph-evolution dans Plugin
/plugin marketplace add trailofbits/skills /plugin install trailmark@trailofbits
Installer la skill graph-evolution dans Claude Code
~/.claude/skills/graph-evolution/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/graph-evolution ~/.claude/skills/graph-evolutionInstaller la skill graph-evolution dans Claude Code (project)
.claude/skills/graph-evolution/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/graph-evolution .claude/skills/graph-evolutionInstaller la skill graph-evolution dans Codex
~/.agents/skills/graph-evolution/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/graph-evolution ~/.agents/skills/graph-evolutionInstaller la skill graph-evolution dans Gemini CLI
~/.gemini/skills/graph-evolution/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/graph-evolution ~/.gemini/skills/graph-evolutionInstaller la skill graph-evolution dans Claude.ai
npx degit trailofbits/skills/plugins/trailmark/skills/graph-evolution graph-evolution && zip -r graph-evolution.zip graph-evolution # claude.ai → Customize → Skills → + → Create skill → Upload a skill → graph-evolution.zip
Vérifications automatisées
Exécuté le 15 nov. 2026Rapport complet →Pas encore vérifiée. Une skill doit obtenir 80, sans constat grave, avec assez de données pour être vérifiée. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessibletrailofbits/skills/plugins/trailmark/skills/graph-evolution is public and reachablegithub.com/trailofbits/skills/tree/HEAD/plugins/trailmark/sk ↗Réussi
- Licence open source (OSI)CC-BY-SA-4.0 is not OSI-approvedspdx.org/licenses/CC-BY-SA-4.0.html ↗Faille
- Commit ou version publiée au cours de l'année écouléeLast commit 2026-11-11github.com/trailofbits/skills/commits ↗Réussi
- Aucun téléchargement-exécution ni vol d'identifiants dans les scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadRéussi
- Aucune instruction cachée dans SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Réussi
- Les outils préautorisés sont limitésNo pre-approved tools; the agent asks before using onegithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Réussi
- SKILL.md respecte le format Agent SkillsValid name and description; says when to use it; 353 linesgithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Réussi
SKILL.md
Voir sur GitHubGraph Evolution
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.
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
- Pre-release structural comparison (tag-to-tag or branch-to-branch)
When NOT to Use
- Line-level code review (use
differential-reviewfor text-diff analysis) - Single-snapshot analysis (use the
trailmarkskill directly) - Diagram generation from a single snapshot (use the
diagramming-codeskill) - Mutation testing triage (use the
genotoxicskill)
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 |
| "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 |
| "The diff came back empty, so nothing changed structurally" | trailmark diff defaults --language to python and exits 0 with empty arrays on any other target, so an empty diff reads identically whether the code is unchanged or the language was wrong |
Pass --language explicitly and re-run before concluding no change |
Prerequisites
trailmark must be installed. If uv run trailmark fails, run:
uv tool install trailmark
# Python snippets: uv run --with trailmark python - (a tool env is not importable)
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.
Quick Start
# 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
Decision Tree
├─ 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 native diff + graph_diff.py)
│
└─ Starting from two git refs?
└─ Start at Phase 1
Workflow
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
Phase 1: Create Snapshots
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.
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.
from trailmark.query.api import QueryEngine
def build_and_export(target_dir, output_path, language="auto"):
"""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}", before_json
)
after_summary = build_and_export(
"{after_dir}", after_json
)
Verify both graphs built successfully by checking the summary output.
If either fails, rerun with an explicit language or comma-separated list
instead of auto.
Phase 3: Compute Structural Diff
Run both:
- Trailmark's native structural diff for nodes, edges, and entrypoints
- The plugin's
graph_diff.pyhelper 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
target the default exits 0 and writes empty arrays rather than reporting a
mismatch.
trailmark diff --json --language auto "{before_dir}" "{after_dir}" > "{work_dir}/trailmark_diff.json" || \
uv run trailmark diff --json --language auto "{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"
If Phase 2 needed an explicit language or a comma-separated list instead of
auto, use that same value here.
If either diff command fails or writes an empty JSON file, stop and report the error instead of continuing to Phase 4.
A trailmark_diff.json whose nodes, edges, and entrypoints arrays are all
empty means either nothing changed structurally or both snapshots parsed to
(near-)empty graphs. Decide which using Phase 2's graph summaries: if either
snapshot's node count is zero or implausibly small for the target, the parse
missed the code — name the language set explicitly (rust, solidity,
python,rust) and re-run. Healthy node counts on both snapshots plus an empty
diff is genuine structural stability.
The native Trailmark diff 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, line span |
edges.added |
New call/inheritance/import relationships |
edges.removed |
Deleted relationships |
entrypoints |
Added, removed, and modified entrypoints |
The subgraph diff contains:
| Key | Contents |
|---|---|
subgraphs |
Per-subgraph membership changes (tainted, high_blast_radius, etc.) |
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):
- New tainted paths — nodes entering the
taintedsubgraph, especially if they also appear in added edges targeting sensitive functions - Privilege boundary changes — new or removed trust transitions from the native entrypoint/edge diff plus the subgraph diff
- Attack surface growth — new entrypoints, especially
untrusted_external, fromtrailmark_diff.json - Blast radius increases — nodes entering
high_blast_radius - Complexity spikes — CC increases > 3 on tainted or entrypoint-reachable nodes
- Structural additions — new nodes and edges (review needed)
- Structural removals — verify removed security functions were replaced
Cross-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.
Phase 5: Clean Up
Remove git worktrees after the report is written:
git worktree remove "{before_dir}"
git worktree remove "{after_dir}"
Diff Reference
trailmark diff --json --language auto BEFORE AFTER
uv run {baseDir}/scripts/graph_diff.py [OPTIONS]
trailmark diff --language defaults to python. On a target in any other
language that default still exits 0, emitting well-formed JSON with empty
nodes, edges, and entrypoints arrays, so always pass the flag: auto
detects and merges every supported language found under the target, and a single
name (rust, solidity) or comma-separated list (python,rust) pins an
explicit set. auto fails loudly with No supported languages detected under <path> when a snapshot holds nothing it can parse, which is the outcome you
want. Confirm the language first; only then can an empty diff count as evidence
that nothing changed.
Use trailmark diff for:
- Node/edge changes
- Added/removed/modified entrypoints
- Human-readable structural diff reports
Use graph_diff.py for:
- Subgraph membership changes derived from
engine.preanalysis() tainted,high_blast_radius,privilege_boundary, and related sets
| Argument | Default | Description |
|---|---|---|
--before |
required | Path to the "before" graph JSON |
--after |
required | Path to the "after" graph JSON |
--indent |
2 |
JSON output indentation |
graph_diff.py input format: Trailmark JSON exports from engine.to_json().
graph_diff.py output: JSON structural diff for nodes, edges, and subgraphs.
Quality Checklist
Before delivering the report:
- Both graphs built successfully (check summaries)
- Pre-analysis ran on both snapshots
- Native Trailmark diff computed (
trailmark_diff.json); if it is empty, both snapshots' Phase 2 node counts were non-zero, so empty means stable - Subgraph diff computed and non-empty (
subgraph_diff.json) - All subgraph changes interpreted (tainted, blast radius, etc.)
- Critical findings include evidence (node IDs, edge diffs)
- Severity levels assigned to all findings
- Source-level context added via git diff cross-reference
- Worktrees cleaned up (or temp dirs removed)
- Report written to
GRAPH_EVOLUTION_*.md
Integration
trailmark 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.
trailmark-review-gate skill: Use trailmark-review-gate after graph-evolution when a branch, pull request, fix commit, or release diff needs a PASS/WARN/FAIL/UNKNOWN structural review packet. The gate applies deterministic review rules to graph-evolution output; it does not replace human review.
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.
Supporting Documentation
- references/evolution-metrics.md — What each structural metric means and why it matters for security
- references/report-format.md — Report template, severity classification, and example findings
Fichiers de cette skill
6Questions sur la skill graph-evolution
Comment installer la skill graph-evolution dans Claude Code ?
Exécutez npx degit trailofbits/skills/plugins/trailmark/skills/graph-evolution ~/.claude/skills/graph-evolution. Claude Code charge les skills depuis ~/.claude/skills (tous les projets) ou .claude/skills (un seul projet) et utilise une skill lorsque sa description correspond à la tâche.
Quels clients peuvent utiliser la skill graph-evolution ?
Tout client qui lit le format Agent Skills : Claude Code, Codex, Gemini CLI et claude.ai (envoi sous forme de ZIP). Les scripts de la skill ne s'exécutent que si le client autorise l'exécution de code.
Que peut détecter cet outil qu'un diff textuel standard ne peut pas identifier ?
Il met en évidence des changements structurels tels que de nouveaux chemins d'attaque, des variations de complexité, l'augmentation du rayon d'impact (blast radius), les changements de propagation de la contamination (taint propagation) et les modifications des limites de privilèges.
Pourquoi un diff peut-il être vide même si le code a été modifié ?
L'outil utilise Python par défaut ; si votre code est écrit dans un autre langage, il peut s'arrêter avec un diff vide. Vous devez explicitement passer l'argument --language.
Comment dois-je procéder pour comparer deux branches git différentes ?
Vous devez utiliser les git worktrees pour créer des copies propres de chaque référence dans des répertoires distincts avant de construire les graphes.