TraceTree

TraceTree Demo

TraceTree (cascade-analyzer) es un organismo de seguridad autónomo diseñado para la era de los agentes. Va más allá del simple escaneo para convertirse en un ecosistema de detección robusto, endurecido y escalable. Como su mascota, la araña, TraceTree teje una red integral de protección alrededor de tu flujo de trabajo de desarrollo utilizando sus ocho "patas" especializadas.

Tabla de Contenidos

• Estructura del Repositorio
• Exportación de Recibos de Comportamiento
• Las 8 Patas de la Araña TraceTree
• Cómo Funciona
• Qué Detecta
  • Firmas de Comportamiento
  • Patrones Temporales
• Objetivos Compatibles
• Inicio Rápido (Ir a Instalación)
  • Requisitos Previos
  • Instalación
  • Ejecutar un Análisis
• Referencia de CLI
• Análisis de Seguridad del Servidor MCP
• Visión General de la Arquitectura
• Limitaciones y Puntos Ciegos

Exportación de Recibos de Comportamiento

TraceTree se puede utilizar como un control de revisión antes de que agentes o humanos confíen en la instalación de un paquete. Consulta Exportación de Recibos de Comportamiento para un pequeño formato de recibo compatible con JSON/SARIF que resume el hash del objetivo, la política de sandbox, el comportamiento observado, los hashes de artefactos, el veredicto y los valores predeterminados de privacidad sin exponer registros de syscall sin procesar.

Estructura del Repositorio```

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

## Las 8 Patas de la Araña TraceTree

1.  **Pata 1: Aislamiento en Sandbox (La Trampa)** — Ejecuta los objetivos en contenedores Docker aislados (o un modo `direct` de alto rendimiento) donde las amenazas están físicamente contenidas.
2.  **Pata 2: Análisis de Syscalls (El Sistema Nervioso)** — Un motor de alta precisión que monitorea cada "vibración" (llamada al sistema) que un proceso realiza al SO.
3.  **Pata 3: Graficación de Comportamiento (La Telaraña)** — Mapea la "Cascada" de cómo interactúan los procesos, archivos y nodos de red utilizando grafos dirigidos de NetworkX.
4.  **Pata 4: Detección de Anomalías con ML (La Intuición)** — Un modelo Random Forest entrenado a medida (con un conjunto de datos pequeño y representativo de paquetes limpios/maliciosos, más fuentes opcionales en vivo de MalwareBazaar) que predice la intención maliciosa con alta confianza.
5.  **Pata 5: Coincidencia de Firmas YARA (La Memoria)** — Una biblioteca integrada de ADN de malware conocido y patrones de explotación (Reverse Shells, Cryptominers, etc.).
6.  **Pata 6: Protocolo de Seguridad MCP (El Escudo del Agente)** — Protección especializada para servidores Model Context Protocol, defendiendo las herramientas que los agentes de IA utilizan.
7.  **Pata 7: Guardian de Seguridad IA (La Telaraña Proactiva)** — Un "Escáner Inteligente" previo al commit que utiliza LLMs locales (Qwen-Coder) para detectar filtraciones e inyecciones antes de que lleguen a tu historial.
8.  **Pata 8: Análisis Temporal y de N-gramas (El Escaneo de ADN)** — Identifica amenazas por el *ritmo* y la *secuencia* de sus acciones a lo largo del tiempo.

## Cómo Funciona```
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 — El objetivo se ejecuta dentro de un contenedor Docker. La red se desconecta (ip link set eth0 down) antes de que comience la instalación/ejecución, por lo que cualquier intento de conexión saliente se registra pero se bloquea.
2. strace — Cada llamada al sistema se rastrea con strace -t -f -e trace=all. La bandera -t agrega marcas de tiempo para análisis temporal, -f sigue los procesos hijo.
3. Analizador (monitor/parser.py) — Analizador basado en expresiones regulares que maneja la salida multilínea de strace y ambos formatos [pid] y pid simple. Extrae creación de procesos, acceso a archivos, conexiones de red y operaciones de memoria. A cada llamada al sistema se le asigna un peso de severidad (0–9) según su relevancia de seguridad.
4. Coincidencia de firmas (monitor/signatures.py) — Compara el flujo de eventos analizados con 8 patrones de firmas de comportamiento definidos en data/signatures.json. Cada coincidencia produce evidencia que enumera los eventos específicos que la desencadenaron.
5. Análisis temporal (monitor/timeline.py) — Detecta 5 patrones de comportamiento basados en el tiempo a partir del flujo de eventos con marcas de tiempo (por ejemplo, lectura de credenciales seguida de conexión externa en menos de 5 segundos).

Qué detecta

Firmas de comportamiento (8 patrones)

Definidas en data/signatures.json. Cada una tiene una severidad (1–10), llamadas al sistema requeridas, patrones de archivo, condiciones de red y una secuencia ordenada para coincidir.

Patrones temporales (5 patrones)

Detectados a partir de la salida de strace con marcas de tiempo. Requiere la bandera -t de strace (habilitada por defecto).

Puntuación de llamadas al sistema con peso de severidad

Cada uno de los 24 tipos de llamadas al sistema tiene un peso de severidad base. Ejemplos:

• mprotect con PROT_EXEC: 9.0
• dup2 después de un connect: 9.0
• execve de binario inesperado: 7.0
• connect a metadatos en la nube (169.254.x.x): 8.0
• connect a CDN de PyPI/npm: 0.0 (benigno)
• openat de /usr/lib/python/*: 0.0 (benigno)

La puntuación de severidad total alimenta el cálculo de confianza del ML.

Clasificación de destino de red

Cada llamada al sistema connect se clasifica en una de cuatro categorías:

Objetivos compatibles

Inicio rápido

Requisitos previos

• Python 3.9+
• Docker (debe estar en ejecución)

Instalar```bash

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

### Ejecutar un análisis```bash
cascade-analyze --help

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

Para un paquete malicioso (p. ej., un typosquat conocido):```
 ┌─ 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 Reference

cascade-analyze <target>

Analiza un solo paquete, binario o archivo masivo.```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`** — Análisis de seguridad del servidor MCP (ver sección MCP más abajo).

**Subcommand: `cascade-analyze watch <repo>`** — Guardián de sesión (ver sección Guardián de Sesión).

**Subcommand: `cascade-analyze check <file>`** — Escaneo rápido bajo demanda.

### `cascade-watch <repo>`

Guardián de sesión independiente. Vigila un directorio en busca de manifiestos de paquetes y ejecuta análisis en entorno aislado en segundo plano.```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

Muestra una mascota de araña en la terminal y consulta el estado en un bucle. Presiona Ctrl+C para detener. Solo se permite un vigilante por directorio (archivo de bloqueo en /tmp/tracetree_sessions/).

cascade-check <file>

Análisis rápido y único de un archivo específico. Inicia una ejecución nueva en entorno aislado y devuelve un veredicto.```bash cascade-check setup.py cascade-check ./payload.exe

### `cascade-install-hook`

Instala un hook de shell que ejecuta `cascade-watch` automáticamente después de cada `git clone`.```bash
cascade-install-hook

This appends a source line to ~/.bashrc or ~/.zshrc. The hook script lives at ~/.local/share/tracetree/hooks/shell_hook.sh. After installation, every git clone will launch a background watcher and log to /tmp/tracetree_<reponame>.log.

cascade-train

Pipeline de entrenamiento interactivo. Solicita una clave API de MalwareBazaar (opcional — se puede omitir para entrenar solo con conjuntos de datos locales), luego:

1. Ingiere muestras de MalwareBazaar (si se proporcionó la clave)
2. Ejecuta cada una a través del pipeline del sandbox
3. Entrena un RandomForestClassifier en las características extraídas
4. Guarda en ml/model.skops e invalida la caché```bash export MALWAREBAZAAR_AUTH_KEY="your-key" cascade-train

## Análisis de seguridad del servidor MCP

El subcomando `cascade-analyze mcp` analiza servidores MCP para detectar comportamientos maliciosos. Ejecuta el servidor en un contenedor aislado, actúa como un cliente MCP simulado para descubrir e invocar cada herramienta, y luego clasifica el rastreo de llamadas al sistema resultante.```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

Qué hace el análisis MCP

1. Sandbox — El servidor se ejecuta en Docker con la red bloqueada por defecto. Rastreado con strace -f.
2. Simulación de cliente — Protocolo de inicio initialize JSON-RPC 2.0, descubrimiento tools/list, invocación segura de cada herramienta con argumentos sintéticos.
3. Sondas adversariales — Cada herramienta se vuelve a invocar con cargas de inyección (; ls /etc, ../../../etc/passwd, <script>alert(1)</script>).
4. Extracción de características — Características específicas de MCP: conexiones de red por herramienta, invocaciones de shell, lecturas de archivos sensibles, cambios de comportamiento bajo entrada adversarial.
5. Clasificación de amenazas — Clasificador basado en reglas con 6 categorías:

6. Comparación de línea base — Compara perfiles de syscall con líneas base codificadas para 5 tipos de servidores: filesystem, github, postgres, fetch, shell.

Arquitectura

sandbox/ — Gestión del ciclo de vida del contenedor Docker. Construye cascade-sandbox:latest a partir de un Dockerfile basado en python:3.11-slim con strace, wine64, p7zip-full, cabextract, Node.js y npm. Desactiva la interfaz de red (ip link set eth0 down) antes de la ejecución del objetivo. Soporta objetivos pip, npm, DMG y EXE. Devuelve una ruta de registro de strace o una cadena vacía en caso de fallo.

monitor/parser.py — Analizador de registros de strace basado en expresiones regulares. Maneja entradas de syscall multilínea, tanto en formato [pid] como pid simple, y salida con marca de tiempo (-t). Rastrea 24 tipos de syscall en 5 categorías (proceso, red, archivo, memoria, IPC). Asigna pesos de gravedad por evento, clasifica destinos de red y marca accesos a archivos sensibles. Devuelve datos de eventos estructurados con marcas de tiempo y desplazamientos relativos en milisegundos.

monitor/signatures.py — Coincidencia de firmas de comportamiento. Carga 8 patrones desde data/signatures.json. Soporta tanto coincidencia desordenada (las syscalls requeridas + los patrones de archivo/red deben estar presentes) como coincidencia de secuencia ordenada (los pares syscall-condición deben aparecer en orden). Devuelve firmas coincidentes con evidencia que enumera los eventos específicos que desencadenaron cada coincidencia.

monitor/timeline.py — Analizador de patrones temporales. Detecta 5 patrones de comportamiento basados en el tiempo a partir del flujo de eventos ordenado y con marca de tiempo. Cada patrón especifica una gravedad, una ventana de tiempo y las condiciones de activación. Devuelve coincidencias ordenadas por gravedad descendente. Solo activo cuando strace se ejecutó con -t (que es el valor predeterminado).

graph/builder.py — Construcción de gráfico dirigido NetworkX. Crea nodos para procesos, archivos y destinos de red. Agrega aristas para relaciones de clonación, objetivos de syscall y relaciones temporales (eventos consecutivos del mismo PID dentro de 5 segundos). Los nodos y aristas se etiquetan con coincidencias de firmas y pesos de gravedad. Genera JSON compatible con Cytoscape y estadísticas internas.

ml/detector.py — Detección de anomalías. Extrae un vector de 10 características (recuento de nodos, recuento de aristas, conexiones de red, lecturas de archivos, recuento de execve, gravedad total, redes sospechosas, archivos sensibles, gravedad máxima, recuento de patrones temporales). Utiliza RandomForestClassifier si hay un modelo entrenado disponible localmente o descargable desde GCS; recurre a IsolationForest entrenado en 10 líneas base de paquetes limpios codificados. Las puntuaciones de gravedad y los recuentos de patrones temporales aumentan la confianza final independientemente de la predicción de ML.

mcp/ — Módulo de análisis de servidores MCP. Seis archivos: sandbox.py (sandbox Docker para servidores MCP), client.py (cliente JSON-RPC 2.0 con descubrimiento de herramientas y sondas adversariales), features.py (extracción de características específicas de MCP con detección de tipo de servidor), classifier.py (clasificación de amenazas basada en reglas), report.py (generación de informes en consola Rich + JSON).

watcher/session.py — Guardián de sesión. La clase SessionWatcher se ejecuta en un hilo demonio en segundo plano. Descubre paquetes escaneando requirements.txt, package.json, setup.py y pyproject.toml. Ejecuta cada uno a través del pipeline de sandbox. Expone el estado a través de get_status() y los resultados a través de una Queue. Bloqueo de sesión mediante archivo de bloqueo en /tmp/tracetree_sessions/.

mascot/spider.py — Clase SpiderMascot. Araña ASCII con 5 estados (idle, success, warning, scanning, confused). Utilizada en la CLI para retroalimentación visual durante el análisis.

hooks/ — Sistema de hooks de shell. shell_hook.sh envuelve el comando git para interceptar git clone e iniciar cascade-watch en segundo plano. install_hook.py es un instalador multiplataforma que detecta bash/zsh y agrega la línea de origen al archivo RC correspondiente.

cli.py — Punto de entrada CLI Typer. Registra todos los subcomandos. Orquesta el pipeline de análisis con barras de progreso Rich y paneles de salida formateados.

Limitaciones y Puntos Ciegos

• Fiabilidad del modelo ML — El modelo RandomForest entrenado solo es tan bueno como sus datos de entrenamiento. El modelo actual fue entrenado en un pequeño conjunto de paquetes. Para una detección confiable, ejecute cascade-train con un conjunto de datos grande y etiquetado. El recurso de IsolationForest es una línea base heurística, no un modelo de calidad de producción.
• Exclusión de red del sandbox — Por defecto, el sandbox desactiva el acceso a la red (ip link set eth0 down) antes de ejecutar/instalar el paquete para evitar la exfiltración activa de datos durante el escaneo. Aunque es seguro, esto significa que el malware que requiere handshakes de red o conexiones C2 durante la instalación puede no ejecutar su carga útil, o algunos instaladores legítimos que requieren conectividad a Internet fallarán. Para sortear esto, pase la opción --controlled-network para habilitar el modo de red controlada/sinkhole.
• Evasión de contenedor y strace — El malware avanzado puede detectar que se está ejecutando dentro de un contenedor Docker (verificando cgroups, pistas del sistema de archivos, etc.) o detectar que sus procesos están bajo monitoreo de strace/ptrace (llamando a ptrace(PTRACE_TRACEME, ...) o verificando TracerPid en /proc/self/status). Si se desencadena la evasión, el malware puede terminar temprano o ejecutar solo acciones benignas, evadiendo la detección.
• strace requiere Linux — El sandbox se ejecuta en Linux dentro de Docker. En macOS y Windows, Docker ejecuta una VM Linux, lo que funciona, pero las syscalls nativas de macOS o Windows no se pueden rastrear. Los scripts DMG y los binarios EXE se ejecutan en un entorno Linux, lo que limita su fidelidad de comportamiento.

Contribuciones

Las solicitudes de extracción son bienvenidas. Mantenga las nuevas características desacopladas de los módulos existentes.

Licencia

MIT