TraceTree

TraceTree Demo

TraceTree (cascade-analyzer) est un organisme de sécurité autonome conçu pour l'ère des agents. Il va au-delà du simple scan pour offrir un écosystème de détection robuste, durci et évolutif. Comme sa mascotte, l'araignée, TraceTree tisse une toile de protection complète autour de votre flux de développement grâce à ses huit « pattes » spécialisées.

Table des matières

• Structure du dépôt
• Export de reçu comportemental
• Les 8 pattes de l'araignée TraceTree
• Comment ça marche
• Ce qu'il détecte
  • Signatures comportementales
  • Motifs temporels
• Cibles prises en charge
• Démarrage rapide (Passer à l'installation)
  • Prérequis
  • Installer
  • Exécuter une analyse
• Référence CLI
• Analyse de sécurité du serveur MCP
• Vue d'ensemble de l'architecture
• Limitations et angles morts

Export de reçu comportemental

TraceTree peut être utilisé comme une passerelle de revue avant que des agents ou des humains ne fassent confiance à l'installation d'un paquet. Voir Export de reçu comportemental pour un petit format de reçu compatible JSON/SARIF qui résume le hachage de la cible, la politique du bac à sable, le comportement observé, les hachages des artefacts, le verdict et les paramètres de confidentialité sans exposer les journaux bruts d'appels système.

Structure du dépôt```

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

## Les 8 pattes de l'araignée TraceTree

1.  **Pattes 1 : Isolation en bac à sable (Le piège)** — Exécute les cibles dans des conteneurs Docker isolés (ou un mode `direct` haute performance) où les menaces sont physiquement contenues.
2.  **Pattes 2 : Analyse des appels système (Le système nerveux)** — Un moteur de haute précision qui surveille chaque « vibration » (appel système) qu'un processus fait à l'OS.
3.  **Pattes 3 : Graphique comportemental (La toile)** — Cartographie la « Cascade » de la façon dont les processus, fichiers et nœuds réseau interagissent en utilisant des graphes dirigés NetworkX.
4.  **Pattes 4 : Détection d'anomalies par ML (L'intuition)** — Un modèle Random Forest personnalisé (entraîné sur un petit ensemble de données représentatif de paquets sains/malveillants, plus des flux optionnels en direct de MalwareBazaar) qui prédit l'intention malveillante avec une haute confiance.
5.  **Pattes 5 : Correspondance de signatures YARA (La mémoire)** — Une bibliothèque intégrée d'ADN de malwares connus et de schémas d'exploitation (Reverse Shells, Cryptomineurs, etc.).
6.  **Pattes 6 : Protocole de sécurité MCP (Le bouclier de l'agent)** — Protection spécialisée pour les serveurs du Protocole de contexte de modèle (MCP), défendant les outils que les agents IA utilisent.
7.  **Pattes 7 : IA de gardien de sécurité (La toile proactive)** — Un « scanner intelligent » pré-commit utilisant des LLM locaux (Qwen-Coder) pour détecter les fuites et injections avant qu'elles n'atteignent votre historique.
8.  **Pattes 8 : Analyse temporelle et N-gram (Le scan d'ADN)** — Identifie les menaces par le *rythme* et la *séquence* de leurs actions dans le temps.

## Comment ça marche```
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 — La cible s'exécute dans un conteneur Docker. Le réseau est désactivé (ip link set eth0 down) avant le début de l'installation/exécution, donc toute tentative de connexion sortante est enregistrée mais bloquée.
2. strace — Chaque appel système est tracé avec strace -t -f -e trace=all. L'option -t ajoute des horodatages pour l'analyse temporelle, -f suit les processus enfants.
3. Parser (monitor/parser.py) — Analyseur basé sur des expressions régulières qui gère les sorties multi-lignes de strace et les deux formats [pid] et pid nu. Extrait la création de processus, l'accès aux fichiers, les connexions réseau et les opérations mémoire. Chaque appel système reçoit un poids de sévérité (0–9) basé sur sa pertinence en sécurité.
4. Correspondance de signatures (monitor/signatures.py) — Fait correspondre le flux d'événements parsé avec 8 modèles de signatures comportementales définis dans data/signatures.json. Chaque correspondance produit des preuves listant les événements spécifiques qui l'ont déclenchée.
5. Analyse temporelle (monitor/timeline.py) — Détecte 5 modèles comportementaux basés sur le temps dans le flux d'événements horodatés (par exemple, lecture d'identifiants suivie d'une connexion externe dans les 5 secondes).

Ce qu'il détecte

Signatures comportementales (8 modèles)

Définies dans data/signatures.json. Chacune a une sévérité (1–10), des appels système requis, des motifs de fichiers, des conditions réseau et une séquence ordonnée à faire correspondre.

Modèles temporels (5 modèles)

Détectés à partir de la sortie horodatée de strace. Nécessite l'option -t de strace (activée par défaut).

Notation pondérée des appels système par sévérité

Chacun des 24 types d'appels système a un poids de sévérité de base. Exemples :

• mprotect avec PROT_EXEC : 9.0
• dup2 après un connect : 9.0
• execve d'un binaire inattendu : 7.0
• connect vers les métadonnées cloud (169.254.x.x) : 8.0
• connect vers le CDN PyPI/npm : 0.0 (bénin)
• openat de /usr/lib/python/* : 0.0 (bénin)

Le score de sévérité total alimente le calcul de confiance du ML.

Classification des destinations réseau

Chaque appel système connect est classé dans l'une des quatre catégories :

Cibles prises en charge

Démarrage rapide

Prérequis

• Python 3.9+
• Docker (doit être en cours d'exécution)

Installation```bash

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

### Lancer une analyse```bash
cascade-analyze --help

Sortie:``` ┌──────────────────────────────────────┐ │ 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%

Pour un paquet malveillant (par exemple, un typosquat connu) :```
 ┌─ 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

Référence CLI

cascade-analyze <target>

Analyse un seul package, binaire ou fichier groupé.```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

**Subcommand : `cascade-analyze mcp`** — Analyse de sécurité du serveur MCP (voir la section MCP ci-dessous).

**Subcommand : `cascade-analyze watch <repo>`** — Gardien de session (voir la section Session Guardian).

**Subcommand : `cascade-analyze check <file>`** — Analyse rapide à la demande.

### `cascade-watch <repo>`

Gardien de session autonome. Surveille un répertoire pour les manifestes de paquets et exécute une analyse sandbox en arrière-plan.```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

Displays a spider mascot in the terminal and polls status in a loop. Press Ctrl+C to stop. Only one watcher per directory is allowed (lockfile at /tmp/tracetree_sessions/).

cascade-check <file>

Quick one-off analysis of a specific file. Starts a fresh sandbox run and returns a verdict.```bash cascade-check setup.py cascade-check ./payload.exe

### `cascade-install-hook`

Installe un hook shell qui exécute `cascade-watch` automatiquement après chaque `git clone`.```bash
cascade-install-hook

Ceci ajoute une ligne source à ~/.bashrc ou ~/.zshrc. Le script de hook se trouve dans ~/.local/share/tracetree/hooks/shell_hook.sh. Après l'installation, chaque git clone lancera un observateur en arrière-plan et enregistrera dans /tmp/tracetree_<reponame>.log.

cascade-train

Pipeline d'entraînement interactif. Demande une clé API MalwareBazaar (optionnelle — peut être ignorée pour s'entraîner uniquement sur des jeux de données locaux), puis :

1. Ingère les échantillons depuis MalwareBazaar (si la clé est fournie)
2. Exécute chacun via le pipeline sandbox
3. Entraîne un RandomForestClassifier sur les caractéristiques extraites
4. Sauvegarde dans ml/model.skops et invalide le cache```bash export MALWAREBAZAAR_AUTH_KEY="your-key" cascade-train

## Analyse de sécurité des serveurs MCP

La sous-commande `cascade-analyze mcp` analyse les serveurs du protocole de contexte de modèle (Model Context Protocol) pour détecter des comportements malveillants. Elle exécute le serveur dans un conteneur isolé, agit comme un client MCP simulé pour découvrir et invoquer chaque outil, puis classifie la trace d'appels système résultante.```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

Ce que fait l'analyse MCP

1. Sandbox — Le serveur s'exécute dans Docker avec le réseau bloqué par défaut. Traçage avec strace -f.
2. Simulation client — Handshake JSON-RPC 2.0 initialize, découverte tools/list, invocation sécurisée de chaque outil avec des arguments synthétiques.
3. Sondes adversariales — Chaque outil est ré-invoqué avec des charges utiles d'injection (; ls /etc, ../../../etc/passwd, <script>alert(1)</script>).
4. Extraction de caractéristiques — Caractéristiques spécifiques MCP : connexions réseau par outil, invocations shell, lectures de fichiers sensibles, changements de comportement sous entrée adversarial.
5. Classification des menaces — Classifieur basé sur des règles avec 6 catégories :

6. Comparaison de référence — Compare les profils d'appels système par rapport à des références codées en dur pour 5 types de serveurs : filesystem, github, postgres, fetch, shell.

Architecture

sandbox/ — Gestion du cycle de vie des conteneurs Docker. Construit cascade-sandbox:latest à partir d'un Dockerfile basé sur python:3.11-slim avec strace, wine64, p7zip-full, cabextract, Node.js et npm. Désactive l'interface réseau (ip link set eth0 down) avant l'exécution de la cible. Prend en charge les cibles pip, npm, DMG et EXE. Renvoie un chemin de journal strace ou une chaîne vide en cas d'échec.

monitor/parser.py — Analyseur de journal strace basé sur des expressions régulières. Gère les entrées d'appels système multi-lignes, les formats [pid] et pid nu, et la sortie horodatée (-t). Suit 24 types d'appels système dans 5 catégories (processus, réseau, fichier, mémoire, IPC). Attribue des poids de sévérité par événement, classe les destinations réseau et signale les accès aux fichiers sensibles. Renvoie des données d'événements structurées avec des horodatages et des décalages en millisecondes relatifs.

monitor/signatures.py — Correspondance de signatures comportementales. Charge 8 motifs à partir de data/signatures.json. Prend en charge à la fois la correspondance non ordonnée (les appels système requis + les motifs de fichier/réseau doivent être présents) et la correspondance de séquence ordonnée (les paires condition-appel système doivent apparaître dans l'ordre). Renvoie les signatures correspondantes avec des preuves listant les événements spécifiques qui ont déclenché chaque correspondance.

monitor/timeline.py — Analyseur de motifs temporels. Détecte 5 motifs comportementaux basés sur le temps à partir du flux d'événements ordonnés et horodatés. Chaque motif spécifie une sévérité, une fenêtre de temps et les conditions de déclenchement. Renvoie les correspondances triées par sévérité décroissante. Actif uniquement lorsque strace a été exécuté avec -t (ce qui est la valeur par défaut).

graph/builder.py — Construction de graphe orienté NetworkX. Crée des nœuds pour les processus, les fichiers et les destinations réseau. Ajoute des arêtes pour les relations de clonage, les cibles d'appels système et les relations temporelles (événements consécutifs du même PID dans les 5 secondes). Les nœuds et les arêtes sont étiquetés avec les correspondances de signatures et les poids de sévérité. Produit du JSON compatible Cytoscape et des statistiques internes.

ml/detector.py — Détection d'anomalies. Extrait un vecteur de 10 caractéristiques (nombre de nœuds, nombre d'arêtes, connexions réseau, lectures de fichiers, nombre d'execve, sévérité totale, réseaux suspects, fichiers sensibles, sévérité maximale, nombre de motifs temporels). Utilise RandomForestClassifier si un modèle entraîné est disponible localement ou téléchargeable depuis GCS ; se rabat sur IsolationForest entraîné sur 10 références de paquets propres codées en dur. Les scores de sévérité et les nombres de motifs temporels augmentent la confiance finale indépendamment de la prédiction ML.

mcp/ — Module d'analyse de serveur MCP. Six fichiers : sandbox.py (bac à sable Docker pour les serveurs MCP), client.py (client JSON-RPC 2.0 avec découverte d'outils et sondes adversariales), features.py (extraction de caractéristiques spécifiques MCP avec détection de type de serveur), classifier.py (classification des menaces basée sur des règles), report.py (console Rich + génération de rapports JSON).

watcher/session.py — Gardien de session. La classe SessionWatcher s'exécute dans un thread démon en arrière-plan. Découvre les paquets en recherchant requirements.txt, package.json, setup.py et pyproject.toml. Exécute chacun via le pipeline du bac à sable. Expose le statut via get_status() et les résultats via une Queue. Verrouillage de session via un fichier de verrouillage à /tmp/tracetree_sessions/.

mascot/spider.py — Classe SpiderMascot. Araignée ASCII avec 5 états (idle, success, warning, scanning, confused). Utilisée dans l'interface en ligne de commande pour un retour visuel pendant l'analyse.

hooks/ — Système de hooks shell. shell_hook.sh encapsule la commande git pour intercepter git clone et lancer cascade-watch en arrière-plan. install_hook.py est un installateur multiplateforme qui détecte bash/zsh et ajoute la ligne source au fichier RC approprié.

cli.py — Point d'entrée de l'interface en ligne de commande Typer. Enregistre toutes les sous-commandes. Orchestre le pipeline d'analyse avec des barres de progression Rich et des panneaux de sortie formatés.

Limitations et angles morts

• Fiabilité du modèle ML — Le modèle RandomForest entraîné n'est aussi bon que ses données d'entraînement. Le modèle actuel a été entraîné sur un petit ensemble de paquets. Pour une détection fiable, exécutez cascade-train avec un grand ensemble de données étiqueté. Le repli IsolationForest est une référence heuristique, pas un modèle de qualité production.
• Exclusion réseau du bac à sable — Par défaut, le bac à sable désactive l'accès réseau (ip link set eth0 down) avant d'exécuter/installer le paquet pour empêcher l'exfiltration active de données pendant l'analyse. Bien que sécurisé, cela signifie que les logiciels malveillants nécessitant des poignées de main réseau ou des connexions C2 pendant l'installation peuvent ne pas exécuter leur charge utile, ou que certains installateurs légitimes nécessitant une connectivité Internet échoueront. Pour contourner cela, passez l'option --controlled-network pour activer le mode réseau contrôlé/entonnoir.
• Évitement de conteneur et strace — Les logiciels malveillants avancés peuvent détecter qu'ils s'exécutent à l'intérieur d'un conteneur Docker (en vérifiant les cgroups, les indices du système de fichiers, etc.) ou détecter que leurs processus sont sous surveillance strace/ptrace (en appelant ptrace(PTRACE_TRACEME, ...) ou en vérifiant TracerPid dans /proc/self/status). Si l'évitement est déclenché, le logiciel malveillant peut se terminer prématurément ou exécuter uniquement des actions bénignes, échappant à la détection.

Contribution

Les pull requests sont les bienvenues. Veuillez garder les nouvelles fonctionnalités découplées des modules existants.

Licence

MIT