Retour aux mises à jour
New releaseJul 24, 2026

trailmark v0.5.0

Construire et interroger une représentation en base de données graphe du code source.

Partager

Trailmark

CI Mutation Testing

Trailmark analyse le code source pour en produire un graphe de fonctions, de types, d'appels et d'autres relations, puis vous permet de l'interroger sur sa structure :

  • Quels points d'entrée peuvent atteindre cette fonction, et par quels chemins d'appel ?
  • Qu'est-ce qui a changé dans la surface d'attaque entre deux commits ?
  • Quelles fonctions écrivent cette variable de stockage Solidity ?
  • Où la résolution des appels s'est-elle arrêtée, rendant les résultats d'accessibilité incomplets ?

Il analyse les langages pris en charge via tree-sitter, stocke le graphe dans rustworkx et l'expose au moyen d'un outil en ligne de commande et d'une API Python. Trailmark a été conçu pour la revue de sécurité : chaque arête enregistre si elle provient directement de la syntaxe ou d'une heuristique, et les appels qu'il n'a pas pu résoudre restent dans le graphe.

La vision à long terme est de combiner ce graphe avec le mutation testing et le fuzzing guidé par la couverture pour identifier les écarts entre les hypothèses et la couverture de test qui sont accessibles depuis les entrées utilisateur.

Fonctionnalités

  • Graphes de code. Fonctions, méthodes, classes, structs, traits, contrats et modules, reliés par des appels, l'héritage, la contenance et l'utilisation de types. --language auto fusionne chaque langage pris en charge dans une arborescence en un seul graphe.
  • Surface d'attaque. Détection des points d'entrée adaptée aux frameworks (Flask, FastAPI, Spring, ASP.NET Core, actix-web, NestJS, enregistrements HTTP Elysia, visibilité Solidity, et plus encore), chacun étiqueté avec un niveau de confiance et une valeur d'actif. Remplacez ou étendez la détection avec .trailmark/entrypoints.toml.
  • Preuves des points d'entrée. Inspectez les références appelables et déclaratives, les corps de fichiers exécutables et les candidats non résolus avec leur provenance source. Les références restent séparées de l'exécution. Sélectionnez des racines de source supplémentaires avec des exclusions explicites.
  • Accessibilité. Appelants et appelés directs, tranches transitives et chemins d'appel bornés depuis les points d'entrée vers une cible.
  • Diffs structurels. Comparez deux répertoires ou références git et signalez les déclarations ajoutées ou supprimées, les changements de signature et de type, les changements de confiance des arêtes d'appel, et les points d'entrée.
  • Diagrammes. Graphes d'appels Mermaid, hiérarchies de classes, dépendances de modules, vues de contenance, cartes de complexité et flux des points d'entrée vers la cible.
  • Constats sur le graphe. Importez les résultats SARIF et weAudit, attachez vos propres annotations et exécutez des passes de préanalyse (rayon d'impact, frontières de privilèges, teinte grossière) qui stockent leurs résultats sous forme d'annotations et de sous-graphes nommés.
  • Lacunes visibles. Les appels qui ne peuvent pas être résolus deviennent des nœuds proxy au lieu de disparaître, et trailmark analyze --resolution les compte.
  • Preuves d'exceptions. Inspectez les throws, rethrows, gestionnaires et syntaxes de nettoyage localisés dans la source avec exception_events() ; les opérandes levés inconnus restent visibles. Consultez le modèle de graphe pour la couverture des frontends et les limites de ces preuves syntaxiques.
  • Liens que Trailmark ne peut pas voir. Déclarez les arêtes RPC, FFI et de sous-processus dans .trailmark/links.toml, ou importez un graphe d'appels produit par un outil d'analyse binaire.
  • Preuves de binaires compilés. Inspectez explicitement les images ELF, Mach-O et PE liées, connectez les fonctions et lignes source aux plages compilées, récupérez les appels binaires et les transferts de queue inférés, et interrogez un désassemblage borné sur 15 cas d'architecture/mode. Inclut les mappages de code strippé, les tranches universelles, les compagnons de débogage locaux vérifiés, les alias repliés et les entrées d'import nommées. Consultez preuves binaires pour l'extra optionnel trailmark[binary] et les exigences d'outils hôtes.
  • Accès au stockage Solidity. Arêtes reads et writes entre les fonctions et les variables d'état du contrat qu'elles touchent.

Installation

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

Nécessite Python ≥ 3.12. La CI teste Python de 3.12 à 3.15. Avec Nix, nix run github:trailofbits/trailmark exécute directement la CLI.

Ce README et les guides suivent la branche main. Le changelog liste ce que contient chaque version publiée, et les guides de la CLI et de l'API Python indiquent la version qui a introduit chaque fonctionnalité plus récente.

La plupart des grammaires sont téléchargées et mises en cache lors de la première utilisation. Les grammaires intégrées sont compilées lors de la première utilisation, ce qui nécessite un compilateur C. Voir Installation pour les machines hors ligne, les proxys inspectant le TLS et la compilation depuis un checkout.

Intégrateurs de skills : voir compatibilité v0.7 pour les vérifications de schéma, d'identité, d'état et d'accessibilité.

Démarrage rapide

# 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'analyse du répertoire rejette les racines manquantes et les fichiers sources sans correspondance. Le résumé inclut les langages sélectionnés et les nombres de fichiers inspectés ; utilisez --allow-empty pour une entrée vide intentionnelle. Le JSON du graphe inclut la version de Trailmark ayant effectué l'export et une version de schéma d'export (v0.7+) ; comparez des instantanés construits avec la même version de Trailmark et les mêmes langages.

Les mêmes questions depuis 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

Catégories