Santamon

مكوّن جانبي خفيف لاكتشاف macOS لـ Santa يقيّم بيانات قياس أمان نقطة النهاية محليًا باستخدام قواعد CEL ويُرسل إشارات الكشف المطابقة فقط إلى خادم خلفي.

تجريبي. صُمم للمختبرات المنزلية والفرق الصغيرة. إصدار مبكر – توقع وجود أخطاء وتغييرات في الواجهة البرمجية.

ماذا يفعل

يقرأ Santamon تدفق قياسات protobuf الخاص بـ Santa، ويقيّم قواعد الكشف باستخدام تعبيرات CEL، ويُرسل الإشارات الأمنية إلى خادم خلفي. تبقى القياسات الأولية على نقطة النهاية—يتم إرسال عمليات الكشف فقط.

القدرات الأساسية:

• الكشف المحلي: قواعد قائمة على CEL تقيّم الأحداث على الجهاز
• ثلاثة أنواع من القواعد: المطابقة البسيطة، الارتباط عبر نافذة زمنية، خط الأساس (أول ظهور)
• سلالة العمليات: إرفاق شجرات العمليات الكاملة اختياريًا بإشارات التنفيذ
• حالة مدمجة: يتتبع BoltDB الارتباطات وبيانات أول ظهور وطابور الإشارات
• إرسال مرن: تجميع متزامن، منطق إعادة المحاولة، قاطع الدائرة

لماذا Santamon؟

Santamon هو مكوّن جانبي للكشف خاص بـ Santa، وليس عميل ESF آخر.

يتطلب بناء أداة ESF مخصصة صلاحيات Apple المقيدة وملفات التزويد والتعامل الدقيق مع أحداث أمان نقطة النهاية عالية الحجم. يقوم Santa بذلك بالفعل وقد خضع لاختبارات قاسية في الإنتاج.

قيمة Santamon:

• يعيد استخدام Santa كطبقة استشعار ESF (بدون صلاحيات إضافية)
• يشغّل القواعد محليًا بالقرب من البيانات، بدلاً من بث كل شيء
• حالة خفيفة عبر BoltDB للارتباطات وإزالة التكرار
• تكلفة بنية تحتية منخفضة - يُرسل فقط عمليات الكشف عالية الإشارة

يتولى Santa الجزء الأثقل من استهلاك أحداث أمان نقطة النهاية بشكل موثوق وآمن؛ بينما يركز Santamon على منطق الكشف وجودة الإشارات.

البنية

Santa Spool → Watcher → Decoder → Rules Engine → Signal Generator → Shipper → Backend
                 ↓                      ↓
                ┌────────────────────────┐
                │ State DB (BoltDB)      │
                │ • Correlation windows  │
                │ • Baseline tracking    │
                │ • Signal queue         │
                └────────────────────────┘
                Process lineage: in-memory cache (1h TTL, 50K max)

تدفق البيانات:

1. المراقب (Watcher) يراقب دليل طابور Santa (/var/db/santa/spool/new/) بحثًا عن ملفات protobuf جديدة
2. وحدة فك الترميز (Decoder) تقرأ رسائل protobuf من ملفات الطابور وتفك ضغطها
3. محرك القواعد (Rules Engine) يقيّم الأحداث مقابل تعبيرات CEL (قواعد بسيطة وارتباطية وأساس)
4. مولّد الإشارات (Signal Generator) ينشئ إشارات غنية بالسياق لمطابقات القواعد (مع شجرات عمليات اختيارية)
5. الشاحن (Shipper) يجمّع الإشارات ويرسلها إلى الخادم الخلفي عبر HTTPS مع منطق إعادة المحاولة وقاطع الدائرة
6. قاعدة الحالة (State DB) تحافظ على حالة الارتباط وتتبع خط الأساس وطابور الإشارات وسجل الطابور

دورة حياة الطابور:

• يتم حذف ملفات الطابور التي لا تحتوي على عمليات كشف بعد المعالجة لمنع امتلاء طابور Santa
• تُؤرشف الملفات التي أنتجت عمليات كشف إلى santa.archive_dir (الافتراضي: /var/lib/santamon/spool_hits)
• تتضمن الإشارات مسار الطابور المؤرشف عند توفره حتى تتمكن من استرجاع protobuf إذا لزم الأمر

سلالة العمليات:

• ذاكرة تخزين مؤقت في الذاكرة لتاريخ تنفيذ العمليات الأخير
• تتيح سياق شجرة عمليات كامل لعمليات كشف التنفيذ
• TTL: ساعة واحدة | الحد الأقصى: 50 ألف إدخال (إخلاء LRU)
• جلسة الإقلاع معزولة (لا يوجد نسب عبر عمليات الإقلاع)
• راجع RULES.md للاستخدام

المتطلبات

• macOS 15.4+ (بعض أنواع القياسات مثل tcc_modification تتطلب macOS 15+)
• Santa مع قياسات protobuf من northpolesec/santa
  • راجع وثائق قياسات Santa
  • مثال للإعداد: configs/examples/santa-config.mobileconfig
• Go 1.23+ (للبناء من المصدر)

التثبيت

1. إعداد Santa لقياسات Protobuf

يجب تكوين Santa لكتابة أحداث protobuf. استخدم ملف التكوين المقدم:

# Review and customize, then install via System Settings
open configs/examples/santa-config.mobileconfig

# Verify
santactl status | grep "Log Type"
# Should show: Log Type | protobuf

2. بناء Santamon

git clone https://github.com/0x4d31/santamon.git
cd santamon
make build

3. التثبيت على مستوى النظام

sudo make install

يتم تثبيت ما يلي:

• الملف التنفيذي: /usr/local/bin/santamon
• الإعدادات: /etc/santamon/config.yaml و rules.yaml
• LaunchDaemon: /Library/LaunchDaemons/com.santamon.plist
• دليل الحالة: /var/lib/santamon/

4. إعداد الخادم الخلفي ومفتاح API

عدّل /etc/santamon/config.yaml:

shipper:
  endpoint: "https://your-backend.example.com:8443/ingest"
  api_key: "${SANTAMON_API_KEY}"

عيّن مفتاح API في ملف LaunchDaemon plist:

# Generate strong API key
openssl rand -hex 32

# Edit LaunchDaemon
sudo nano /Library/LaunchDaemons/com.santamon.plist

# Add under EnvironmentVariables:
<key>SANTAMON_API_KEY</key>
<string>your-generated-key-here</string>

5. التشغيل

# Start service
sudo make start

# Monitor logs
make logs

الإعدادات

الإعداد الرئيسي: /etc/santamon/config.yaml

agent:
  id: "${HOSTNAME}"

shipper:
  endpoint: "https://backend.example.com:8443/ingest"
  api_key: "${SANTAMON_API_KEY}"

santa:
  spool_dir: "/var/db/santa/spool"      # Santa spool location
  archive_dir: "/var/lib/santamon/spool_hits"  # Archive spool files that produced alerts
  stability_wait: "2s"                  # Wait before reading new files

rules:
  path: "/etc/santamon/rules.yaml"      # File or directory

state:
  db_path: "/var/lib/santamon/state.db"
  sync_writes: true                     # Fsync after writes (safer but slower)

  first_seen:
    max_entries: 10000                  # LRU cache for baseline rules

  windows:
    max_events: 1000                    # Max events per correlation window

shipper:
  batch_size: 100                       # Signals per batch
  flush_interval: "30s"                 # Time between flushes
  timeout: "10s"                        # HTTP request timeout
  tls_skip_verify: false                # NEVER true in production

راجع configs/santamon.yaml لجميع الخيارات مع تعليقات مفصلة.

قواعد الكشف

القواعد هي تعبيرات CEL تقيّم أحداث Santa. ثلاثة أنواع مدعومة: بسيطة، ارتباطية، وخط أساس.

rules:
  - id: SM-014
    title: "Non-interactive process invoking curl/wget"
    description: |
      Non-terminal, non-package-manager process launching curl or wget.
    expr: |
      kind == "execution" &&
      event.execution.target.executable.path in ["/usr/bin/curl", "/usr/bin/wget"] &&

      // Exclude interactive shells
      !(
        event.execution.instigator.executable.path.startsWith("/bin/bash") ||
        event.execution.instigator.executable.path.startsWith("/bin/zsh") ||
        event.execution.instigator.executable.path.startsWith("/bin/sh")
      ) &&

      // Exclude Homebrew / package-manager helpers that legitimately use curl frequently
      !(
        event.execution.instigator.executable.path.startsWith("/opt/homebrew/") ||
        event.execution.instigator.executable.path.contains("/Homebrew/")
      )
    severity: high
    tags: ["T1105", "command-and-control"]
    extra_context: ["event.execution.args"]
    include_process_tree: true
    enabled: true

correlations:
  - id: SM-COR-001
    title: "Process touching multiple credential stores"
    description: "Single process accessing 3+ credential stores within 5 minutes."
    expr: |
      kind == "file_access" &&
      event.file_access.policy_name in [
        "ChromeCookies", "CometCookies", "SSHPrivateKeys",
        "BrowserPasswords", "KeychainDB"
      ]
    window: "5m"
    group_by: ["event.file_access.instigator.executable.path"]
    count_distinct: "event.file_access.policy_name"
    threshold: 3
    severity: critical
    tags: ["T1539", "T1552", "credential-access"]
    enabled: true

baselines:
  - id: SM-BASE-001
    title: "First-time unsigned binary executed from user paths"
    description: "First time an unsigned binary executes from /Users paths."
    expr: |
      kind == "execution" &&
      event.execution.decision == DECISION_ALLOW &&
      event.execution.target.executable.path.startsWith("/Users/") &&
      (
        !has(event.execution.target.code_signature) ||
        !has(event.execution.target.code_signature.team_id) ||
        event.execution.target.code_signature.team_id == ""
      )
    track: ["event.execution.target.executable.cdhash"]
    learning_period: "720h"
    severity: high
    tags: ["T1204.002", "initial-access"]
    enabled: true

تنظيم القواعد: ملف واحد (/etc/santamon/rules.yaml) أو بنية دليل متعدد الملفات.

تحقق قبل النشر:

santamon rules validate

راجع RULES.md للدليل الشامل.

الخادم الخلفي

يتطلب Santamon خادمًا خلفيًا لاستقبال الإشارات. يتضمن المشروع خادم FastAPI بسيطًا في backend/.

ما يفعله:

• يستقبل الإشارات عبر POST /ingest (يتطلب مفتاح API)
• يخزن الإشارات في قاعدة بيانات SQLite
• يوفر واجهة برمجية للاستعلام (GET /signals, GET /stats)
• يتتبع صحة الوكيل عبر نبضات القلب (POST /agents/heartbeat)
• واجهة ويب لإدارة الإشارات

بدء سريع:

cd backend
pip install fastapi uvicorn

# Set API key
export SANTAMON_API_KEY="your-key-here"

# Run (uses HTTPS if cert.pem exists, otherwise HTTP)
python backend.py

راجع backend/README.md.

أوامر CLI

# Run agent (foreground, verbose mode)
santamon run --verbose

# Validate rules
santamon rules validate

# Show status
santamon status

# Database operations
santamon db stats      # Show statistics
santamon db compact    # Compact database

# Version
santamon version

التوثيق

• RULES.md - دليل كتابة قواعد الكشف
• SECURITY.md - اعتبارات الأمان ومرونة الوكيل
• backend/README.md - دليل نشر الخادم الخلفي
• configs/santamon.yaml - مرجع إعدادات كامل
• configs/rules.yaml - أمثلة على قواعد الكشف