
trailmark v0.5.0
Crea e interroga una rappresentazione a database grafico del codice sorgente.
Trailmark
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 autounisce 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 --resolutionle 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
readsewritestra 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.