TraceTree

TraceTree Demo

TraceTree（cascade-analyzer）是一个专为智能体时代设计的自主安全有机体。它超越了简单的扫描，构建了一个健壮、加固且可扩展的检测生态系统。就像其吉祥物蜘蛛一样，TraceTree 使用其八个专门化的“腿”围绕您的开发工作流程编织一张全面的保护网。

目录

• 仓库结构
• 行为凭证导出
• TraceTree 蜘蛛的八条腿
• 工作原理
• 检测内容
  • 行为签名
  • 时间模式
• 支持的目标
• 快速开始（跳转至安装）
  • 前提条件
  • 安装
  • 运行分析
• 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 蜘蛛的八条腿

1.  **第1条腿：沙盒隔离（陷阱）** — 在隔离的 Docker 容器（或高性能的 `direct` 模式）中执行目标，威胁被物理限制在其中。
2.  **第2条腿：系统调用解析（神经系统）** — 一个高精度引擎，监控进程对操作系统发出的每一次“振动”（系统调用）。
3.  **第3条腿：行为图谱（网）** — 使用 NetworkX 有向图绘制进程、文件和网络节点交互的“级联”关系。
4.  **第4条腿：机器学习异常检测（直觉）** — 一个自定义训练的随机森林模型（在一个小型、有代表性的干净/恶意包数据集上训练，加上可选的实时 MalwareBazaar 数据源），以高置信度预测恶意意图。
5.  **第5条腿：YARA 签名匹配（记忆）** — 一个已知恶意软件 DNA 和利用模式（反向 Shell、加密货币矿工等）的集成库。
6.  **第6条腿：MCP 安全协议（代理盾牌）** — 针对模型上下文协议服务器的专门保护，防御 AI 代理使用的工具。
7.  **第7条腿：安全守护 AI（主动网）** — 一个提交前的“智能扫描器”，使用本地 LLM（Qwen-Coder）在泄露和注入进入你的历史之前捕获它们。
8.  **第8条腿：时间与 N-gram 分析（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 有向图，包含进程、文件和网络节点。在 5 秒窗口内的连续相同 PID 事件之间添加时间边。
7. 机器学习 (ml/detector.py) — 从图和解析数据中提取一个 10 特征向量。如果有训练好的模型，则使用 RandomForestClassifier，否则回退到基于 10 个硬编码的干净包基线训练的 IsolationForest。严重性分数和时间模式计数提高最终置信度。

检测内容

行为签名 (8 种模式)

定义在 data/signatures.json 中。每个都有一个严重性 (1–10)、必需的系统调用、文件模式、网络条件和要匹配的有序序列。

时间模式 (5 种模式)

从带有时间戳的 strace 输出中检测。需要 strace -t 标志（默认启用）。

严重性权重的系统调用评分

24 种系统调用类型中的每一个都有一个基础严重性权重。示例：

• mprotect 使用 PROT_EXEC: 9.0
• 在 connect 之后的 dup2: 9.0
• execve 执行意外二进制文件: 7.0
• connect 连接到云元数据 (169.254.x.x): 8.0
• connect 连接到 PyPI/npm CDN: 0.0（良性）
• openat 打开 /usr/lib/python/*: 0.0（良性）

总严重性分数用于 ML 置信度计算。

网络目标分类

每个 connect 系统调用被分为以下四个类别之一：

支持的目标

快速开始

先决条件

• 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 参考

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 停止。每个目录只允许一个监视器（锁定文件位于 /tmp/tracetree_sessions/）。

cascade-check <file>

对特定文件进行快速一次性分析。启动一个新的沙箱运行并返回判定结果。```bash cascade-check setup.py cascade-check ./payload.exe

### `cascade-install-hook`

安装一个 shell 钩子，使每次 `git clone` 后自动运行 `cascade-watch`。```bash
cascade-install-hook

这会将一个 source 行追加到 ~/.bashrc 或 ~/.zshrc 中。钩子脚本位于 ~/.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 服务器安全分析

`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 分析的内容

1. 沙箱 — 服务器在 Docker 中运行，默认禁用网络。通过 strace -f 追踪。
2. 客户端模拟 — JSON-RPC 2.0 initialize 握手、tools/list 发现、使用合成参数安全调用每个工具。
3. 对抗性探测 — 每个工具使用注入载荷重新调用（; ls /etc、../../../etc/passwd、<script>alert(1)</script>）。
4. 特征提取 — MCP 专属特征：每个工具的网络连接、Shell 调用、敏感文件读取、对抗性输入下的行为变化。
5. 威胁分类 — 基于规则的分类器，包含 6 个类别：

6. 基线比较 — 将系统调用配置文件与 5 种服务器类型的硬编码基线进行比较：filesystem、github、postgres、fetch、shell。

架构

sandbox/ — Docker 容器生命周期管理。基于 python:3.11-slim 的 Dockerfile 构建 cascade-sandbox:latest，包含 strace、wine64、p7zip-full、cabextract、Node.js 和 npm。在目标执行前关闭网络接口（ip link set eth0 down）。支持 pip、npm、DMG 和 EXE 目标。返回 strace 日志路径，失败时返回空字符串。

monitor/parser.py — 基于正则表达式的 strace 日志解析器。处理多行系统调用条目，支持 [pid] 和无 pid 格式，以及带时间戳（-t）的输出。跟踪 5 个类别（进程、网络、文件、内存、IPC）中的 24 种系统调用类型。为每个事件分配严重性权重，分类网络目标，并标记敏感文件访问。返回包含时间戳和相对毫秒偏移量的结构化事件数据。

monitor/signatures.py — 行为签名匹配器。从 data/signatures.json 加载 8 个模式。支持无序匹配（必须存在所需的系统调用 + 文件/网络模式）和有序序列匹配（系统调用-条件对必须按顺序出现）。返回匹配的签名，并附带触发每个匹配的具体事件证据。

monitor/timeline.py — 时间模式分析器。从有序、带时间戳的事件流中检测 5 种基于时间的行为模式。每个模式指定了严重性、时间窗口和触发条件。按严重性降序返回匹配结果。仅当使用 -t 选项运行 strace 时（默认启用）才有效。

graph/builder.py — NetworkX 有向图构建。为进程、文件和网络目标创建节点。为 clone 关系、系统调用目标以及时间关系（同一 PID 的连续事件在 5 秒内）添加边。节点和边带有签名匹配和严重性权重标记。输出 Cytoscape 兼容的 JSON 和内部统计信息。

ml/detector.py — 异常检测。提取一个 10 维特征向量（节点数、边数、网络连接数、文件读取数、execve 计数、总严重性、可疑网络数、敏感文件数、最大严重性、时间模式计数）。如果本地存在训练好的模型或可从 GCS 下载，则使用 RandomForestClassifier；否则回退到基于 10 个硬编码干净包基线的 IsolationForest。严重性得分和时间模式计数独立于 ML 预测提升最终置信度。

mcp/ — MCP 服务器分析模块。六个文件：sandbox.py（MCP 服务器的 Docker 沙箱）、client.py（JSON-RPC 2.0 客户端，包含工具发现和对抗性探测）、features.py（MCP 专属特征提取，带服务器类型检测）、classifier.py（基于规则的威胁分类器）、report.py（Rich 控制台 + JSON 报告生成）。

watcher/session.py — 会话守护器。SessionWatcher 类在后台守护线程中运行。通过扫描 requirements.txt、package.json、setup.py 和 pyproject.toml 发现包。将每个包送入沙箱管道。通过 get_status() 暴露状态，通过 Queue 暴露结果。通过 /tmp/tracetree_sessions/ 下的锁文件进行会话锁定。

mascot/spider.py — SpiderMascot 类。ASCII 蜘蛛，有 5 种状态（idle、success、warning、scanning、confused）。在 CLI 中用于分析期间的视觉反馈。

hooks/ — Shell 钩子系统。shell_hook.sh 包装 git 命令以拦截 git clone 并在后台启动 cascade-watch。install_hook.py 是一个跨平台安装程序，检测 bash/zsh 并将 source 行追加到适当的 RC 文件。

cli.py — Typer CLI 入口点。注册所有子命令。使用 Rich 进度条和格式化输出面板编排分析管道。

局限性与盲点

• ML 模型可靠性 — 训练好的 RandomForest 模型仅与其训练数据一样好。当前模型在少量包上训练。为了实现可靠检测，请使用大型标记数据集运行 cascade-train。IsolationForest 回退方案是基于启发式的基线，并非生产级模型。
• 网络沙箱排除 — 默认情况下，沙箱在运行/安装包之前禁用网络访问（ip link set eth0 down），以防止扫描期间主动数据外泄。虽然安全，但这意味着需要在安装期间进行网络握手或 C2 连接的恶意软件可能不会执行其载荷，或者某些需要互联网连接的正规安装程序会失败。要绕过此限制，请传递 --controlled-network 选项以启用受控/接收池网络模式。
• 容器和 strace 规避 — 高级恶意软件可以检测到它运行在 Docker 容器内（通过检查 cgroups、文件系统线索等），或检测到其进程受到 strace/ptrace 监控（通过调用 ptrace(PTRACE_TRACEME, ...) 或检查 /proc/self/status 中的 TracerPid）。如果触发规避，恶意软件可能提前终止或仅执行良性操作，从而逃避检测。
• strace 需要 Linux — 沙箱在 Docker 内的 Linux 上运行。在 macOS 和 Windows 上，Docker 运行一个 Linux VM，这是可行的，但本机 macOS 或 Windows 系统调用无法被追踪。DMG 脚本和 EXE 二进制文件在 Linux 环境中执行，这限制了其行为保真度。
• wine64 EXE 分析是尽力而为 — Wine 将 Windows 系统调用转换为 Linux 系统调用。某些特定于 Windows 的行为（注册表访问、COM 对象、Windows API 调用）可能不会产生可见的 Linux 级别系统调用。等待用户输入的 GUI 应用程序将在 30 秒后超时。
• DMG 分析有限 — DMG 文件使用 7z 解压，这可能在加密或非常规格式上失败。提取的脚本在 Linux 容器中运行，因此特定于 macOS 的行为（launchd、Keychain 等）不会执行。
• API 实现 — api/main.py 已连接到后台任务中运行实际的 TraceTree 分析管道。它使用内存数据库（mock_db）进行作业跟踪，并且需要设置 环境变量才能启动。

贡献

欢迎提交 Pull Request。请确保新功能与现有模块解耦。

许可证

MIT