TraceTree

TraceTree-Demo

TraceTree (cascade-analyzer) ist ein autonomer Sicherheitsorganismus, der für die agentische Ära entwickelt wurde. Es geht über einfaches Scannen hinaus und schafft ein robustes, gehärtetes und skalierbares Erkennungsökosystem. Wie sein Maskottchen, die Spinne, webt TraceTree mit seinen acht spezialisierten „Beinen" ein umfassendes Schutznetz um Ihren Entwicklungsworkflow.

Inhaltsverzeichnis

• Repository-Struktur
• Export von Verhaltensbelegen
• Die 8 Beine der TraceTree-Spinne
• Funktionsweise
• Erkennungsfunktionen
  • Verhaltenssignaturen
  • Zeitliche Muster
• Unterstützte Ziele
• Schnellstart (direkt zur Installation)
  • Voraussetzungen
  • Installation
  • Analyse ausführen
• CLI-Referenz
• Sicherheitsanalyse des MCP-Servers
• Architekturübersicht
• Einschränkungen & blinde Flecken

Export von Verhaltensbelegen

TraceTree kann als Prüfinstanz verwendet werden, bevor Agenten oder Menschen einer Paketinstallation vertrauen. Siehe Export von Verhaltensbelegen für eine kleine JSON/SARIF-kompatible Belegform, die Ziel-Hash, Sandbox-Richtlinie, beobachtetes Verhalten, Artefakt-Hashes, Bewertung und Datenschutz-Standardeinstellungen zusammenfasst, ohne die rohen Syscall-Protokolle offenzulegen.

Repository-Struktur```

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

## Die 8 Beine der TraceTree-Spinne

1.  **Bein 1: Sandbox-Isolation (Die Falle)** — Führt Ziele in isolierten Docker-Containern (oder einem leistungsstarken `direct`-Modus) aus, in denen Bedrohungen physisch eingeschlossen sind.
2.  **Bein 2: Syscall-Parsing (Das Nervensystem)** — Eine hochpräzise Engine, die jede „Vibration“ (Systemaufruf) eines Prozesses an das Betriebssystem überwacht.
3.  **Bein 3: Verhaltensgrafik (Das Netz)** — Zeichnet die „Kaskade“ auf, wie Prozesse, Dateien und Netzwerkknoten interagieren, unter Verwendung von NetworkX-Directed-Graphen.
4.  **Bein 4: ML-Anomalieerkennung (Die Intuition)** — Ein benutzerdefiniert trainiertes Random-Forest-Modell (trainiert auf einem kleinen, repräsentativen Datensatz sauberer/bösartiger Pakete, plus optionalen Live-MalwareBazaar-Feeds), das mit hoher Zuversicht bösartige Absichten vorhersagt.
5.  **Bein 5: YARA-Signaturvergleich (Die Erinnerung)** — Eine integrierte Bibliothek bekannter Malware-DNA und Exploit-Muster (Reverse Shells, Cryptominer, etc.).
6.  **Bein 6: MCP-Sicherheitsprotokoll (Der Agentenschild)** — Spezialisierter Schutz für Model-Context-Protocol-Server, die die von KI-Agenten verwendeten Werkzeuge verteidigen.
7.  **Bein 7: Security Guardian AI (Das proaktive Netz)** — Ein Pre-Commit „Smart Scanner“, der lokale LLMs (Qwen-Coder) verwendet, um Lecks und Injections abzufangen, bevor sie in Ihrem Verlauf landen.
8.  **Bein 8: Zeitliche & N-Gramm-Analyse (Der DNA-Scan)** — Identifiziert Bedrohungen anhand des *Rhythmus* und der *Sequenz* ihrer Aktionen über die Zeit.

## So funktioniert es```
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 – Das Ziel läuft in einem Docker-Container. Das Netzwerk wird vor Beginn der Installation/Ausführung deaktiviert (ip link set eth0 down), sodass ausgehende Verbindungsversuche zwar protokolliert, aber blockiert werden.
2. strace – Jeder Syscall wird mit strace -t -f -e trace=all getrace. Das Flag -t fügt Zeitstempel für die zeitliche Analyse hinzu, -f folgt Kindprozessen.
3. Parser (monitor/parser.py) – Regex-basierter Parser, der mehrzeilige strace-Ausgaben sowie sowohl [pid]- als auch reine PID-Formate verarbeitet. Extrahiert Prozesserstellung, Dateizugriffe, Netzwerkverbindungen und Speicheroperationen. Jeder Syscall erhält ein Schweregrad-Gewicht (0–9) basierend auf seiner sicherheitsrelevanten Bedeutung.
4. Signaturerkennung (monitor/signatures.py) – Gleicht den geparsten Ereignisstrom mit 8 in data/signatures.json definierten Verhaltenssignaturmustern ab. Jede Übereinstimmung liefert Belege, die die auslösenden Ereignisse auflisten.
5. Zeitliche Analyse (monitor/timeline.py) – Erkennt 5 zeitbasierte Verhaltensmuster aus dem mit Zeitstempeln versehenen Ereignisstrom (z.B. Lesezugriff auf Anmeldeinformationen, gefolgt von einer externen Verbindung innerhalb von 5 Sekunden).

Was es erkennt

Verhaltenssignaturen (8 Muster)

Definiert in data/signatures.json. Jedes hat einen Schweregrad (1–10), erforderliche Syscalls, Dateimuster, Netzwerkbedingungen und eine geordnete Sequenz zum Abgleich.

Zeitliche Muster (5 Muster)

Erkannt aus der mit Zeitstempeln versehenen strace-Ausgabe. Erfordert das strace-Flag -t (standardmäßig aktiviert).

Schweregrad-gewichtetes Syscall-Scoring

Jeder der 24 Syscall-Typen hat ein Basis-Schweregrad-Gewicht. Beispiele:

• mprotect mit PROT_EXEC: 9,0
• dup2 nach einem connect: 9,0
• execve eines unerwarteten Binärprogramms: 7,0
• connect zu Cloud-Metadaten (169.254.x.x): 8,0
• connect zu PyPI/npm-CDN: 0,0 (gutartig)
• openat von /usr/lib/python/*: 0,0 (gutartig)

Der gesamte Schweregrad-Score fließt in die ML-Konfidenzberechnung ein.

Klassifizierung von Netzwerkzielen

Jeder connect-Syscall wird in eine von vier Kategorien eingeteilt:

Unterstützte Ziele

Schnellstart

Voraussetzungen

• Python 3.9+
• Docker (muss ausgeführt werden)

Installation```bash

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

### Eine Analyse durchführen```bash
cascade-analyze --help

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

Für ein bösartiges Paket (z.B. ein bekanntes Typosquat):```
 ┌─ 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

CLI-Referenz

cascade-analyze <target>

Analysiert ein einzelnes Paket, eine Binärdatei oder eine Bulk-Datei.```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

**Unterbefehl: `cascade-analyze mcp`** — MCP-Server-Sicherheitsanalyse (siehe Abschnitt MCP unten).

**Unterbefehl: `cascade-analyze watch <repo>`** — Sitzungswächter (siehe Abschnitt Session Guardian).

**Unterbefehl: `cascade-analyze check <file>`** — Schneller Scan auf Abruf.

### `cascade-watch <repo>`

Eigenständiger Sitzungswächter. Überwacht ein Verzeichnis auf Paketmanifeste und führt Hintergrund-Sandbox-Analysen durch.```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

Zeigt ein Spider-Maskottchen im Terminal an und fragt den Status in einer Schleife ab. Drücken Sie Ctrl+C zum Beenden. Pro Verzeichnis ist nur ein Watcher erlaubt (Sperrdatei unter /tmp/tracetree_sessions/).

cascade-check <file>

Schnelle einmalige Analyse einer bestimmten Datei. Startet einen neuen Sandbox-Durchlauf und gibt ein Urteil zurück.```bash cascade-check setup.py cascade-check ./payload.exe

### `cascade-install-hook`

Installiert einen Shell-Hook, der `cascade-watch` automatisch nach jedem `git clone` ausführt.```bash
cascade-install-hook

Dies hängt eine source-Zeile an ~/.bashrc oder ~/.zshrc an. Das Hook-Skript befindet sich unter ~/.local/share/tracetree/hooks/shell_hook.sh. Nach der Installation startet jedes git clone einen Hintergrund-Watcher und protokolliert in /tmp/tracetree_<reponame>.log.

cascade-train

Interaktive Trainings-Pipeline. Fragt nach einem MalwareBazaar-API-Key (optional – kann übersprungen werden, um nur mit lokalen Datensätzen zu trainieren), dann:

1. Holt Beispiele von MalwareBazaar (falls Key angegeben)
2. Führt jedes durch die Sandbox-Pipeline
3. Trainiert einen RandomForestClassifier auf den extrahierten Merkmalen
4. Speichert in ml/model.skops und macht den Cache ungültig```bash export MALWAREBAZAAR_AUTH_KEY="your-key" cascade-train

## MCP Server Sicherheitsanalyse

Der Unterbefehl `cascade-analyze mcp` analysiert Model Context Protocol-Server auf schädliches Verhalten. Er führt den Server in einem abgesicherten Container aus, agiert als simulierter MCP-Client, um jedes Werkzeug zu entdecken und aufzurufen, und klassifiziert dann die resultierende Systemaufrufverfolgung.```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

Was die MCP-Analyse macht

1. Sandbox — Der Server läuft in einem Docker-Container mit standardmäßig blockiertem Netzwerk. Verfolgt mit strace -f.
2. Client-Simulation — JSON-RPC 2.0 initialize-Handschlag, tools/list-Erkennung, sichere Ausführung jedes Tools mit synthetischen Argumenten.
3. Adversarial-Tests — Jedes Tool wird erneut mit Injection-Payloads aufgerufen (; ls /etc, ../../../etc/passwd, <script>alert(1)</script>).
4. Merkmal-Extraktion — MCP-spezifische Merkmale: Netzwerkverbindungen pro Tool, Shell-Aufrufe, Lesezugriffe auf sensible Dateien, Verhaltensänderungen unter adversarialen Eingaben.
5. Bedrohungsklassifizierung — Regelbasierter Klassifikator mit 6 Kategorien:

6. Basislinienvergleich — Vergleicht Syscall-Profile mit fest codierten Basislinien für 5 Server-Typen: filesystem, github, postgres, fetch, shell.

Architektur

sandbox/ — Lebenszyklusverwaltung von Docker-Containern. Baut cascade-sandbox:latest aus einem Dockerfile basierend auf python:3.11-slim mit strace, wine64, p7zip-full, cabextract, Node.js und npm. Deaktiviert die Netzwerkschnittstelle (ip link set eth0 down) vor der Ziel-Ausführung. Unterstützt Pip-, npm-, DMG- und EXE-Ziele. Gibt einen strace-Log-Pfad oder eine leere Zeichenkette bei Fehlschlag zurück.

monitor/parser.py — Regex-basierter strace-Log-Parser. Verarbeitet mehrzeilige Syscall-Einträge, sowohl [pid]- als auch reine-PID-Formate sowie timestamp-ausgegebene (-t) Ausgaben. Verfolgt 24 Syscall-Typen in 5 Kategorien (Prozess, Netzwerk, Datei, Speicher, IPC). Weist jedem Ereignis Gewichtungen für den Schweregrad zu, klassifiziert Netzwerkziele und markiert sensible Dateizugriffe. Gibt strukturierte Ereignisdaten mit Zeitstempeln und relativen Millisekunden-Offsets zurück.

monitor/signatures.py — Abgleich-Verhaltenssignaturen. Lädt 8 Muster aus data/signatures.json. Unterstützt sowohl ungeordneten Abgleich (erforderliche Syscalls + Datei-/Netzwerkmuster müssen vorhanden sein) als auch geordneten Sequenzabgleich (Syscall-Bedingung-Paare müssen in Reihenfolge erscheinen). Gibt abgeglichene Signaturen mit Nachweisen zurück, die die spezifischen Ereignisse auflisten, die jeden Treffer ausgelöst haben.

monitor/timeline.py — Zeitlicher Musteranalysator. Erkennt 5 zeitbasierte Verhaltensmuster aus dem geordneten, mit Zeitstempel versehenen Ereignisstrom. Jedes Muster gibt einen Schweregrad, ein Zeitfenster und die auslösenden Bedingungen an. Gibt Treffer absteigend nach Schweregrad sortiert zurück. Nur aktiv, wenn strace mit -t ausgeführt wurde (was der Standard ist).

graph/builder.py — Erstellung gerichteter Graphen mit NetworkX. Erstellt Knoten für Prozesse, Dateien und Netzwerkziele. Fügt Kanten für Clone-Beziehungen, Syscall-Ziele und zeitliche Beziehungen (aufeinanderfolgende Ereignisse mit derselben PID innerhalb von 5 Sekunden) hinzu. Knoten und Kanten werden mit Signaturtreffern und Schweregrad-Gewichtungen versehen. Gibt Cytoscape-kompatibles JSON und interne Statistiken aus.

ml/detector.py — Anomalieerkennung. Extrahiert einen 10-Merkmals-Vektor (Knotenanzahl, Kantenanzahl, Netzwerkverbindungen, Dateilesevorgänge, execve-Anzahl, Gesamtschweregrad, verdächtige Netzwerke, sensible Dateien, maximaler Schweregrad, Anzahl zeitlicher Muster). Verwendet RandomForestClassifier, wenn ein trainiertes Modell lokal verfügbar ist oder von GCS heruntergeladen werden kann; falls nicht, fällt es auf IsolationForest zurück, trainiert auf 10 fest codierten Sauber-Paket-Basislinien. Schweregrad-Scores und Anzahl zeitlicher Muster erhöhen die endgültige Konfidenz unabhängig von der ML-Vorhersage.

mcp/ — MCP-Server-Analysemodul. Sechs Dateien: sandbox.py (Docker-Sandbox für MCP-Server), client.py (JSON-RPC 2.0-Client mit Tool-Erkennung und adversarialen Tests), features.py (MCP-spezifische Merkmal-Extraktion mit Server-Typ-Erkennung), classifier.py (regelbasierte Bedrohungsklassifizierung), report.py (Rich-Konsole + JSON-Berichterstellung).

watcher/session.py — Sitzungswächter. Die Klasse SessionWatcher läuft in einem Hintergrund-Daemon-Thread. Entdeckt Pakete durch Scannen nach requirements.txt, package.json, setup.py und pyproject.toml. Führt jedes durch die Sandbox-Pipeline. Stellt Status über get_status() und Ergebnisse über eine Queue bereit. Sitzungssperrung über Sperrdatei unter /tmp/tracetree_sessions/.

mascot/spider.py — Klasse SpiderMascot. ASCII-Spinne mit 5 Zuständen (idle, success, warning, scanning, confused). Wird in der CLI für visuelles Feedback während der Analyse verwendet.

hooks/ — Shell-Hook-System. shell_hook.sh umschließt den Befehl git, um git clone abzufangen und cascade-watch im Hintergrund zu starten. install_hook.py ist ein plattformübergreifender Installer, der bash/zsh erkennt und die Source-Zeile an die entsprechende RC-Datei anhängt.

cli.py — Typer-CLI-Einstiegspunkt. Registriert alle Unterbefehle. Orchestriert die Analyse-Pipeline mit Rich-Fortschrittsbalken und formatierten Ausgabe-Panels.

Einschränkungen & blinde Flecken

• Zuverlässigkeit des ML-Modells — Das trainierte RandomForest-Modell ist nur so gut wie seine Trainingsdaten. Das aktuelle Modell wurde auf einer kleinen Menge von Paketen trainiert. Für eine zuverlässige Erkennung führen Sie cascade-train mit einem großen, gelabelten Datensatz aus. Der IsolationForest-Fallback ist eine heuristische Basislinie, kein produktionsreifes Modell.
• Netzwerk-Sandbox-Ausschluss — Standardmäßig deaktiviert die Sandbox den Netzwerkzugriff (ip link set eth0 down) vor dem Ausführen/Installieren des Pakets, um eine aktive Datenexfiltration während des Scannens zu verhindern. Das ist zwar sicher, bedeutet aber, dass Schadsoftware, die während der Installation Netzwerk-Handshakes oder C2-Verbindungen benötigt, möglicherweise ihre Nutzlast nicht ausführt, oder dass einige legitime Installer, die Internetverbindung benötigen, fehlschlagen. Um dies zu umgehen, übergeben Sie die Option --controlled-network, um den kontrollierten/Sinkhole-Netzwerkmodus zu aktivieren.
• Container- und strace-Umgehung — Fortgeschrittene Schadsoftware kann erkennen, dass sie in einem Docker-Container läuft (durch Überprüfung von cgroups, Dateisystem-Hinweisen usw.) oder dass ihre Prozesse unter strace/ptrace-Überwachung stehen (durch Aufruf von ptrace(PTRACE_TRACEME, ...) oder Überprüfung von TracerPid in /proc/self/status). Wird eine solche Umgehung ausgelöst, kann die Schadsoftware vorzeitig beenden oder nur gutartige Aktionen ausführen und so der Erkennung entgehen.

Mitwirken

Pull-Requests sind willkommen. Bitte halten Sie neue Funktionen entkoppelt von bestehenden Modulen.

Lizenz

MIT