
trailmark v0.5.0
Construir e consultar uma representação de banco de dados em grafo do código-fonte
Trailmark
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 automescla 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 --resolutionas 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
readsewritesentre 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.