TraceTree

TraceTree デモ

TraceTree (cascade-analyzer) は、エージェンティック時代のために設計された自律型セキュリティ生物です。単純なスキャンを超え、堅牢で強化された拡張可能な検出エコシステムへと進化します。マスコットであるクモのように、TraceTree は8本の特殊な「脚」を使って開発ワークフローを包括的に保護するウェブを織り上げます。

目次

• リポジトリ構造
• 動作レシートのエクスポート
• TraceTreeスパイダーの8本の脚
• 動作の仕組み
• 検出内容
  • 行動シグネチャ (8パターン)
  • 時間的パターン (5パターン)
• サポート対象
• クイックスタート（インストールへスキップ）
  • 前提条件
  • インストール
  • 分析の実行
• CLIリファレンス
• MCPサーバーセキュリティ分析
• アーキテクチャ概要
• 制限事項と盲点

動作レシートのエクスポート

TraceTree は、エージェントや人間がパッケージのインストールを信頼する前のレビューゲートとして使用できます。詳細な動作レシートの形状については、動作レシートのエクスポート を参照してください。このレシートは、ターゲットハッシュ、サンドボックスポリシー、観測された動作、アーティファクトハッシュ、判定、プライバシーのデフォルトを要約した、JSON/SARIF に対応した小型のレシート形状であり、生のシステムコールログを公開しません。

リポジトリ構造```

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

## TraceTreeスパイダーの8本の脚

1.  **脚1: サンドボックス分離（罠）** — 隔離されたDockerコンテナ（または高性能な`direct`モード）でターゲットを実行し、脅威を物理的に封じ込めます。
2.  **脚2: システムコール解析（神経系）** — プロセスがOSに対して行うすべての「振動」（システムコール）を監視する高精度エンジン。
3.  **脚3: 行動グラフ化（ウェブ）** — プロセス、ファイル、ネットワークノードの相互作用の「カスケード」をNetworkX有向グラフでマッピングします。
4.  **脚4: ML異常検知（直感）** — クリーン/悪意のあるパッケージの小規模な代表データセットとオプションのMalwareBazaarライブフィードでトレーニングされたカスタムRandom Forestモデルで、高い信頼度で悪意を予測します。
5.  **脚5: YARAシグネチャマッチング（記憶）** — 既知のマルウェアDNAとエクスプロイトパターン（リバースシェル、暗号通貨マイナーなど）の統合ライブラリ。
6.  **脚6: MCPセキュリティプロトコル（エージェントシールド）** — Model Context Protocolサーバーのための特別な保護で、AIエージェントが使用するツールを防御します。
7.  **脚7: セキュリティガーディアンAI（プロアクティブウェブ）** — ローカルLLM（Qwen-Coder）を使用したコミット前の「スマートスキャナー」で、リークやインジェクションが履歴に残る前に検出します。
8.  **脚8: 時間的・Nグラム分析（DNAスキャン）** — 時間を超えたアクションの*リズム*と*シーケンス*で脅威を識別します。

## 動作の仕組み```
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. サンドボックス — ターゲットはDockerコンテナ内で実行されます。インストール/実行開始前にネットワークが切断され（ip link set eth0 down）、そのため外部への接続試行はログに記録されますがブロックされます。
2. strace — すべてのシステムコールが strace -t -f -e trace=all でトレースされます。-t フラグでタイムスタンプが付与され時間分析が可能に、-f で子プロセスも追跡します。
3. パーサー (monitor/parser.py) — 複数行のstrace出力と [pid] 形式・裸のpid形式の両方を処理する正規表現ベースのパーサー。プロセス生成、ファイルアクセス、ネットワーク接続、メモリ操作を抽出します。各システムコールにはセキュリティ関連性に基づく重大度重み（0～9）が割り当てられます。
4. シグネチャマッチング (monitor/signatures.py) — パースされたイベントストリームを data/signatures.json に定義された8つの振る舞いシグネチャパターンと照合します。各一致は、それを引き起こした具体的なイベントをリストアップした証拠を生成します。
5. 時間分析 (monitor/timeline.py) — タイムスタンプ付きイベントストリームから5つの時間ベースの振る舞いパターンを検出します（例：資格情報読み取り後5秒以内の外部接続）。
6. グラフ (graph/builder.py) — プロセス、ファイル、ネットワークノードを持つNetworkX有向グラフを構築します。同じPIDの連続イベント間に5秒以内の時間的なエッジを追加します。
7. ML (ml/detector.py) — グラフとパース済みデータから10特徴量のベクトルを抽出します。学習済みモデルがあれば RandomForestClassifier を使用し、そうでなければ10のハードコードされたクリーンパッケージベースラインで学習した IsolationForest にフォールバックします。重大度スコアと時間パターンカウントが最終的な信頼度を引き上げます。

検出するもの

振る舞いシグネチャ（8パターン）

data/signatures.json で定義。各シグネチャには重大度（1～10）、必要なシステムコール、ファイルパターン、ネットワーク条件、照合する順序付きシーケンスがあります。

時間パターン（5パターン）

タイムスタンプ付きのstrace出力から検出。straceの -t フラグが必要です（デフォルトで有効）。

重大度加重システムコールスコアリング

24種類のシステムコールそれぞれに基本重大度重みがあります。例：

• mprotect with PROT_EXEC: 9.0
• dup2 after a connect: 9.0
• execve of unexpected binary: 7.0
• connect to cloud metadata (169.254.x.x): 8.0
• connect to PyPI/npm CDN: 0.0（良性）
• openat of /usr/lib/python/*: 0.0（良性）

総重大度スコアはML信頼度計算に反映されます。

ネットワーク宛先分類

すべての connect システムコールは次の4カテゴリのいずれかに分類されます：

サポート対象ターゲット

クイックスタート

前提条件

• Python 3.9+
• Docker（実行中であること）

インストール```bash

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

### 分析の実行```bash
cascade-analyze --help

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

悪意のあるパッケージ（例：既知のタイポスクワット）:```
 ┌─ 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>

単一のパッケージ、バイナリ、またはバルクファイルを解析します。```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

**サブコマンド: `cascade-analyze mcp`** — MCPサーバーのセキュリティ分析（以下のMCPセクションを参照）。

**サブコマンド: `cascade-analyze watch <repo>`** — セッションガーディアン（セッションガーディアンセクションを参照）。

**サブコマンド: `cascade-analyze check <file>`** — オンデマンドのクイックスキャン。

### `cascade-watch <repo>`

スタンドアロンセッションガーディアン。ディレクトリを監視してパッケージマニフェストを確認し、バックグラウンドでサンドボックス分析を実行します。```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

ターミナルにクモのマスコットを表示し、ループでステータスをポーリングします。停止するにはCtrl+Cを押します。ディレクトリごとに1つのウォッチャーのみ許可されています（ロックファイルは /tmp/tracetree_sessions/ にあります）。

cascade-check <file>

特定のファイルの簡単な単発解析です。新しいサンドボックス実行を開始し、判定を返します。```bash cascade-check setup.py cascade-check ./payload.exe

### `cascade-install-hook`

シェルフックをインストールし、`cascade-watch`が`git clone`のたびに自動的に実行されるようにします。```bash
cascade-install-hook

これは ~/.bashrc または ~/.zshrc に source 行を追加します。フックスクリプトは ~/.local/share/tracetree/hooks/shell_hook.sh にあります。インストール後、git clone を実行するたびにバックグラウンドウォッチャーが起動し、/tmp/tracetree_<reponame>.log にログを出力します。

cascade-train

対話型トレーニングパイプラインです。MalwareBazaar APIキーを要求します（オプション — ローカルデータセットのみでトレーニングする場合はスキップ可能）。その後、次の処理を行います：

1. MalwareBazaar からサンプルを取り込む（キーが提供された場合）
2. 各サンプルをサンドボックスパイプラインで実行する
3. 抽出された特徴量に基づいて RandomForestClassifier をトレーニングする
4. ml/model.skops に保存し、キャッシュを無効化する```bash export MALWAREBAZAAR_AUTH_KEY="your-key" cascade-train

## MCP Server Security Analysis

`cascade-analyze mcp` サブコマンドは、Model Context Protocol サーバーの悪意のある動作を分析します。サンドボックスコンテナ内でサーバーを実行し、シミュレートされた MCP クライアントとして動作してすべてのツールを発見・呼び出し、結果のシステムコールトレースを分類します。```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

MCP analysis does

1. Sandbox — Server runs in Docker with network blocked by default. Traced with strace -f.
2. Client simulation — JSON-RPC 2.0 initialize handshake, tools/list discovery, safe invocation of every tool with synthetic arguments.
3. Adversarial probes — Each tool re-invoked with injection payloads (; ls /etc, ../../../etc/passwd, <script>alert(1)</script>).
4. Feature extraction — MCP-specific features: per-tool network connections, shell invocations, sensitive file reads, behavior changes under adversarial input.
5. Threat classification — Rule-based classifier with 6 categories:

6. Baseline comparison — Compares syscall profiles against hardcoded baselines for 5 server types: filesystem, github, postgres, fetch, shell.

Architecture

sandbox/ — Docker container lifecycle management. Builds cascade-sandbox:latest from a Dockerfile based on python:3.11-slim with strace, wine64, p7zip-full, cabextract, Node.js, and npm. Drops the network interface (ip link set eth0 down) before target execution. Supports pip, npm, DMG, and EXE targets. Returns a strace log path or empty string on failure.

monitor/parser.py — Regex-based strace log parser. Handles multi-line syscall entries, both [pid] and bare-pid formats, and timestamped (-t) output. Tracks 24 syscall types across 5 categories (process, network, file, memory, IPC). Assigns per-event severity weights, classifies network destinations, and flags sensitive file accesses. Returns structured event data with timestamps and relative millisecond offsets.

monitor/signatures.py — Behavioral signature matcher. Loads 8 patterns from data/signatures.json. Supports both unordered matching (required syscalls + file/network patterns must be present) and ordered sequence matching (syscall-condition pairs must appear in order). Returns matched signatures with evidence listing the specific events that triggered each match.

monitor/timeline.py — Temporal pattern analyzer. Detects 5 time-based behavioral patterns from the ordered, timestamped event stream. Each pattern specifies a severity, a time window, and the triggering conditions. Returns matches sorted by severity descending. Only active when strace was run with -t (which is the default).

graph/builder.py — NetworkX directed graph construction. Creates nodes for processes, files, and network destinations. Adds edges for clone relationships, syscall targets, and temporal relationships (consecutive same-PID events within 5 seconds). Nodes and edges are tagged with signature matches and severity weights. Outputs Cytoscape-compatible JSON and internal stats.

ml/detector.py — Anomaly detection. Extracts a 10-feature vector (node count, edge count, network connections, file reads, execve count, total severity, suspicious networks, sensitive files, max severity, temporal pattern count). Uses RandomForestClassifier if a trained model is available locally or downloadable from GCS; falls back to IsolationForest trained on 10 hardcoded clean-package baselines. Severity scores and temporal pattern counts boost the final confidence independently of the ML prediction.

mcp/ — MCP server analysis module. Six files: sandbox.py (Docker sandbox for MCP servers), client.py (JSON-RPC 2.0 client with tool discovery and adversarial probes), features.py (MCP-specific feature extraction with server type detection), classifier.py (rule-based threat classification), report.py (Rich console + JSON report generation).

watcher/session.py — Session guardian. SessionWatcher class runs in a background daemon thread. Discovers packages by scanning for requirements.txt, package.json, setup.py, and pyproject.toml. Runs each through the sandbox pipeline. Exposes status via get_status() and results via a Queue. Session locking via lockfile at /tmp/tracetree_sessions/.

mascot/spider.py — SpiderMascot class. ASCII spider with 5 states (idle, success, warning, scanning, confused). Used in the CLI for visual feedback during analysis.

hooks/ — Shell hook system. shell_hook.sh wraps the git command to intercept git clone and start cascade-watch in the background. install_hook.py is a cross-platform installer that detects bash/zsh and appends the source line to the appropriate RC file.

cli.py — Typer CLI entry point. Registers all subcommands. Orchestrates the analysis pipeline with Rich progress bars and formatted output panels.

Limitations & Blind Spots

• ML model reliability — The trained RandomForest model is only as good as its training data. The current model was trained on a small set of packages. For reliable detection, run cascade-train with a large, labeled dataset. The IsolationForest fallback is a heuristic baseline, not a production-quality model.
• Network sandbox exclusion — By default, the sandbox disables network access (ip link set eth0 down) before running/installing the package to prevent active data exfiltration during scanning. While secure, this means malware requiring network handshakes or C2 connections during installation may not execute its payload, or some legitimate installers that require internet connectivity will fail. To bypass this, pass the --controlled-network option to enable controlled/sinkhole network mode.
• Container and strace evasion — Advanced malware can detect it is running inside a Docker container (by checking cgroups, filesystem clues, etc.) or detect that its processes are under strace/ptrace monitoring (by calling ptrace(PTRACE_TRACEME, ...) or checking TracerPid in /proc/self/status). If evasion is triggered, the malware may terminate early or execute only benign actions, evading detection.
• strace requires Linux — The sandbox runs on Linux inside Docker. On macOS and Windows, Docker runs a Linux VM, which works, but native macOS or Windows syscalls cannot be traced. DMG scripts and EXE binaries are executed in a Linux environment, which limits their behavioral fidelity.

Contributing

Pull requests are welcome. Please keep new features decoupled from existing modules.

License

MIT