TraceTree

Demo di TraceTree

TraceTree (cascade-analyzer) è un organismo di sicurezza autonomo progettato per l'era agentica. Va oltre la semplice scansione, trasformandosi in un ecosistema di rilevamento robusto, irrobustito e scalabile. Come la sua mascotte, il ragno, TraceTree tesse una rete completa di protezione attorno al tuo flusso di lavoro di sviluppo utilizzando le sue otto "zampe" specializzate.

Sommario

• Struttura del repository
• Esportazione del report di comportamento
• Le 8 zampe del ragno TraceTree
• Come funziona
• Cosa rileva
  • Firme comportamentali
  • Pattern temporali
• Target supportati
• Avvio rapido (Vai all'installazione)
  • Prerequisiti
  • Installazione
  • Esegui un'analisi
• Riferimento CLI
• Analisi di sicurezza del server MCP
• Panoramica dell'architettura
• Limitazioni e punti ciechi

Esportazione del report di comportamento

TraceTree può essere utilizzato come gate di revisione prima che agenti o umani si fidino di un'installazione di un pacchetto. Vedi Esportazione del report di comportamento per un formato di report piccolo e compatibile con JSON/SARIF che riassume l'hash del target, la policy del sandbox, il comportamento osservato, gli hash degli artefatti, il verdetto e le impostazioni predefinite sulla privacy senza esporre i log grezzi delle syscall.

Struttura del repository```

TraceTree/ ├── api/ # API stubs ├── codebase-analysis-docs/ # Architecture documents and knowledge guides ├── data/ # Behavioral signatures, rules, and training datasets ├── docs/ # Documentation assets ├── examples/ # Demo scripts and usage examples ├── frontend/ # Next.js/React web dashboard ├── graph/ # NetworkX directed graph builder ├── hooks/ # Git/Shell hooks for background monitoring ├── logs/ # Execution trace logs and strace outputs ├── macapp/ # Native macOS menu bar app ├── mascot/ # Console ASCII spider mascot ├── mcp/ # MCP server security testing module ├── ml/ # Machine learning classification and anomaly detection ├── monitor/ # Core syscall parser, YARA matching, and timelines ├── orchestrator/ # TypeScript multi-agent coordination server ├── repocheckai/ # Repository analysis engine (TypeScript/Node) ├── samples/ # Malware and benign files for sandbox tests ├── sandbox/ # Docker container manager and strace sandbox ├── test_targets/ # Mock packages/servers for detection testing ├── tests/ # Unit, integration, and system tests ├── watcher/ # File system change listener daemon └── worker/ # Background task execution worker

## Le 8 zampe del TraceTree Spider

1.  **Zampa 1: Isolamento nella Sandbox (La Trappola)** — Esegue i target in container Docker isolati (o in una modalità `direct` ad alte prestazioni) dove le minacce sono fisicamente contenute.
2.  **Zampa 2: Parsing delle Syscall (Il Sistema Nervoso)** — Un motore ad alta precisione che monitora ogni "vibrazione" (chiamata di sistema) che un processo invia al sistema operativo.
3.  **Zampa 3: Grafici Comportamentali (La Rete)** — Mappa la "Cascata" di come processi, file e nodi di rete interagiscono utilizzando grafi diretti di NetworkX.
4.  **Zampa 4: Rilevamento di Anomalie ML (L'Intuito)** — Un modello Random Forest addestrato su misura (addestrato su un piccolo dataset rappresentativo di pacchetti puliti/maligni, più feed opzionali live da MalwareBazaar) che predice l'intento maligno con alta confidenza.
5.  **Zampa 5: Corrispondenza delle Firme YARA (La Memoria)** — Una libreria integrata di DNA di malware noti e pattern di exploit (Reverse Shell, Cryptominer, ecc.).
6.  **Zampa 6: Protocollo di Sicurezza MCP (Lo Scudo Agente)** — Protezione specializzata per i server Model Context Protocol, difendendo gli strumenti che gli agenti AI utilizzano.
7.  **Zampa 7: AI Guardiano della Sicurezza (La Rete Proattiva)** — Uno "Smart Scanner" pre-commit che utilizza LLM locali (Qwen-Coder) per individuare fughe e iniezioni prima che colpiscano la tua cronologia.
8.  **Zampa 8: Analisi Temporale e N-gram (La Scansione del DNA)** — Identifica le minacce tramite il *ritmo* e la *sequenza* delle loro azioni nel tempo.

## Come Funziona```
target ──► Docker sandbox (network dropped) ──► strace -t -f
                                               │
                                               ▼
                                          strace log
                                               │
                              ┌────────────────┼────────────────┐
                              ▼                ▼                ▼
                        strace parser      signature       temporal
                        (parser.py)     matcher (sigs)    analyzer
                              │                │                │
                              └───────┬────────┴────────────────┘
                                      ▼
                              NetworkX graph
                              (builder.py)
                                      │
                                      ▼
                          ML anomaly detection
                          (RandomForest / IsolationForest)
                                      │
                                      ▼
                                 verdict

1. Sandbox — Il target viene eseguito all'interno di un container Docker. La rete viene disattivata (ip link set eth0 down) prima che inizi l'installazione/esecuzione, quindi qualsiasi tentativo di connessione in uscita viene registrato ma bloccato.
2. strace — Ogni syscall viene tracciata con strace -t -f -e trace=all. Il flag -t aggiunge timestamp per l'analisi temporale, -f segue i processi figli.
3. Parser (monitor/parser.py) — Parser basato su regex che gestisce output strace multi-riga e sia i formati [pid] che pid nudo. Estrae creazione di processi, accesso ai file, connessioni di rete e operazioni di memoria. A ogni syscall viene assegnato un peso di gravità (0–9) in base alla sua rilevanza per la sicurezza.
4. Signature matching (monitor/signatures.py) — Abbina il flusso di eventi analizzato a 8 pattern di firme comportamentali definiti in data/signatures.json. Ogni corrispondenza produce evidenze che elencano gli eventi specifici che l'hanno attivata.
5. Temporal analysis (monitor/timeline.py) — Rileva 5 pattern comportamentali basati sul tempo dal flusso di eventi temporalmente marcati (ad es., lettura di credenziali seguita da connessione esterna entro 5 secondi).

Cosa Rileva

Firme Comportamentali (8 pattern)

Definite in data/signatures.json. Ognuna ha una gravità (1–10), syscall richieste, pattern di file, condizioni di rete e una sequenza ordinata da abbinare.

Pattern Temporali (5 pattern)

Rilevati dall'output strace con timestamp. Richiede il flag -t di strace (abilitato per impostazione predefinita).

Punteggio delle Syscall Ponderato per Gravità

Ognuno dei 24 tipi di syscall ha un peso di gravità base. Esempi:

• mprotect con PROT_EXEC: 9.0
• dup2 dopo una connect: 9.0
• execve di binario inaspettato: 7.0
• connect a metadata cloud (169.254.x.x): 8.0
• connect a CDN PyPI/npm: 0.0 (benigno)
• openat di /usr/lib/python/*: 0.0 (benigno)

Il punteggio totale di gravità alimenta il calcolo della confidenza ML.

Classificazione delle Destinazioni di Rete

Ogni syscall connect viene classificata in una delle quattro categorie:

Target Supportati

Avvio Rapido

Prerequisiti

• Python 3.9+
• Docker (deve essere in esecuzione)

Installazione```bash

git clone --depth 1 https://github.com/tejasprasad2008-afk/TraceTree.git cd TraceTree pip install -e .

### Esegui un'Analisi```bash
cascade-analyze --help

Risultato:``` ┌──────────────────────────────────────┐ │ TraceTree Security Analyzer │ │ Target: requests │ │ Analyzer Type: PIP │ └──────────────────────────────────────┘ ✔ Sandboxing requests (pip)... ✔ Parsing requests... ✔ Graphing requests... ✔ Detecting requests...

┌─ Cascade Graph: requests ────────────┐ │ pip install requests │ │ └─ pip (root) │ │ └─ net_151.101.1.69:443 (connect)│ │ └─ file_/usr/lib/python3.11/... │ └──────────────────────────────────────┘

┌─ Flagged Behaviors ──────────────────┐ │ No suspicious footprints flagged. │ └──────────────────────────────────────┘

    ┌──────────┐
    │  CLEAN   │
    └──────────
    Confidence Score: 72.3%

Per un pacchetto malevolo (ad es., un typosquatting conosciuto):```
 ┌─ Behavioral Signatures Matched ──────┐
 │ 🔴 credential_theft (severity 9/10) │
 │   Step 1: openat /etc/shadow         │
 │   Step 2: connect 45.33.32.156:4444  │
 └──────────────────────────────────────┘

 ┌─ Temporal Execution Patterns ────────┐
 │ 🔴 connect_then_shell (severity 10/10)│
 │   Window: 1500-4200 ms — External... │
 └──────────────────────────────────────┘

        ┌───────────┐
        │ MALICIOUS │
        └───────────┘
        Confidence Score: 99.9%
        Signatures: credential_theft | Temporal: connect_then_shell

Riferimento CLI

cascade-analyze <target>

Analizza un singolo pacchetto, binario o file bulk.```bash

PyPI package

cascade-analyze requests cascade-analyze urllib33 # known typosquat

npm package

cascade-analyze package.json

DMG / EXE

cascade-analyze suspicious_app.dmg cascade-analyze payload.exe

Bulk analysis

cascade-analyze requirements.txt cascade-analyze package.json

Force target type

cascade-analyze ./some_file --type pip cascade-analyze ./some_file --type npm cascade-analyze ./some_file --type dmg cascade-analyze ./some_file --type exe

**Sottocomando: `cascade-analyze mcp`** — Analisi di sicurezza del server MCP (vedi sezione MCP più avanti).

**Sottocomando: `cascade-analyze watch <repo>`** — Guardiano di sessione (vedi sezione Guardiano di sessione).

**Sottocomando: `cascade-analyze check <file>`** — Scansione rapida su richiesta.

### `cascade-watch <repo>`

Guardiano di sessione autonomo. Monitora una directory per manifesti di pacchetti ed esegue un'analisi sandbox in background.```bash
cascade-watch ./my-project
cascade-watch ./my-project --check setup.py    # on-demand scan
cascade-watch https://github.com/user/repo.git  # URL accepted but not cloned

Visualizza una mascotte ragno nel terminale e interroga lo stato in un loop. Premi Ctrl+C per fermare. È consentito un solo watcher per directory (file di blocco in /tmp/tracetree_sessions/).

cascade-check <file>

Analisi rapida e singola di un file specifico. Avvia una nuova esecuzione in sandbox e restituisce un verdetto.```bash cascade-check setup.py cascade-check ./payload.exe

### `cascade-install-hook`

Installa un hook di shell che esegue `cascade-watch` automaticamente dopo ogni `git clone`.```bash
cascade-install-hook

Questo aggiunge una riga source a ~/.bashrc o ~/.zshrc. Lo script hook si trova in ~/.local/share/tracetree/hooks/shell_hook.sh. Dopo l'installazione, ogni git clone avvierà un watcher in background e registrerà in /tmp/tracetree_<reponame>.log.

cascade-train

Pipeline di training interattiva. Richiede una chiave API MalwareBazaar (opzionale — può essere saltata per addestrare solo su dataset locali), quindi:

1. Inserisce campioni da MalwareBazaar (se la chiave è fornita)
2. Esegue ciascuno attraverso la pipeline sandbox
3. Addestra un RandomForestClassifier sulle feature estratte
4. Salva in ml/model.skops e invalida la cache```bash export MALWAREBAZAAR_AUTH_KEY="your-key" cascade-train

## Analisi di sicurezza del server MCP

Il sottocomando `cascade-analyze mcp` analizza i server Model Context Protocol alla ricerca di comportamenti dannosi. Esegue il server in un contenitore in sandbox, agisce come un client MCP simulato per scoprire e invocare ogni strumento, quindi classifica la traccia delle syscall risultante.```bash
# Analyze an npm MCP server
cascade-analyze mcp --npm @modelcontextprotocol/server-github

# Analyze a local MCP server project
cascade-analyze mcp --path ./my-mcp-server

# Allow network (for servers that legitimately need internet)
cascade-analyze mcp --npm @modelcontextprotocol/server-github --allow-network

# Force transport
cascade-analyze mcp --npm some-package --transport stdio
cascade-analyze mcp --npm some-package --transport http --port 3000

# JSON output
cascade-analyze mcp --npm some-package --output json

Cosa fa l'analisi MCP

1. Sandbox — Il server viene eseguito in Docker con rete bloccata per impostazione predefinita. Tracciato con strace -f.
2. Simulazione client — Handshake initialize JSON-RPC 2.0, scoperta tools/list, invocazione sicura di ogni strumento con argomenti sintetici.
3. Sonde avversarie — Ogni strumento viene reinvocato con payload di iniezione (; ls /etc, ../../../etc/passwd, <script>alert(1)</script>).
4. Estrazione delle caratteristiche — Caratteristiche specifiche di MCP: connessioni di rete per strumento, invocazioni di shell, letture di file sensibili, cambiamenti di comportamento sotto input avversario.
5. Classificazione delle minacce — Classificatore basato su regole con 6 categorie:

6. Confronto con baseline — Confronta i profili delle syscall con baseline hardcoded per 5 tipi di server: filesystem, github, postgres, fetch, shell.

Architettura

sandbox/ — Gestione del ciclo di vita dei container Docker. Costruisce cascade-sandbox:latest da un Dockerfile basato su python:3.11-slim con strace, wine64, p7zip-full, cabextract, Node.js e npm. Disabilita l'interfaccia di rete (ip link set eth0 down) prima dell'esecuzione del target. Supporta target pip, npm, DMG ed EXE. Restituisce un percorso del log di strace o una stringa vuota in caso di fallimento.

monitor/parser.py — Parser di log strace basato su regex. Gestisce voci di syscall multi-riga, sia formati [pid] che pid nudo, e output con timestamp (-t). Tiene traccia di 24 tipi di syscall in 5 categorie (processo, rete, file, memoria, IPC). Assegna pesi di gravità per evento, classifica le destinazioni di rete e segnala accessi a file sensibili. Restituisce dati strutturati degli eventi con timestamp e offset in millisecondi relativi.

monitor/signatures.py — Matcher di firme comportamentali. Carica 8 pattern da data/signatures.json. Supporta sia matching non ordinato (le syscall richieste + i pattern di file/rete devono essere presenti) sia matching di sequenza ordinata (le coppie syscall-condizione devono apparire in ordine). Restituisce le firme corrispondenti con evidenza che elenca gli eventi specifici che hanno attivato ogni corrispondenza.

monitor/timeline.py — Analizzatore di pattern temporali. Rileva 5 pattern comportamentali basati sul tempo dal flusso di eventi ordinato e con timestamp. Ogni pattern specifica una gravità, una finestra temporale e le condizioni di attivazione. Restituisce le corrispondenze ordinate per gravità decrescente. Attivo solo quando strace è stato eseguito con -t (che è l'impostazione predefinita).

graph/builder.py — Costruzione di grafi diretti con NetworkX. Crea nodi per processi, file e destinazioni di rete. Aggiunge archi per relazioni di clone, target di syscall e relazioni temporali (eventi consecutivi dello stesso PID entro 5 secondi). Nodi e archi sono etichettati con corrispondenze di firme e pesi di gravità. Produce JSON compatibile con Cytoscape e statistiche interne.

ml/detector.py — Rilevamento di anomalie. Estrae un vettore di 10 caratteristiche (conteggio nodi, conteggio archi, connessioni di rete, letture di file, conteggio execve, gravità totale, reti sospette, file sensibili, gravità massima, conteggio pattern temporali). Utilizza RandomForestClassifier se un modello addestrato è disponibile localmente o scaricabile da GCS; in caso contrario, ricade su IsolationForest addestrato su 10 baseline hardcoded di pacchetti puliti. I punteggi di gravità e i conteggi di pattern temporali aumentano la confidenza finale indipendentemente dalla previsione ML.

mcp/ — Modulo di analisi del server MCP. Sei file: sandbox.py (sandbox Docker per server MCP), client.py (client JSON-RPC 2.0 con scoperta di strumenti e sonde avversarie), features.py (estrazione di caratteristiche specifiche di MCP con rilevamento del tipo di server), classifier.py (classificazione delle minacce basata su regole), report.py (generazione di report Rich console + JSON).

watcher/session.py — Guardiano di sessione. La classe SessionWatcher viene eseguita in un thread demone in background. Scopre i pacchetti cercando requirements.txt, package.json, setup.py e pyproject.toml. Esegue ciascuno attraverso la pipeline sandbox. Espone lo stato tramite get_status() e i risultati tramite una Queue. Blocco della sessione tramite lockfile in /tmp/tracetree_sessions/.

mascot/spider.py — Classe SpiderMascot. Ragno ASCII con 5 stati (idle, success, warning, scanning, confused). Utilizzato nella CLI per feedback visivo durante l'analisi.

hooks/ — Sistema di hook shell. shell_hook.sh avvolge il comando git per intercettare git clone e avviare cascade-watch in background. install_hook.py è un installer cross-platform che rileva bash/zsh e aggiunge la riga source al file RC appropriato.

cli.py — Punto di ingresso CLI Typer. Registra tutti i sottocomandi. Orchestra la pipeline di analisi con barre di progresso Rich e pannelli di output formattati.

Limitazioni e Punti Oscuri

• Affidabilità del modello ML — Il modello RandomForest addestrato è valido solo quanto i suoi dati di addestramento. Il modello attuale è stato addestrato su un piccolo insieme di pacchetti. Per un rilevamento affidabile, esegui cascade-train con un dataset ampio ed etichettato. Il fallback IsolationForest è una baseline euristica, non un modello di qualità produttiva.
• Esclusione della rete sandbox — Per impostazione predefinita, la sandbox disabilita l'accesso alla rete (ip link set eth0 down) prima di eseguire/installare il pacchetto per prevenire l'esfiltrazione attiva dei dati durante la scansione. Sebbene sicuro, ciò significa che il malware che richiede handshake di rete o connessioni C2 durante l'installazione potrebbe non eseguire il suo payload, o alcuni installer legittimi che necessitano di connettività Internet falliranno. Per bypassare, usa l'opzione --controlled-network per abilitare la modalità di rete controllata/sinkhole.
• Evitamento di container e strace — Il malware avanzato può rilevare di essere in esecuzione all'interno di un container Docker (controllando cgroups, indizi del filesystem, ecc.) o rilevare che i suoi processi sono sotto monitoraggio strace/ptrace (chiamando ptrace(PTRACE_TRACEME, ...) o controllando TracerPid in /proc/self/status). Se viene attivato l'evitamento, il malware potrebbe terminare precocemente o eseguire solo azioni benigne, eludendo il rilevamento.

Contribuire

I pull request sono benvenuti. Si prega di mantenere le nuove funzionalità disaccoppiate dai moduli esistenti.

Licenza

MIT