TraceTree

Демонстрация TraceTree

TraceTree (cascade-analyzer) — это автономный организм безопасности, созданный для эпохи агентов. Он выходит за рамки простого сканирования, превращаясь в надежную, закаленную и масштабируемую экосистему обнаружения. Как и его маскот-паук, TraceTree сплетает комплексную паутину защиты вокруг вашего рабочего процесса разработки, используя свои восемь специализированных «ног».

Содержание

• Структура репозитория
• Экспорт квитанции поведения
• 8 ног паука 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

## 8 Лап Паука TraceTree

1.  **Лапа 1: Изоляция в песочнице (Ловушка)** — Выполняет цели в изолированных Docker-контейнерах (или в высокопроизводительном режиме `direct`), где угрозы физически сдерживаются.
2.  **Лапа 2: Разбор системных вызовов (Нервная система)** — Высокоточный движок, отслеживающий каждую «вибрацию» (системный вызов) процесса к ОС.
3.  **Лапа 3: Поведенческое графостроение (Паутина)** — Отображает «Каскад» взаимодействий процессов, файлов и сетевых узлов, используя направленные графы NetworkX.
4.  **Лапа 4: Обнаружение аномалий с помощью ML (Интуиция)** — Пользовательская модель Random Forest (обученная на небольшом репрезентативном наборе чистых/вредоносных пакетов, а также на опциональных живых фидах MalwareBazaar), предсказывающая вредоносные намерения с высокой точностью.
5.  **Лапа 5: Поиск по сигнатурам YARA (Память)** — Интегрированная библиотека известной ДНК вредоносных программ и шаблонов эксплойтов (реверс-шеллы, криптомайнеры и т.д.).
6.  **Лапа 6: Протокол безопасности MCP (Щит агента)** — Специализированная защита для серверов протокола Model Context, защищающая инструменты, используемые AI-агентами.
7.  **Лапа 7: Страж ИИ безопасности (Проактивная паутина)** — «Умный сканер» перед коммитом, использующий локальные LLM (Qwen-Coder) для перехвата утечек и инъекций до того, как они попадут в историю.
8.  **Лапа 8: Анализ временных рядов и N-грамм (Сканирование ДНК)** — Идентифицирует угрозы по *ритму* и *последовательности* их действий во времени.

## Как это работает```
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) — Цель выполняется внутри 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) — Сопоставляет поток событий с 8 шаблонами поведенческих сигнатур, определёнными в data/signatures.json. Каждое совпадение выдаёт доказательства, перечисляющие конкретные события, которые его вызвали.
5. Временной анализ (monitor/timeline.py) — Обнаруживает 5 временных поведенческих паттернов на основе потока событий с временными метками (например, чтение учётных данных с последующим внешним соединением в течение 5 секунд).

Что он обнаруживает

Поведенческие сигнатуры (8 паттернов)

Определены в data/signatures.json. Каждая имеет серьёзность (1–10), требуемые системные вызовы, файловые паттерны, сетевые условия и упорядоченную последовательность для сопоставления.

Временные паттерны (5 паттернов)

Обнаруживаются из вывода strace с временными метками. Требуется флаг -t у strace (включён по умолчанию).

Оценка системных вызовов с весовой серьёзностью

Каждый из 24 типов системных вызовов имеет базовый весовой коэффициент серьёзности. Примеры:

• mprotect с PROT_EXEC: 9.0
• dup2 после connect: 9.0
• execve неожиданного бинарника: 7.0
• connect к облачной метаданным (169.254.x.x): 8.0
• connect к CDN PyPI/npm: 0.0 (безвредный)
• openat из /usr/lib/python/*: 0.0 (безвредный)

Общий показатель серьёзности используется в расчёте уверенности МО.

Классификация сетевых назначений

Каждый системный вызов 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 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

**Subcommand: `cascade-analyze mcp`** — Анализ безопасности MCP-сервера (см. раздел MCP ниже).

**Subcommand: `cascade-analyze watch <repo>`** — Сессионный страж (см. раздел «Сессионный страж»).

**Subcommand: `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`

Устанавливает хук оболочки, который запускает `cascade-watch` автоматически после каждого `git clone`.```bash
cascade-install-hook

Это добавляет строку source в ~/.bashrc или ~/.zshrc. Скрипт-хук находится в ~/.local/share/tracetree/hooks/shell_hook.sh. После установки каждый git clone будет запускать фоновый наблюдатель и записывать логи в /tmp/tracetree_<reponame>.log.

cascade-train

Интерактивный пайплайн обучения. Запрашивает API-ключ MalwareBazaar (необязательно — можно пропустить для обучения только на локальных наборах данных), затем:

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

1. Песочница — Сервер запускается в Docker с заблокированной сетью по умолчанию. Отслеживается с помощью strace -f.
2. Симуляция клиента — JSON-RPC 2.0 рукопожатие initialize, обнаружение tools/list, безопасный вызов каждого инструмента с синтетическими аргументами.
3. Атакующие пробы — Каждый инструмент повторно вызывается с нагрузками внедрения (; ls /etc, ../../../etc/passwd, <script>alert(1)</script>).
4. Извлечение признаков — Специфичные для MCP признаки: сетевые соединения на инструмент, вызовы оболочки, чтение конфиденциальных файлов, изменения поведения при атакующем вводе.
5. Классификация угроз — Классификатор на основе правил с 6 категориями:

6. Сравнение с базовым уровнем — Сравнивает профили системных вызовов с жёстко заданными базовыми уровнями для 5 типов серверов: filesystem, github, postgres, fetch, shell.

Архитектура

sandbox/ — Управление жизненным циклом контейнеров Docker. Собирает образ cascade-sandbox:latest из Dockerfile на основе python:3.11-slim с 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). Отслеживает 24 типа системных вызовов в 5 категориях (процесс, сеть, файл, память, IPC). Назначает веса серьёзности для каждого события, классифицирует сетевые адресаты и помечает доступ к конфиденциальным файлам. Возвращает структурированные данные событий с временными метками и относительными смещениями в миллисекундах.

monitor/signatures.py — Сопоставитель сигнатур поведения. Загружает 8 шаблонов из data/signatures.json. Поддерживает как неупорядоченное сопоставление (требуемые системные вызовы + шаблоны файлов/сети должны присутствовать), так и упорядоченное последовательное сопоставление (пары системный вызов—условие должны появляться по порядку). Возвращает совпавшие сигнатуры с доказательствами, перечисляющими конкретные события, которые запустили каждое совпадение.

monitor/timeline.py — Анализатор временных шаблонов. Обнаруживает 5 поведенческих шаблонов на основе времени из упорядоченного потока событий с метками времени. Каждый шаблон задаёт серьёзность, временное окно и условия срабатывания. Возвращает совпадения, отсортированные по убыванию серьёзности. Активен только если strace был запущен с -t (что используется по умолчанию).

graph/builder.py — Построение ориентированного графа с помощью NetworkX. Создаёт узлы для процессов, файлов и сетевых адресатов. Добавляет рёбра для отношений клонирования, целей системных вызовов и временных отношений (последовательные события одного и того же PID в пределах 5 секунд). Узлы и рёбра помечаются совпадениями сигнатур и весами серьёзности. Выводит JSON, совместимый с Cytoscape, и внутреннюю статистику.

ml/detector.py — Обнаружение аномалий. Извлекает вектор из 10 признаков (количество узлов, количество рёбер, сетевые соединения, чтения файлов, количество execve, общая серьёзность, подозрительные сети, конфиденциальные файлы, максимальная серьёзность, количество временных шаблонов). Использует RandomForestClassifier, если обученная модель доступна локально или может быть загружена из GCS; в противном случае использует IsolationForest, обученный на 10 жёстко заданных базовых уровнях чистых пакетов. Оценки серьёзности и количество временных шаблонов повышают итоговую уверенность независимо от предсказания ML.

mcp/ — Модуль анализа серверов MCP. Шесть файлов: sandbox.py (песочница Docker для серверов MCP), 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_hook.sh оборачивает команду git для перехвата git clone и запуска cascade-watch в фоне. install_hook.py — кроссплатформенный установщик, который определяет bash/zsh и добавляет строку source в соответствующий RC-файл.

cli.py — Точка входа CLI на Typer. Регистрирует все подкоманды. Оркестрирует конвейер анализа с индикаторами прогресса Rich и форматированными панелями вывода.

Ограничения и слепые зоны

• Надёжность ML-модели — Обученная модель RandomForest настолько хороша, насколько хороши её обучающие данные. Текущая модель обучена на небольшом наборе пакетов. Для надёжного обнаружения запустите cascade-train с большим размеченным набором данных. IsolationForest как запасной вариант — это эвристический базовый уровень, а не промышленная модель.
• Исключение сетевой песочницы — По умолчанию песочница отключает сетевой доступ (ip link set eth0 down) перед запуском/установкой пакета, чтобы предотвратить активную утечку данных во время сканирования. Это безопасно, но означает, что вредоносное ПО, требующее сетевых рукопожатий или C2-соединений во время установки, может не выполнить свою нагрузку, или некоторые легитимные установщики, которым требуется подключение к интернету, не сработают. Чтобы обойти это, передайте опцию --controlled-network для включения контролируемого/сетевого режима с заменой адресата.
• Обход контейнера и strace — Продвинутое вредоносное ПО может определить, что оно работает внутри контейнера Docker (проверяя cgroups, подсказки файловой системы и т. д.) или обнаружить, что его процессы находятся под мониторингом strace/ptrace (вызовом ptrace(PTRACE_TRACEME, ...) или проверкой TracerPid в /proc/self/status). Если срабатывает обход, вредоносное ПО может завершиться досрочно или выполнить только безвредные действия, уклоняясь от обнаружения.
• strace требует Linux — Песочница работает на Linux внутри Docker. На macOS и Windows Docker запускает виртуальную машину Linux, что работает, но родные системные вызовы macOS или Windows не могут быть отслежены. DMG-скрипты и EXE-бинарные файлы выполняются в среде Linux, что ограничивает точность их поведения.

Участие в разработке

Pull-реквесты приветствуются. Пожалуйста, сохраняйте новые функции независимыми от существующих модулей.

Лицензия

MIT