TraceTree

TraceTree Demo

TraceTree(cascade-analyzer)는 에이전트 시대를 위해 설계된 자율 보안 유기체입니다. 단순한 스캐닝을 넘어 견고하고 강화된 확장형 탐지 생태계로 발전합니다. 마스코트인 거미처럼, TraceTree는 여덟 개의 특화된 "다리"를 사용하여 개발 워크플로우 주변에 포괄적인 보호망을 엮습니다.

목차

• 저장소 구조
• 행동 영수증 내보내기
• TraceTree 거미의 8개 다리
• 작동 방식
• 탐지 대상
  • 행동 시그니처
  • 시간적 패턴
• 지원 대상
• 빠른 시작(설치로 건너뛰기)
  • 전제 조건
  • 설치
  • 분석 실행
• 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개의 다리

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-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] 및 bare-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 (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 시스템 호출은 네 가지 범주 중 하나로 분류됩니다.

지원 대상

빠른 시작

사전 요구 사항

• 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`

모든 `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 클라이언트 역할을 하여 모든 도구를 발견하고 호출한 다음, 결과 syscall trace를 분류합니다.```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 컨테이너 수명주기 관리. 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가지 시간 기반 동작 패턴을 감지합니다. 각 패턴은 심각도, 시간 창, 트리거 조건을 지정합니다. 심각도 내림차순으로 정렬된 매치를 반환합니다. strace가 -t(기본값)로 실행된 경우에만 활성화됩니다.

graph/builder.py — NetworkX 방향 그래프 구성. 프로세스, 파일, 네트워크 대상에 대한 노드를 생성합니다. 복제 관계, 시스템 호출 대상, 시간 관계(5초 이내의 연속된 동일 PID 이벤트)에 대한 엣지를 추가합니다. 노드와 엣지는 시그니처 매치 및 심각도 가중치로 태그가 지정됩니다. Cytoscape 호환 JSON 및 내부 통계를 출력합니다.

ml/detector.py — 이상 탐지. 10가지 특징 벡터(노드 수, 엣지 수, 네트워크 연결, 파일 읽기, execve 수, 총 심각도, 의심스러운 네트워크, 민감한 파일, 최대 심각도, 시간 패턴 수)를 추출합니다. 학습된 모델이 로컬에 있거나 GCS에서 다운로드 가능한 경우 RandomForestClassifier를 사용하고, 그렇지 않으면 10개의 하드코딩된 클린 패키지 기준선으로 학습된 IsolationForest로 대체합니다. 심각도 점수와 시간 패턴 수는 ML 예측과 별도로 최종 신뢰도를 높입니다.

mcp/ — MCP 서버 분석 모듈. 6개 파일: 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 클래스. 5가지 상태(idle, success, warning, scanning, confused)를 가진 ASCII 거미. 분석 중 시각적 피드백을 위해 CLI에서 사용됩니다.

hooks/ — 셸 훅 시스템. shell_hook.sh는 git 명령을 래핑하여 git clone을 가로채고 백그라운드에서 cascade-watch를 시작합니다. install_hook.py는 크로스 플랫폼 설치 프로그램으로, bash/zsh를 감지하고 적절한 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 구현 — 는 실제 TraceTree 분석 파이프라인을 백그라운드 작업 내에서 실행하도록 연결되어 있습니다. 작업 추적을 위해 인메모리 데이터베이스()를 사용하며, 시작하려면 환경 변수가 설정되어야 합니다.

기여하기

풀 리퀘스트를 환영합니다. 새로운 기능은 기존 모듈과 분리된 상태로 유지해 주세요.

License

MIT