Voltar às atualizações
New releaseJul 24, 2026

trailmark v0.5.0

Construir e consultar uma representação de banco de dados em grafo do código-fonte

Compartilhar

Trailmark

CI Mutation Testing

O Trailmark analisa código-fonte em um grafo de funções, tipos, chamadas e outros relacionamentos, e então permite fazer perguntas estruturais sobre ele:

  • Quais entrypoints conseguem alcançar esta função, e por quais caminhos de chamada?
  • O que mudou na superfície de ataque entre dois commits?
  • Quais funções escrevem nesta variável de storage do Solidity?
  • Onde a resolução de chamadas parou, de modo que os resultados de alcançabilidade ficam incompletos?

Ele analisa as linguagens suportadas por meio do tree-sitter, armazena o grafo em rustworkx e o expõe por meio de uma ferramenta de linha de comando e de uma API Python. O Trailmark foi criado para revisão de segurança: cada aresta registra se veio diretamente da sintaxe ou de uma heurística, e as chamadas que não pôde resolver permanecem no grafo.

A visão de longo prazo é combinar este grafo com mutation testing e fuzzing guiado por cobertura para identificar lacunas entre premissas e cobertura de testes que sejam alcançáveis a partir da entrada do usuário.

Recursos

  • Grafos de código. Funções, métodos, classes, structs, traits, contratos e módulos, conectados por chamadas, herança, contenção e uso de tipos. --language auto mescla todas as linguagens suportadas em uma árvore em um único grafo.
  • Superfície de ataque. Detecção de entrypoints ciente de frameworks (Flask, FastAPI, Spring, ASP.NET Core, actix-web, NestJS, registros HTTP do Elysia, visibilidade em Solidity e mais), cada um marcado com um nível de confiança e valor de ativo. Substitua ou estenda a detecção com .trailmark/entrypoints.toml.
  • Evidência de entrypoints. Inspecione referências chamáveis e declarativas, corpos de arquivos executáveis e candidatos não resolvidos com proveniência de código-fonte. Referências permanecem separadas da execução. Selecione raízes de código-fonte adicionais com exclusões explícitas.
  • Alcançabilidade. Chamadores e chamados diretos, fatias transitivas e caminhos de chamada limitados de entrypoints até um alvo.
  • Diffs estruturais. Compare dois diretórios ou refs do git e relate declarações adicionadas ou removidas, mudanças de assinatura e tipo, mudanças de confiança em arestas de chamada e entrypoints.
  • Diagramas. Grafos de chamada Mermaid, hierarquias de classes, dependências de módulos, visões de contenção, mapas de complexidade e fluxos de entrypoint até alvo.
  • Achados no grafo. Importe resultados SARIF e weAudit, anexe suas próprias anotações e execute passagens de pré-análise (raio de impacto, fronteiras de privilégio, taint grosseiro) que armazenam seus resultados como anotações e subgrafos nomeados.
  • Lacunas visíveis. Chamadas que não podem ser resolvidas tornam-se nós proxy em vez de desaparecerem, e trailmark analyze --resolution as contabiliza.
  • Evidência de exceções. Inspecione throws, rethrows, handlers e sintaxe de limpeza localizados no código-fonte com exception_events(); operandos lançados desconhecidos permanecem visíveis. Consulte o modelo de grafo para cobertura de frontend e os limites dessa evidência sintática.
  • Links que o Trailmark não consegue ver. Declare arestas de RPC, FFI e subprocessos em .trailmark/links.toml, ou importe um grafo de chamadas produzido por uma ferramenta de análise de binários.
  • Evidência de binários compilados. Inspecione explicitamente imagens ELF, Mach-O e PE vinculadas, conecte funções e linhas do código-fonte a intervalos compilados, recupere chamadas de binários e transferências de cauda inferidas, e consulte desmontagem limitada em 15 casos de arquitetura/modo. Inclui mapeamentos de código sem símbolos, fatias universais, companheiros de depuração locais verificados, aliases dobrados e entradas de importação nomeadas. Consulte evidência de binários para o extra opcional trailmark[binary] e os requisitos de ferramentas do host.
  • Acesso ao armazenamento em Solidity. Arestas reads e writes entre funções e as variáveis de estado do contrato que elas acessam.

Instalação

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

Requer Python ≥ 3.12. Os testes de CI cobrem Python 3.12 até 3.15. Com Nix, nix run github:trailofbits/trailmark executa a CLI diretamente.

Este README e os guias acompanham a branch main. O changelog lista o que cada versão publicada inclui, e os guias da CLI e da API Python indicam a versão que adicionou cada recurso mais recente.

A maioria das gramáticas é baixada e armazenada em cache no primeiro uso. As gramáticas incluídas são compiladas no primeiro uso, o que requer um compilador C. Consulte Instalação para máquinas offline, proxies que inspecionam TLS e compilação a partir de um checkout.

Integradores de skills: consulte compatibilidade v0.7 para verificações de schema, identidade, estado e acessibilidade.

Início 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

O diretório de análise rejeita raízes ausentes e zero arquivos de origem correspondentes. O resumo inclui os idiomas selecionados e as contagens de arquivos inspecionados; use --allow-empty para uma entrada vazia intencional. O JSON do grafo inclui a versão do Trailmark que exportou e uma versão do esquema de exportação (v0.7+); compare snapshots criados com a mesma versão do Trailmark e os mesmos idiomas.

As mesmas perguntas a partir do 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

Nomes podem ser simples (verify_signature), qualificados (Auth.verify) ou IDs de nó completos (auth:Auth.verify). Os resultados de consulta são dicts e listas simples que serializam diretamente para JSON.

Como funciona

Categorias