TraceTree

Demonstração TraceTree

TraceTree (cascade-analyzer) é um organismo de segurança autônomo projetado para a era agentiva. Ele vai além da simples verificação, tornando-se um ecossistema de detecção robusto, endurecido e escalável. Como seu mascote, a aranha, o TraceTree tece uma teia abrangente de proteção ao redor do seu fluxo de trabalho de desenvolvimento, usando suas oito 'pernas' especializadas.

Tabela de Conteúdos

• Estrutura do Repositório
• Exportação de recibo de comportamento
• As 8 Pernas da Aranha TraceTree
• Como Funciona
• O Que Detecta
  • Assinaturas Comportamentais
  • Padrões Temporais
• Alvos Suportados
• Início Rápido (Pule para a Instalação)
  • Pré-requisitos
  • Instalação
  • Executar uma Análise
• Referência da CLI
• Análise de Segurança do Servidor MCP
• Visão Geral da Arquitetura
• Limitações e Pontos Cegos

Exportação de recibo de comportamento

TraceTree pode ser usado como uma porta de revisão antes que agentes ou humanos confiem na instalação de um pacote. Veja Exportação de recibo de comportamento para um formato de recibo pequeno e compatível com JSON/SARIF que resume hash do alvo, política de sandbox, comportamento observado, hashes de artefatos, veredito e padrões de privacidade sem expor logs brutos de chamadas de sistema.

Estrutura do Repositório```

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

## As 8 Pernas da Aranha TraceTree

1.  **Perna 1: Isolamento em Sandbox (A Armadilha)** — Executa alvos em contêineres Docker isolados (ou um modo `direct` de alto desempenho) onde as ameaças são fisicamente contidas.
2.  **Perna 2: Análise de Syscalls (O Sistema Nervoso)** — Um motor de alta precisão que monitora cada "vibração" (chamada de sistema) que um processo faz ao SO.
3.  **Perna 3: Gráfico Comportamental (A Teia)** — Mapeia a "Cascata" de como processos, arquivos e nós de rede interagem usando grafos direcionados do NetworkX.
4.  **Perna 4: Detecção de Anomalias por ML (A Intuição)** — Um modelo Random Forest treinado sob medida (treinado em um pequeno conjunto de dados representativo de pacotes limpos/maliciosos, mais feeds opcionais ao vivo do MalwareBazaar) que prevê intenção maliciosa com alta confiança.
5.  **Perna 5: Correspondência de Assinaturas YARA (A Memória)** — Uma biblioteca integrada de DNA de malware conhecido e padrões de exploração (Reverse Shells, Cryptominers, etc.).
6.  **Perna 6: Protocolo de Segurança MCP (O Escudo do Agente)** — Proteção especializada para servidores do Model Context Protocol, defendendo as ferramentas que os agentes de IA usam.
7.  **Perna 7: AI Guardiã de Segurança (A Teia Proativa)** — Um "Smart Scanner" pré-commit usando LLMs locais (Qwen-Coder) para capturar vazamentos e injeções antes que cheguem ao seu histórico.
8.  **Perna 8: Análise Temporal e de N-gramas (A Varredura de DNA)** — Identifica ameaças pelo *ritmo* e *sequência* de suas ações ao longo do tempo.

## Como Funciona```
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 — O alvo é executado dentro de um contêiner Docker. A rede é desativada (ip link set eth0 down) antes do início da instalação/execução, portanto, quaisquer tentativas de conexão de saída são registadas, mas bloqueadas.
2. strace — Cada syscall é rastreada com strace -t -f -e trace=all. A flag -t adiciona carimbos de data/hora para análise temporal, -f segue os processos filhos.
3. Parser (monitor/parser.py) — Parser baseado em regex que processa saída strace multilinha e ambos os formatos [pid] e pid simples. Extrai criação de processos, acesso a arquivos, conexões de rede e operações de memória. Cada syscall recebe um peso de gravidade (0–9) com base na sua relevância de segurança.
4. Correspondência de assinaturas (monitor/signatures.py) — Compara o fluxo de eventos analisado com 8 padrões de assinatura comportamental definidos em data/signatures.json. Cada correspondência produz evidências listando os eventos específicos que a desencadearam.
5. Análise temporal (monitor/timeline.py) — Detecta 5 padrões comportamentais baseados no tempo a partir do fluxo de eventos com carimbo de data/hora (ex.: leitura de credencial seguida de conexão externa em 5 segundos).

O Que Detecta

Assinaturas Comportamentais (8 padrões)

Definidas em data/signatures.json. Cada uma tem uma gravidade (1–10), syscalls necessárias, padrões de arquivo, condições de rede e uma sequência ordenada para correspondência.

Padrões Temporais (5 padrões)

Detectados a partir da saída do strace com carimbo de data/hora. Requer a flag -t do strace (ativada por padrão).

Pontuação de Syscall com Peso de Gravidade

Cada um dos 24 tipos de syscall tem um peso de gravidade base. Exemplos:

• mprotect com PROT_EXEC: 9.0
• dup2 após um connect: 9.0
• execve de binário inesperado: 7.0
• connect para metadados de nuvem (169.254.x.x): 8.0
• connect para PyPI/npm CDN: 0.0 (benigno)
• openat de /usr/lib/python/*: 0.0 (benigno)

A pontuação total de gravidade alimenta o cálculo de confiança do ML.

Classificação de Destino de Rede

Cada syscall connect é classificada em uma de quatro categorias:

Alvos Suportados

Início Rápido

Pré-requisitos

• Python 3.9+
• Docker (deve estar em execução)

Instalar```bash

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

### Executar uma Análise```bash
cascade-analyze --help

Saída:``` ┌──────────────────────────────────────┐ │ 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%

Para um pacote malicioso (por exemplo, um typosquat conhecido):```
 ┌─ 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

Referência da CLI

cascade-analyze <target>

Analisar um único pacote, binário ou arquivo em massa.```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`** — Análise de segurança do servidor MCP (veja a seção MCP abaixo).

**Subcommand: `cascade-analyze watch <repo>`** — Guardião de sessão (veja a seção Session Guardian).

**Subcommand: `cascade-analyze check <file>`** — Varredura rápida sob demanda.

### `cascade-watch <repo>`

Guardião de sessão independente. Monitora um diretório em busca de manifestos de pacotes e executa análise de sandbox em segundo plano.```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

Exibe um mascote de aranha no terminal e verifica o status em um loop. Pressione Ctrl+C para parar. Apenas um observador por diretório é permitido (arquivo de bloqueio em /tmp/tracetree_sessions/).

cascade-check <file>

Análise única rápida de um arquivo específico. Inicia uma nova execução em sandbox e retorna um veredito.```bash cascade-check setup.py cascade-check ./payload.exe

### `cascade-install-hook`

Instala um hook de shell que executa `cascade-watch` automaticamente após cada `git clone`.```bash
cascade-install-hook

Isso adiciona uma linha source ao ~/.bashrc ou ~/.zshrc. O script de hook está localizado em ~/.local/share/tracetree/hooks/shell_hook.sh. Após a instalação, cada git clone iniciará um observador em segundo plano e registrará em /tmp/tracetree_<reponame>.log.

cascade-train

Pipeline de treinamento interativo. Solicita uma chave de API do MalwareBazaar (opcional — pode ser ignorada para treinar apenas com conjuntos de dados locais), em seguida:

1. Ingere amostras do MalwareBazaar (se a chave for fornecida)
2. Executa cada uma através do pipeline de sandbox
3. Treina um RandomForestClassifier nas características extraídas
4. Salva em ml/model.skops e invalida o cache```bash export MALWAREBAZAAR_AUTH_KEY="your-key" cascade-train

## Análise de Segurança do Servidor MCP

O subcomando `cascade-analyze mcp` analisa servidores do Protocolo de Contexto de Modelo (MCP) em busca de comportamentos maliciosos. Ele executa o servidor em um container isolado (sandbox), age como um cliente MCP simulado para descobrir e invocar todas as ferramentas, e então classifica o rastreamento de chamadas de sistema (syscall) resultante.```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

O que a análise MCP faz

1. Sandbox — O servidor é executado em Docker com rede bloqueada por padrão. Rastreado com strace -f.
2. Simulação de cliente — Handshake initialize JSON-RPC 2.0, descoberta tools/list, invocação segura de cada ferramenta com argumentos sintéticos.
3. Sondas adversariais — Cada ferramenta é reinvocada com payloads de injeção (; ls /etc, ../../../etc/passwd, <script>alert(1)</script>).
4. Extração de características — Características específicas do MCP: conexões de rede por ferramenta, invocações de shell, leituras de arquivos sensíveis, mudanças de comportamento sob entrada adversarial.
5. Classificação de ameaças — Classificador baseado em regras com 6 categorias:

6. Comparação de linha de base — Compara perfis de syscall com linhas de base fixas para 5 tipos de servidor: filesystem, github, postgres, fetch, shell.

Arquitetura

sandbox/ — Gerenciamento do ciclo de vida de contêineres Docker. Constrói cascade-sandbox:latest a partir de um Dockerfile baseado em python:3.11-slim com strace, wine64, p7zip-full, cabextract, Node.js e npm. Desativa a interface de rede (ip link set eth0 down) antes da execução do alvo. Suporta alvos pip, npm, DMG e EXE. Retorna um caminho de log strace ou string vazia em caso de falha.

monitor/parser.py — Analisador de log strace baseado em regex. Lida com entradas de syscall de várias linhas, formatos [pid] e pid simples, e saída com timestamp (-t). Rastreia 24 tipos de syscall em 5 categorias (processo, rede, arquivo, memória, IPC). Atribui pesos de severidade por evento, classifica destinos de rede e sinaliza acessos a arquivos sensíveis. Retorna dados de evento estruturados com timestamps e deslocamentos relativos em milissegundos.

monitor/signatures.py — Correspondente de assinaturas comportamentais. Carrega 8 padrões de data/signatures.json. Suporta correspondência não ordenada (syscalls necessários + padrões de arquivo/rede devem estar presentes) e correspondência de sequência ordenada (pares de syscall-condição devem aparecer em ordem). Retorna assinaturas correspondentes com evidências listando os eventos específicos que dispararam cada correspondência.

monitor/timeline.py — Analisador de padrões temporais. Detecta 5 padrões comportamentais baseados em tempo a partir do fluxo de eventos ordenado e com timestamp. Cada padrão especifica uma severidade, uma janela de tempo e as condições de disparo. Retorna correspondências ordenadas por severidade decrescente. Ativo apenas quando strace foi executado com -t (que é o padrão).

graph/builder.py — Construção de grafo direcionado NetworkX. Cria nós para processos, arquivos e destinos de rede. Adiciona arestas para relacionamentos de clone, alvos de syscall e relacionamentos temporais (eventos consecutivos do mesmo PID dentro de 5 segundos). Nós e arestas são marcados com correspondências de assinaturas e pesos de severidade. Produz JSON compatível com Cytoscape e estatísticas internas.

ml/detector.py — Detecção de anomalias. Extrai um vetor de 10 características (contagem de nós, contagem de arestas, conexões de rede, leituras de arquivos, contagem de execve, severidade total, redes suspeitas, arquivos sensíveis, severidade máxima, contagem de padrões temporais). Usa RandomForestClassifier se um modelo treinado estiver disponível localmente ou puder ser baixado do GCS; recorre a IsolationForest treinado em 10 linhas de base de pacotes limpos fixos. Pontuações de severidade e contagens de padrões temporais aumentam a confiança final independentemente da previsão do ML.

mcp/ — Módulo de análise de servidores MCP. Seis arquivos: sandbox.py (sandbox Docker para servidores MCP), client.py (cliente JSON-RPC 2.0 com descoberta de ferramentas e sondas adversariais), features.py (extração de características específicas do MCP com detecção de tipo de servidor), classifier.py (classificação de ameaças baseada em regras), report.py (geração de relatório Rich console + JSON).

watcher/session.py — Guardião de sessão. A classe SessionWatcher é executada em uma thread daemon em segundo plano. Descobre pacotes escaneando por requirements.txt, package.json, setup.py e pyproject.toml. Executa cada um através do pipeline da sandbox. Expõe status via get_status() e resultados via uma Queue. Bloqueio de sessão via arquivo de bloqueio em /tmp/tracetree_sessions/.

mascot/spider.py — Classe SpiderMascot. Aranha ASCII com 5 estados (idle, success, warning, scanning, confused). Usada na CLI para feedback visual durante a análise.

hooks/ — Sistema de hook de shell. shell_hook.sh envolve o comando git para interceptar git clone e iniciar cascade-watch em segundo plano. install_hook.py é um instalador multiplataforma que detecta bash/zsh e anexa a linha de source ao arquivo RC apropriado.

cli.py — Ponto de entrada da CLI Typer. Registra todos os subcomandos. Orquestra o pipeline de análise com barras de progresso Rich e painéis de saída formatados.

Limitações e Pontos Cegos

• Confiabilidade do modelo ML — O modelo RandomForest treinado é tão bom quanto seus dados de treinamento. O modelo atual foi treinado em um pequeno conjunto de pacotes. Para detecção confiável, execute cascade-train com um grande conjunto de dados rotulados. O fallback IsolationForest é uma linha de base heurística, não um modelo de qualidade de produção.
• Exclusão de sandbox de rede — Por padrão, a sandbox desabilita o acesso à rede (ip link set eth0 down) antes de executar/instalar o pacote para evitar exfiltração ativa de dados durante a varredura. Embora seguro, isso significa que malware que requer handshakes de rede ou conexões C2 durante a instalação pode não executar seu payload, ou alguns instaladores legítimos que exigem conectividade com a internet falharão. Para contornar isso, passe a opção --controlled-network para habilitar o modo de rede controlada/ sinkhole.
• Evasão de contêiner e strace — Malware avançado pode detectar que está sendo executado dentro de um contêiner Docker (verificando cgroups, pistas do sistema de arquivos, etc.) ou detectar que seus processos estão sob monitoramento strace/ptrace (chamando ptrace(PTRACE_TRACEME, ...) ou verificando TracerPid em /proc/self/status). Se a evasão for acionada, o malware pode encerrar precocemente ou executar apenas ações benignas, escapando da detecção.
• strace requer Linux — A sandbox é executada no Linux dentro do Docker. No macOS e Windows, o Docker executa uma VM Linux, o que funciona, mas syscalls nativas do macOS ou Windows não podem ser rastreadas. Scripts DMG e binários EXE são executados em um ambiente Linux, o que limita sua fidelidade comportamental.

Contribuindo

Pull requests são bem-vindos. Por favor, mantenha novos recursos desacoplados dos módulos existentes.

Licença

MIT