Trailmark

Analise código fonte em grafos consultáveis de funções, classes, chamadas e anotações semânticas para análise de segurança.

O Trailmark usa tree-sitter para análise de AST independente de linguagem e rustworkx para travessia de grafos de alto desempenho. A visão de longo prazo é combinar este grafo com testes de mutação e fuzzing guiado por cobertura para identificar lacunas entre suposições e cobertura de teste que são alcançáveis a partir da entrada do usuário.

Como Funciona

O Trailmark opera em três fases: analisar, indexar e consultar.```mermaid flowchart TD A["Source Files"] --> B["tree-sitter Parser"] B --> C["CodeGraph (nodes + edges)"] C --> D["rustworkx GraphStore"] D --> E["QueryEngine"] E --> F["JSON / Summary / Hotspots"]

classDef src fill:#007bff26,stroke:#007bff,color:#007bff
classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef query fill:#ffc10726,stroke:#e6a817,color:#e6a817

class A src
class B parse
class C,D data
class E,F query

### 1. Análise

Um parser específico da linguagem percorre o diretório, analisa cada arquivo em uma AST tree-sitter e extrai:

- **Nós** — funções, métodos, classes, structs, interfaces, traits, enums, módulos, namespaces
- **Arestas** — chamadas, herança, implementação, contenção, imports
- **Metadados** — anotações de tipo, complexidade ciclomática, branches, docstrings, tipos de exceção

### Linguagens Suportadas

| Linguagem | Extensões | Principais construtos |
| --- | --- | --- |
| Python | `.py` | funções, classes, métodos |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | funções, classes, funções seta |
| TypeScript | `.ts`, `.tsx` | funções, classes, interfaces, enums |
| PHP | `.php` | funções, classes, interfaces, traits |
| Ruby | `.rb` | métodos, classes, módulos |
| C | `.c`, `.h` | funções, structs, enums |
| C++ | `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | funções, classes, structs, namespaces |
| C# | `.cs` | métodos, classes, interfaces, structs, enums, namespaces |
| Java | `.java` | métodos, classes, interfaces, enums |
| Go | `.go` | funções, métodos, structs, interfaces |
| Rust | `.rs` | funções, structs, traits, enums, blocos impl |
| Solidity | `.sol` | contratos, interfaces, bibliotecas, funções, modificadores, structs, enums |
| Cairo | `.cairo` | funções, traits, structs, enums, blocos impl, contratos StarkNet |
| Circom | `.circom` | templates, funções, sinais, componentes |
| Haskell | `.hs` | funções, tipos de dados, classes de tipo, instâncias |
| Erlang | `.erl` | funções, registros, comportamentos, módulos |
| Miden Assembly | `.masm` | procedimentos, pontos de entrada, constantes, invocações |
| Swift | `.swift` | funções, classes, structs, enums, protocolos, extensões |
| Objective-C | `.m`, `.mm`, `.h` | funções C, classes, métodos (nomenclatura baseada em seletores) |
| Kotlin | `.kt`, `.kts` | funções, classes, interfaces, classes de dados, objetos, métodos |
| Dart | `.dart` | funções, classes, classes abstratas, métodos, construtores |
| Move | `.move` | módulos, funções, imports, chamadas diretas |
| Tact | `.tact` | contratos, structs, receptores, funções |
| Func | `.fc`, `.func` | funções, includes, chamadas diretas |
| Sway | `.sw` | interfaces ABI, structs, métodos impl, funções |
| Rego | `.rego` | pacotes, imports, regras de política, chamadas de regras |
| Proto | `.proto` | serviços, RPCs, mensagens, campos, enums |
| Thrift | `.thrift` | serviços, funções, structs, campos, enums |
| GraphQL | `.graphql`, `.gql` | tipos de objeto, operações raiz, campos, enums |
| SQL | `.sql` | esquemas, tabelas, visões, funções, procedimentos |```mermaid
flowchart TD
    subgraph "Per-File Parsing"
        F["Source file"] --> TS["tree-sitter AST"]
        TS --> EX["Extract nodes"]
        TS --> EC["Extract call edges"]
        TS --> EB["Count branches"]
        TS --> ET["Resolve types"]
    end

    EX --> CG["CodeGraph"]
    EC --> CG
    EB --> CG
    ET --> CG

    classDef src fill:#007bff26,stroke:#007bff,color:#007bff
    classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
    classDef extract fill:#ffc10726,stroke:#e6a817,color:#e6a817
    classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1

    class F src
    class TS parse
    class EX,EC,EB,ET extract
    class CG data

Os IDs de nó seguem o esquema module:function, module:Class ou module:Class.method para consulta inequívoca. A análise de diretório resolve chamadas entre arquivos isoladas quando existe uma definição única; chamadas ambíguas entre arquivos são deixadas no seu destino de melhor esforço original e marcadas como uncertain. A confiança da aresta é marcada como certain (chamadas diretas, self.method()), inferred (acesso a atributos em objetos não-self) ou uncertain (despacho dinâmico ou resolução ambígua).

2. Índice

O GraphStore carrega o CodeGraph em um PyDiGraph do rustworkx e constrói mapeamentos bidirecionais de ID/índice para travessia rápida.

3. Consulta

O QueryEngine fornece uma API de alto nível sobre o grafo indexado:

Método	Descrição
callers_of(name)	Chamadores diretos do alvo nomeado
callees_of(name)	Calados diretos da fonte nomeada
ancestors_of(name)	Todas as funções que podem alcançar transitivamente o alvo (fatia ascendente)
reachable_from(name)	Todas as funções transitivamente alcançáveis a partir da fonte
paths_between(src, dst)	Todos os caminhos de chamada simples entre dois nós
connect_subgraphs(source, target)	Caminhos conectando dois subgrafos nomeados
entrypoint_paths_to(name)	Caminhos de qualquer ponto de entrada detectado até o alvo
attack_surface()	Pontos de entrada marcados com nível de confiança, valor do ativo e atributos do analisador quando presentes
complexity_hotspots(n)	Funções com complexidade ciclomática ≥ n
functions_that_raise(exc)	Funções cuja lista de exceções detectadas pelo analisador inclui exc
generic_parameters(name)	Parâmetros de tipo genérico declarados por um nó
type_references(name)	Referências de tipo de parâmetro, retorno, exceção e limites genéricos
annotate(name, kind, description, source)	Adicionar uma anotação semântica a um nó
annotations_of(name, kind=None)	Obter anotações para um nó, opcionalmente filtradas por tipo
nodes_with_annotation(kind)	Todos os nós marcados com o tipo de anotação dado
clear_annotations(name, kind=None)	Remover anotações de um nó
diff_against(other)	Diff estrutural deste grafo do mecanismo vs. outro
preanalysis()	Executar as passagens de pré-análise embutidas e armazenar anotações/subgrafos
augment_sarif(path)	Mesclar descobertas SARIF no grafo
augment_weaudit(path)	Mesclar descobertas weAudit no grafo
augment_binary(path)	Mesclar um arquivo JSON de grafo de análise binária externa
findings(kind=None)	Retornar nós que carregam anotações do tipo descoberta
subgraph(name)	Retornar os nós em um subgrafo nomeado
subgraph_edges(name)	Retornar arestas induzidas dentro de um subgrafo nomeado
subgraph_names()	Listar todos os subgrafos nomeados atualmente no grafo
summary()	Contagens de nós, contagens de arestas, dependências
to_json()	Exportação completa do grafo