Volver a actualizaciones
Nuevo releaseJul 24, 2026

trailmark v0.5.0

Construye y consulta una representación de base de datos de grafos del código fuente.

Compartir

Trailmark

CI Mutation Testing

Trailmark analiza el código fuente y lo convierte en un grafo de funciones, tipos, llamadas y otras relaciones, y luego te permite plantear preguntas estructurales sobre él:

  • ¿Qué puntos de entrada pueden alcanzar esta función y a través de qué rutas de llamada?
  • ¿Qué cambió en la superficie de ataque entre dos commits?
  • ¿Qué funciones escriben esta variable de almacenamiento de Solidity?
  • ¿Dónde se detuvo la resolución de llamadas, de modo que los resultados de alcanzabilidad quedan incompletos?

Analiza los lenguajes compatibles mediante tree-sitter, almacena el grafo en rustworkx y lo expone a través de una herramienta de línea de comandos y una API de Python. Trailmark se creó para la revisión de seguridad: cada arista registra si proviene directamente de la sintaxis o de una heurística, y las llamadas que no pudo resolver permanecen en el grafo.

La visión a largo plazo es combinar este grafo con pruebas de mutación y fuzzing guiado por cobertura para identificar brechas entre las suposiciones y la cobertura de pruebas que sean alcanzables desde la entrada del usuario.

Características

  • Grafos de código. Funciones, métodos, clases, structs, traits, contratos y módulos, conectados por llamadas, herencia, contención y uso de tipos. --language auto fusiona todos los lenguajes compatibles de un árbol en un único grafo.
  • Superficie de ataque. Detección de puntos de entrada consciente del framework (Flask, FastAPI, Spring, ASP.NET Core, actix-web, NestJS, registros HTTP de Elysia, visibilidad de Solidity y más), cada uno etiquetado con un nivel de confianza y un valor de activo. Sobrescribe o amplía la detección con .trailmark/entrypoints.toml.
  • Evidencia de puntos de entrada. Inspecciona referencias invocables y declarativas, cuerpos de archivos ejecutables y candidatos sin resolver con procedencia del código fuente. Las referencias se mantienen separadas de la ejecución. Selecciona raíces de código fuente adicionales con exclusiones explícitas.
  • Alcanzabilidad. Llamadores y llamados directos, slices transitivos y rutas de llamada acotadas desde los puntos de entrada hasta un objetivo.
  • Diffs estructurales. Compara dos directorios o refs de git y reporta declaraciones añadidas o eliminadas, cambios de firma y de tipos, cambios de confianza en las aristas de llamada y puntos de entrada.
  • Diagramas. Grafos de llamadas Mermaid, jerarquías de clases, dependencias entre módulos, vistas de contención, mapas de complejidad y flujos de punto de entrada a objetivo.
  • Hallazgos sobre el grafo. Importa resultados de SARIF y weAudit, adjunta tus propias anotaciones y ejecuta pasadas de preanálisis (radio de impacto, límites de privilegios, taint aproximado) que almacenan sus resultados como anotaciones y subgrafos con nombre.
  • Brechas visibles. Las llamadas que no se pueden resolver se convierten en nodos proxy en lugar de desaparecer, y trailmark analyze --resolution las cuenta.
  • Evidencia de excepciones. Inspecciona throws, rethrows, manejadores y sintaxis de limpieza ubicados en el código fuente con exception_events(); los operandos lanzados desconocidos permanecen visibles. Consulta el modelo de grafo para la cobertura del frontend y los límites de esta evidencia sintáctica.
  • Enlaces que Trailmark no puede ver. Declara aristas de RPC, FFI y subprocesos en .trailmark/links.toml, o importa un grafo de llamadas producido por una herramienta de análisis de binarios.
  • Evidencia de binarios compilados. Inspecciona explícitamente imágenes ELF, Mach-O y PE enlazadas, conecta funciones y líneas del código fuente con rangos compilados, recupera llamadas de binarios y transferencias de cola inferidas, y consulta desensamblado acotado en 15 casos de arquitectura/modo. Incluye mapeos de código sin símbolos, slices universales, compañeros de depuración locales verificados, alias plegados y entradas de importación con nombre. Consulta evidencia de binarios para el extra opcional trailmark[binary] y los requisitos de herramientas del host.
  • Acceso al almacenamiento en Solidity. Aristas reads y writes entre funciones y las variables de estado del contrato a las que acceden.

Instalación

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

Requiere Python ≥ 3.12. La CI prueba Python desde 3.12 hasta 3.15. Con Nix, nix run github:trailofbits/trailmark ejecuta la CLI directamente.

Este README y las guías siguen la rama main. El changelog enumera lo que incluye cada versión publicada, y las guías de la CLI y de la API de Python indican la versión que añadió cada función más reciente.

La mayoría de las gramáticas se descargan y se almacenan en caché en el primer uso. Las gramáticas incluidas se compilan en el primer uso, lo que requiere un compilador de C. Consulta Installation para máquinas sin conexión, proxies que inspeccionan TLS y compilación desde un checkout.

Integradores de skills: consulta v0.7 compatibility para las comprobaciones de esquema, identidad, estado y alcanzabilidad.

Inicio rápido

# 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

El análisis de directorios rechaza raíces faltantes y cero archivos fuente coincidentes. El resumen incluye los lenguajes seleccionados y los recuentos de archivos inspeccionados; use --allow-empty para una entrada vacía intencional. El JSON del grafo incluye la versión de Trailmark que exporta y una versión del esquema de exportación (v0.7+); compare instantáneas creadas con la misma versión de Trailmark y los mismos lenguajes.

Las mismas preguntas desde 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

Categorías