TraceTree

TraceTree Demo

TraceTree (cascade-analyzer) is an autonomous security organism designed for the agentic era. It moves beyond simple scanning into a robust, hardened, and scalable detection ecosystem. Like its mascot, the spider, TraceTree weaves a comprehensive web of protection around your development workflow using its eight specialized "legs."

Table of Contents

• Repository Structure
• Behavior receipt export
• The 8 Legs of the TraceTree Spider
• How It Works
• What It Detects
  • Behavioral Signatures
  • Temporal Patterns
• Supported Targets
• Quick Start (Skip to Installation)
  • Prerequisites
  • Install
  • Run an Analysis
• CLI Reference
• MCP Server Security Analysis
• Architecture Overview
• Limitations & Blind Spots

Behavior receipt export

TraceTree can be used as a review gate before agents or humans trust a package install. See Behavior receipt export for a small JSON/SARIF-friendly receipt shape that summarizes target hash, sandbox policy, observed behavior, artifact hashes, verdict, and privacy defaults without exposing raw syscall logs.

Repository Structure

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

The 8 Legs of the TraceTree Spider

1. Leg 1: Sandbox Isolation (The Trap) — Executes targets in isolated Docker containers (or a high-performance direct mode) where threats are physically contained.
2. Leg 2: Syscall Parsing (The Nervous System) — A high-precision engine that monitors every "vibration" (system call) a process makes to the OS.
3. Leg 3: Behavioral Graphing (The Web) — Maps the "Cascade" of how processes, files, and network nodes interact using NetworkX directed graphs.
4. Leg 4: ML Anomaly Detection (The Intuition) — A custom-trained Random Forest model (trained on a small, representative dataset of clean/malicious packages, plus optional live MalwareBazaar feeds) that predicts malicious intent with high confidence.
5. Leg 5: YARA Signature Matching (The Memory) — An integrated library of known malware DNA and exploit patterns (Reverse Shells, Cryptominers, etc.).
6. Leg 6: MCP Security Protocol (The Agent Shield) — Specialized protection for Model Context Protocol servers, defending the tools that AI agents use.
7. Leg 7: Security Guardian AI (The Proactive Web) — A pre-commit "Smart Scanner" using local LLMs (Qwen-Coder) to catch leaks and injections before they hit your history.
8. Leg 8: Temporal & N-gram Analysis (The DNA Scan) — Identifies threats by the rhythm and sequence of their actions across time.

How It Works

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 — The target runs inside a Docker container. Network is dropped (ip link set eth0 down) before installation/execution begins, so any outbound connection attempts are logged but blocked.
2. strace — Every syscall is traced with strace -t -f -e trace=all. The -t flag adds timestamps for temporal analysis, -f follows child processes.
3. Parser (monitor/parser.py) — Regex-based parser that handles multi-line strace output and both [pid] and bare-pid formats. Extracts process creation, file access, network connections, and memory operations. Each syscall is assigned a severity weight (0–9) based on its security relevance.
4. Signature matching (monitor/signatures.py) — Matches the parsed event stream against 8 behavioral signature patterns defined in data/signatures.json. Each match produces evidence listing the specific events that triggered it.
5. Temporal analysis (monitor/timeline.py) — Detects 5 time-based behavioral patterns from the timestamped event stream (e.g., credential read followed by external connection within 5 seconds).
6. Graph (graph/builder.py) — Builds a NetworkX directed graph with process, file, and network nodes. Adds temporal edges between consecutive same-PID events within a 5-second window.
7. ML (ml/detector.py) — Extracts a 10-feature vector from the graph and parsed data. Uses a RandomForestClassifier if a trained model is available, falls back to an IsolationForest trained on 10 hardcoded clean-package baselines. Severity scores and temporal pattern counts boost the final confidence.

What It Detects

Behavioral Signatures (8 patterns)

Defined in data/signatures.json. Each has a severity (1–10), required syscalls, file patterns, network conditions, and an ordered sequence to match.