tejasprasad2008-afk/TraceTree

# TraceTree   对 Python 包、npm 模块、DMG 镜像和 Windows EXE 文件进行运行时行为分析。在沙箱化的 Docker 容器中执行目标程序，使用 strace 跟踪系统调用，并通过 ML 异常检测、基于规则的签名匹配和时间模式分析对行为进行分类。 ## 工作原理 ``` 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 维特征向量。若存在已训练模型则使用随机森林分类器，否则回退到基于 10 个硬编码干净包基线的孤立森林。严重性分数和时间模式计数会提升最终置信度。 ## 检测内容 ### 行为签名（8 种模式） 定义在 `data/signatures.json` 中。每种签名包含严重性（1–10）、所需系统调用、文件模式、网络条件以及有序匹配序列。 | 签名 | 严重性 | 检测内容 | |---|---|---| | `reverse_shell` | 10 | 外部连接 → dup2 → execve /bin/sh | | `container_escape` | 10 | 打开 /proc/1/、/sys/fs/cgroup、/var/run/docker.sock | | `credential_theft` | 9 | 打开 /etc/shadow、.ssh/、.aws/ → 外部连接 | | `typosquat_exfil` | 9 | 读取敏感文件（.env、.npmrc）→ 连接到 pastebin/file.io/transfer.sh | | `process_injection` | 9 | mprotect 设置 PROT_EXEC → execve 非常规二进制文件 | | `crypto_miner` | 8 | clone → clone → 连接到矿池端口（3333、4444、14444、45700） | | `dns_tunneling` | 7 | getaddrinfo + sendto + 53/5353 端口上的 socket | | `persistence_cron` | 7 | 打开 crontab 路径 → 写入 | ### 时间模式（5 种） 从带时间戳的 strace 输出中检测。启用 strace 的 `-t` 标志（默认开启）。 | 模式 | 严重性 | 触发条件 | |---|---|---| | `connect_then_shell` | 10 | 外部连接 → 3 秒内 execve /bin/sh | | `credential_scan_then_exfil` | 9 | 读取敏感文件 → 5 秒内外部连接 | | `delayed_payload` | 8 | >10 秒空窗后出现突发可疑活动（投放器行为） | | `rapid_file_enumeration` | 7 | 1 秒内打开 10+ 个文件（扫描行为） | | `burst_process_spawn` | 7 | 2 秒内 5+ 次 clone/execve | ### 严重性加权系统调用评分 每种系统调用类型具有基础严重性权重。示例： - `mprotect` 且 `PROT_EXEC`：9.0 - 连接后 `dup2`：9.0 - 执非常规二进制文件的 `execve`：7.0 - 连接到云元数据（169.254.x.x）：8.0 - 连接到 PyPI/npm CDN：0.0（良性） - 打开 `/usr/lib/python/*`：0.0（良性） 总严重性分数用于 ML 置信度计算。 ### 网络目标分类 每个 `connect` 系统调用被分类为以下四类之一： | 类别 | 条件 | 风险分数 | |---|---|---| | `safe_registry` | IP 匹配已知的 PyPI/npm/GitHub CDN 范围 | 0.0 | | `known_benign` | 标准 Web 端口（80/443）连接到未识别主机 | 0.5 | | `suspicious` | 云元数据（169.254.x.x）、容器内私有 IP 或可疑端口（4444、1337、31337 等） | 8.0–9.0 | | `unknown` | 默认 | 3.0 | ## 支持的目标类型 | 目标类型 | 工作方式 | 说明 | |---|---|---| | **PyPI 包** | `pip download`（带网络），然后在无网络环境下执行 `pip install --no-index` | 最可靠。在执行前关闭网络。 | | **npm 包** | 在沙箱中执行 `npm install`，网络在 dry-run 后关闭 | 需要沙箱镜像中包含 Node.js。 | | **DMG 文件** | 使用 `7z` 在容器内解压。执行找到的脚本（.sh、.py、.command）、.pkg 安装包、.app 包以及裸 Mach-O 二进制文件。 | 需要沙箱镜像中包含 p7zip-full。DMG 解压可能因加密或不常见格式失败。脚本在 Linux 容器中运行，因此不会执行 macOS 特定行为。 | | **EXE 文件** | 使用 `wine64` 在沙箱中运行，并附带 `strace -t -f` 和 30 秒超时。Wine 初始化噪声会从 strace 日志中过滤。 | 需要沙箱镜像中包含 wine64。等待用户输入的 GUI 应用会在 30 秒后超时。Wine 层意味着系统调用是 Linux 系统调用，而非原生 Windows —— 部分 Windows 特定行为可能不可见。 | ## 快速开始 ### 先决条件 - Python 3.9+ - Docker（必须正在运行） ### 安装 ``` git clone https://github.com/tejasprasad2008-afk/TraceTree.git cd TraceTree pip install -e . ``` ### 运行分析 ``` cascade-analyze requests ``` 输出： ``` ┌──────────────────────────────────────┐ │ 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 ` 分析单个包、二进制文件或批量文件。 ``` # 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`** — 分析 Model Context Protocol 服务器的安全性（参见下方 MCP 章节）。 **子命令 `cascade-analyze watch `** — 会话守护者（参见会话守护者章节）。 **子命令 `cascade-analyze check `** — 快速按需扫描。 ### `cascade-watch ` 独立的会话守护者。监视目录中的包清单并后台运行沙箱分析。 ``` 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 ` 快速一次性分析特定文件。启动一个新的沙箱运行并返回判断结果。 <_BLOCK_7/> ### `cascade-install-hook` 安装一个 Shell 钩子，在每次 `git clone` 后自动运行 `cascade-watch`。 ``` cascade-install-hook ``` 该命令会在 `~/.bashrc` 或 `~/.zshrc` 中追加一行 source。钩子脚本位于 `~/.local/share/tracetree/hooks/shell_hook.sh`。安装后，每次 `git clone` 都会启动一个后台监视器并记录到 `/tmp/tracetree_.log`。 ### `cascade-train` 交互式训练管道。提示输入 MalwareBazaar API 密钥（可选 —— 可跳过仅使用本地数据集训练），然后： 1. 从 MalwareBazaar 摄入样本（如果提供了密钥） 2. 对每个样本运行沙箱管道 3. 在提取的特征上训练随机森林分类器 4. 保存到 `ml/model.pkl` 5. 尝试上传到 Google Cloud Storage（需要已认证的 `google-cloud-storage`） ``` export MALWAREBAZAAR_AUTH_KEY="your-key" cascade-train ``` ### `cascade-update` 从 Google Cloud Storage（`cascade-analyzer-models` 存储桶，匿名访问）下载最新的预训练模型。如果下载失败，则回退到孤立森林基线。 ``` cascade-update ``` ## MCP 服务器安全分析 `cascade-analyze mcp` 子命令用于分析模型上下文协议（MCP）服务器的恶意行为。它在沙箱容器中运行服务器，充当模拟的 MCP 客户端以发现并调用每个工具，然后分类生成的系统调用跟踪。 ``` # 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`、``）。 4. **特征提取** — MCP 特定特征：每个工具的网络连接、Shell 调用、敏感文件读取以及在对抗输入下的行为变化。 5. **威胁分类** — 基于规则的分类器，包含 6 类威胁： | 威胁 | 严重性 | 描述 | |---|---|---| | `COMMAND_INJECTION` | Critical | 工具参数触发 Shell 启动 | | `CREDENTIAL_EXFILTRATION` | Critical | 读取密钥后建立网络连接 | | `COVERT_NETWORK_CALL` | High | 工具调用期间连接到意外目标 | | `PATH_TRAVERSAL` | High | 读取工作目录之外的文件 | | `EXCESSIVE_PROCESS_SPAWNING` | Medium | 子进程数量异常 | | `PROMPT_INJECTION_VECTOR` | High | 工具描述包含零宽字符或注入语言 | 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`）。支持 PyPI、npm、DMG 和 EXE 目标。返回 strace 日志路径或失败时返回空字符串。 **`monitor/parser.py`** — 基于正则表达式的 strace 日志解析器。处理多行系统调用条目、`[pid]` 和裸 PID 格式，以及带时间戳（`-t`）的输出。跟踪 24 种系统调用类型，跨 5 个类别（进程、网络、文件、内存、IPC）。为每个事件分配严重性权重，分类网络目标并标记敏感文件访问。返回包含时间戳和相对毫秒偏移的结构化事件数据。 **`monitor/signatures.py`** — 行为签名匹配器。从 `data/signatures.json` 加载 8 种模式。支持无序匹配（必需系统调用 + 文件/网络模式必须存在）和有序序列匹配（系统调用-条件对必须按顺序出现）。返回匹配的签名及触发它们的特定事件证据。 **`monitor/timeline.py`** — 时间模式分析器。从有序且带时间戳的事件流中检测 5 种基于时间的行为模式。每种模式指定严重性、时间窗口和触发条件。仅在 strace 使用 `-t` 标志（默认启用）时有效。返回按严重性降序排列的匹配结果。 **`graph/builder.py`** — NetworkX 有向图构建。创建进程、文件和网络目标节点。添加克隆关系、系统调用目标和时间关系（同一 PID 事件在 5 秒内连续发生）。节点和边标记有签名匹配和严重性权重。输出 Cytoscape 兼容的 JSON 及内部统计信息。 **`ml/detector.py`** — 异常检测。提取 10 维特征向量（节点数、边数、网络连接、文件读取、execve 数量、总严重性、可疑网络、敏感文件、最大严重性、时间模式数量）。若本地存在已训练模型则使用随机森林分类器，否则回退到基于 10 个硬编码干净包基线的孤立森林。严重性分数和时间模式计数独立于 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 并在适当的 RC 文件中追加 source 行。 **`cli.py`** — Typer CLI 入口点。注册所有子命令。使用 Rich 进度条和格式化输出面板协调分析管道。 ## 限制 - **ML 模型可靠性** — 训练好的随机森林模型质量取决于训练数据。当前模型使用小规模包集合训练。要获得可靠检测，请使用大数据集运行 `cascade-train`。孤立森林回退是启发式基线，并非生产级模型。 - **strace 需要 Linux** — 沙箱在 Docker 中运行于 Linux。在 macOS 和 Windows 上，Docker 运行 Linux 虚拟机，这可以工作，但无法跟踪原生 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` 未连接到真实管道，返回硬编码数据。 - **会话守护者不克隆仓库 — `cascade-watch` 接受 URL 参数但不执行 `git clone`。它监视本地目录或回退到当前工作目录。 ## 贡献 欢迎提交 Pull Request。请保持新功能与现有模块解耦。 ## 许可证 MIT

标签：Apex, DMG分析, Docker沙箱, NetworkX, npm分析, Python分析, SEO：供应链攻击检测, SEO：沙箱分析工具, SEO：运行时行为分析, strace, Windows可执行文件分析, 可视化界面, 孤立森林, 安装时扫描, 异常检测, 时序模式分析, 有向图, 机器学习, 沙箱分析, 特权检测, 突变策略, 系统调用追踪, 网络隔离, 规则匹配, 请求拦截, 运行时行为分析, 进程树, 逆向工具, 随机森林, 隐蔽攻击发现