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: كشف الشذوذ بالتعلم الآلي (الحدس)** — نموذج غابة عشوائية (Random Forest) مُدرَّب خصيصًا (مُدرَّب على مجموعة بيانات صغيرة وممثلة من الحزم النظيفة/الخبيثة، بالإضافة إلى خلاصات MalwareBazaar الحية الاختيارية) يتنبأ بالنوايا الخبيثة بثقة عالية.
5.  **الرجل 5: مطابقة توقيعات YARA (الذاكرة)** — مكتبة مدمجة من الحمض النووي للبرامج الضارة المعروفة وأنماط الاستغلال (الصدف العكسية، عمال تعدين العملات الرقمية، إلخ).
6.  **الرجل 6: بروتوكول أمان MCP (درع الوكيل)** — حماية متخصصة لخوادم بروتوكول سياق النموذج (Model Context Protocol)، للدفاع عن الأدوات التي يستخدمها وكلاء الذكاء الاصطناعي.
7.  **الرجل 7: الذكاء الاصطناعي الحارس الأمني (الشبكة الاستباقية)** — "ماسح ذكي" قبل الالتزام (pre-commit) يستخدم نماذج 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. Sandbox — الهدف يعمل داخل حاوية Docker. يتم قطع الشبكة (ip link set eth0 down) قبل بدء التثبيت/التنفيذ، لذا يتم تسجيل أي محاولات اتصال خارجية ولكن يتم حظرها.
2. strace — يتم تتبع كل استدعاء نظام باستخدام strace -t -f -e trace=all. يضيف -t طوابع زمنية للتحليل الزمني، و-f يتابع العمليات الفرعية.
3. Parser (monitor/parser.py) — محلل يعتمد على التعبيرات النمطية (Regex) يتعامل مع مخرجات strace متعددة الأسطر وتنسيقات [pid] و bare-pid. يستخرج إنشاء العملية، الوصول إلى الملفات، اتصالات الشبكة، وعمليات الذاكرة. يُخصص لكل استدعاء نظام وزن خطورة (0–9) بناءً على صلته بالأمان.
4. مطابقة التوقيعات (monitor/signatures.py) — يطابق تدفق الأحداث المحلل مقابل 8 أنماط توقيع سلوكي معرفة في data/signatures.json. كل مطابقة تنتج أدلة تسرد الأحداث المحددة التي أدت إلى ذلك.
5. التحليل الزمني (monitor/timeline.py) — يكتشف 5 أنماط سلوكية مبنية على الوقت من تدفق الأحداث المطعم بالطوابع الزمنية (مثل: قراءة بيانات الاعتماد متبوعة باتصال خارجي خلال 5 ثوانٍ).
6. الرسم البياني (graph/builder.py) — يبني رسمًا بيانيًا موجهًا باستخدام NetworkX مع عُقد للعمليات والملفات والشبكة. يضيف حوافًا زمنية بين أحداث متتالية لنفس PID ضمن نافذة 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%

للحزمة الضارة (على سبيل المثال، typosquat معروف):```
 ┌─ 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

مرجع واجهة سطر الأوامر

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>`** — حارس الجلسة (انظر قسم Session Guardian).

**الأمر الفرعي: `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 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

يقوم الأمر الفرعي `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. الصندوق الرملي (Sandbox) — يعمل الخادم في Docker مع تعطيل الشبكة افتراضيًا. يتم تتبعه باستخدام strace -f.
2. محاكاة العميل — مصافحة تهيئة JSON-RPC 2.0 initialize، اكتشاف tools/list، استدعاء آمن لكل أداة مع وسائط اصطناعية. 3 الاختبارات الخصومية — يتم إعادة استدعاء كل أداة بحمولات حقن (; ls /etc، ../../../etc/passwd، <script>alert(1)</script>).
3. استخراج الميزات — ميزات خاصة بـ MCP: اتصالات الشبكة لكل أداة، استدعاءات الصدفة، قراءة الملفات الحساسة، تغيرات السلوك تحت الإدخال الخصومي.
4. تصنيف التهديدات — مصنف قائم على القواعد مع 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). يُستخدم في واجهة سطر الأوامر للتغذية الراجعة البصرية أثناء التحليل.

hooks/ — نظام ربط الصدفة. shell_hook.sh يلف أمر git لاعتراض git clone وبدء cascade-watch في الخلفية. install_hook.py هو مثبت عبر المنصات يكتشف bash/zsh ويضيف سطر المصدر إلى ملف RC المناسب.

cli.py — نقطة دخول Typer CLI. يسجل جميع الأوامر الفرعية. ينظم خط أنابيب التحليل مع أشرطة تقدم Rich وألواح إخراج منسقة.

القيود والنقاط العمياء

• موثوقية نموذج التعلم الآلي — نموذج 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 requests). يرجى الحفاظ على فصل الميزات الجديدة عن الوحدات الموجودة.

الترخيص

MIT