Trailmark

Analizza il codice sorgente in grafici interrogabili di funzioni, classi, chiamate e annotazioni semantiche per l'analisi della sicurezza.

Trailmark utilizza tree-sitter per l'analisi AST indipendente dal linguaggio e rustworkx per l'esplorazione di grafici ad alte prestazioni. La visione a lungo termine è combinare questo grafico con il mutation testing e il fuzzing guidato dalla copertura per identificare lacune tra le supposizioni e la copertura dei test che sono raggiungibili dall'input utente.

Come Funziona

Trailmark opera in tre fasi: analisi, indicizzazione e interrogazione.```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. Analisi

Un parser specifico per linguaggio esamina la directory, analizza ogni file in un AST tree-sitter ed estrae:

- **Nodi** — funzioni, metodi, classi, struct, interfacce, trait, enumerazioni, moduli, namespace
- **Archi** — chiamate, ereditarietà, implementazione, contenimento, importazioni
- **Metadati** — annotazioni di tipo, complessità ciclomatica, rami, docstring, tipi di eccezioni

### Linguaggi supportati

| Linguaggio | Estensioni | Costrutti chiave |
| --- | --- | --- |
| Python | `.py` | funzioni, classi, metodi |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | funzioni, classi, funzioni freccia |
| TypeScript | `.ts`, `.tsx` | funzioni, classi, interfacce, enumerazioni |
| PHP | `.php` | funzioni, classi, interfacce, trait |
| Ruby | `.rb` | metodi, classi, moduli |
| C | `.c`, `.h` | funzioni, struct, enumerazioni |
| C++ | `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | funzioni, classi, struct, namespace |
| C# | `.cs` | metodi, classi, interfacce, struct, enumerazioni, namespace |
| Java | `.java` | metodi, classi, interfacce, enumerazioni |
| Go | `.go` | funzioni, metodi, struct, interfacce |
| Rust | `.rs` | funzioni, struct, trait, enumerazioni, blocchi impl |
| Solidity | `.sol` | contratti, interfacce, librerie, funzioni, modificatori, struct, enumerazioni |
| Cairo | `.cairo` | funzioni, trait, struct, enumerazioni, blocchi impl, contratti StarkNet |
| Circom | `.circom` | template, funzioni, segnali, componenti |
| Haskell | `.hs` | funzioni, tipi di dato, type class, istanze |
| Erlang | `.erl` | funzioni, record, comportamenti, moduli |
| Miden Assembly | `.masm` | procedure, punti di ingresso, costanti, invocazioni |
| Swift | `.swift` | funzioni, classi, struct, enumerazioni, protocolli, estensioni |
| Objective-C | `.m`, `.mm`, `.h` | funzioni C, classi, metodi (nomi basati su selettori) |
| Kotlin | `.kt`, `.kts` | funzioni, classi, interfacce, data class, oggetti, metodi |
| Dart | `.dart` | funzioni, classi, classi astratte, metodi, costruttori |
| Move | `.move` | moduli, funzioni, import, chiamate dirette |
| Tact | `.tact` | contratti, struct, ricevitori, funzioni |
| Func | `.fc`, `.func` | funzioni, include, chiamate dirette |
| Sway | `.sw` | interfacce ABI, struct, metodi impl, funzioni |
| Rego | `.rego` | pacchetti, import, regole di policy, chiamate a regole |
| Proto | `.proto` | servizi, RPC, messaggi, campi, enumerazioni |
| Thrift | `.thrift` | servizi, funzioni, struct, campi, enumerazioni |
| GraphQL | `.graphql`, `.gql` | tipi oggetto, operazioni radice, campi, enumerazioni |
| SQL | `.sql` | schemi, tabelle, viste, funzioni, procedure |```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

Gli ID dei nodi seguono lo schema module:function, module:Class o module:Class.method per una ricerca univoca. L'analisi delle directory risolve le chiamate semplici tra file quando esiste una definizione univoca; le chiamate ambigue tra file vengono lasciate al loro obiettivo originale di miglior sforzo e contrassegnate come uncertain. La confidenza degli archi è etichettata come certain (chiamate dirette, self.method()), inferred (accesso ad attributi su oggetti non self) o uncertain (dispatch dinamico o risoluzione ambigua).

2. Indice

Il GraphStore carica il CodeGraph in un PyDiGraph di rustworkx e costruisce mappature bidirezionali ID/indice per una rapida traversata.

3. Interrogazione

Il QueryEngine fornisce un'API di alto livello sul grafo indicizzato: