Torna agli aggiornamenti
New releaseJul 24, 2026

trailmark v0.5.0

Crea e interroga una rappresentazione a database grafico del codice sorgente.

Condividi

Trailmark

CI Mutation Testing

Trailmark analizza il codice sorgente trasformandolo in un grafo di funzioni, tipi, chiamate e altre relazioni, per poi permetterti di porre domande strutturali al riguardo:

  • Quali entrypoint possono raggiungere questa funzione, e lungo quali percorsi di chiamata?
  • Cosa è cambiato nella superficie d'attacco tra due commit?
  • Quali funzioni scrivono questa variabile di storage Solidity?
  • Dove si è interrotta la risoluzione delle chiamate, così che i risultati di raggiungibilità siano incompleti?

Analizza i linguaggi supportati tramite tree-sitter, memorizza il grafo in rustworkx e lo espone tramite uno strumento da riga di comando e un'API Python. Trailmark è stato creato per la revisione di sicurezza: ogni arco registra se proviene direttamente dalla sintassi o da una euristica, e le chiamate che non è riuscito a risolvere restano nel grafo.

La visione a lungo termine è quella di combinare questo grafo con il mutation testing e il fuzzing guidato dalla copertura per identificare le lacune tra le assunzioni e la copertura dei test che sono raggiungibili dall'input dell'utente.

Funzionalità

  • Grafo del codice. Funzioni, metodi, classi, struct, trait, contratti e moduli, collegati da chiamate, ereditarietà, contenimento e uso dei tipi. --language auto unisce ogni linguaggio supportato in un albero in un unico grafo.
  • Superficie d'attacco. Rilevamento degli entrypoint consapevole del framework (Flask, FastAPI, Spring, ASP.NET Core, actix-web, NestJS, registrazioni HTTP Elysia, visibilità Solidity e altro), ciascuno etichettato con un livello di fiducia e un valore di asset. Sovrascrivi o estendi il rilevamento con .trailmark/entrypoints.toml.
  • Evidenza degli entrypoint. Ispeziona riferimenti richiamabili e dichiarativi, corpi di file eseguibili e candidati non risolti con provenienza dal sorgente. I riferimenti restano separati dall'esecuzione. Seleziona radici sorgente aggiuntive con esclusioni esplicite.
  • Raggiungibilità. Chiamanti e chiamati diretti, slice transitive e percorsi di chiamata limitati dagli entrypoint a un target.
  • Diff strutturali. Confronta due directory o ref git e segnala dichiarazioni aggiunte o rimosse, modifiche a firme e tipi, cambiamenti di confidenza degli archi di chiamata ed entrypoint.
  • Diagrammi. Grafi di chiamata Mermaid, gerarchie di classi, dipendenze tra moduli, viste di contenimento, mappe di complessità e flussi da entrypoint a target.
  • Risultati sul grafo. Importa risultati SARIF e weAudit, allega le tue annotazioni ed esegui passate di preanalisi (blast radius, confini di privilegio, taint grossolano) che memorizzano i risultati come annotazioni e sottografi denominati.
  • Lacune visibili. Le chiamate che non possono essere risolte diventano nodi proxy invece di sparire, e trailmark analyze --resolution le conta.
  • Evidenza delle eccezioni. Ispeziona throw, rethrow, handler e sintassi di cleanup localizzati nel sorgente con exception_events(); gli operandi lanciati sconosciuti restano visibili. Consulta il modello del grafo per la copertura dei frontend e i limiti di questa evidenza sintattica.
  • Collegamenti che Trailmark non può vedere. Dichiara archi RPC, FFI e di sottoprocesso in .trailmark/links.toml, oppure importa un grafo di chiamate prodotto da uno strumento di analisi binaria.
  • Evidenza da binari compilati. Ispeziona esplicitamente immagini ELF, Mach-O e PE collegate, collega funzioni e righe del sorgente agli intervalli compilati, recupera chiamate binarie e trasferimenti di coda inferiti, e interroga disassembly limitati su 15 casi di architettura/modalità. Include mappature di codice stripped, slice universali, companion di debug locali verificati, alias ripiegati e voci di import denominate. Consulta evidenza binaria per l'extra opzionale trailmark[binary] e i requisiti degli strumenti host.
  • Accesso allo storage Solidity. Archi reads e writes tra funzioni e le variabili di stato del contratto che esse toccano.

Installazione

uv tool install trailmark        # the CLI
uv add trailmark                 # the library, in a uv-managed project

Richiede Python ≥ 3.12. La CI testa Python dalla 3.12 alla 3.15. Con Nix, nix run github:trailofbits/trailmark esegue direttamente la CLI.

Questo README e le guide seguono il branch main. Il changelog elenca cosa include ogni release pubblicata, e le guide alla CLI e all'API Python indicano la versione che ha introdotto ciascuna funzionalità più recente.

La maggior parte delle grammatiche viene scaricata e memorizzata nella cache al primo utilizzo. Le grammatiche incluse nel pacchetto vengono compilate al primo utilizzo, il che richiede un compilatore C. Vedi Installation per le macchine offline, i proxy che ispezionano il TLS e la compilazione da un checkout.

Integratori di Skills: vedi v0.7 compatibility per i controlli su schema, identità, stato e raggiungibilità.

Avvio rapido

# Node and edge counts for a Python project (Python is the default language)
trailmark analyze --summary path/to/project

# The same summary as JSON, including source-file counts per language (v0.7+)
trailmark analyze --summary --json --language auto path/to/project

# Full JSON graph of every supported language in the tree
trailmark analyze --language auto path/to/project > graph.json

# Detected entrypoints with trust level and asset value
trailmark entrypoints --language auto path/to/project

# How the attack surface changed between two git refs
trailmark diff --repo . main HEAD

# Mermaid call graph around one function
trailmark diagram -t path/to/project -T call-graph -f handle_request

# How many call sites could not be resolved, grouped by callee name
trailmark analyze --language rust --resolution path/to/project

L'analisi della directory rifiuta le radici mancanti e i file sorgente senza corrispondenze. Il riepilogo include le lingue selezionate e i conteggi dei file ispezionati; usa --allow-empty per un input vuoto intenzionale. Il JSON del grafo include la versione di Trailmark che ha esportato e una versione dello schema di esportazione (v0.7+); confronta snapshot creati con la stessa versione di Trailmark e le stesse lingue.

Le stesse domande da Python:

from trailmark.query.api import QueryEngine

engine = QueryEngine.from_directory("path/to/project", language="auto")

engine.attack_surface()                    # entrypoints and their trust levels
engine.callers_of("verify_signature")      # direct callers
engine.ancestors_of("verify_signature")    # everything that can reach it
engine.entrypoint_paths_to("verify_signature")
engine.complexity_hotspots(10)             # cyclomatic complexity >= 10

I nomi possono essere semplici (verify_signature), qualificati (Auth.verify) o ID di nodo completi (auth:Auth.verify). I risultati delle query sono semplici dict e liste che si serializzano direttamente in JSON.

Come funziona

Categorie