Santamon

macOS के लिए हल्का डिटेक्शन साइडकार Santa जो स्थानीय रूप से CEL नियमों के साथ एंडपॉइंट सुरक्षा टेलीमेट्री का मूल्यांकन करता है और केवल मिलान किए गए डिटेक्शन सिग्नल को बैकएंड सर्वर पर अग्रेषित करता है।

प्रायोगिक. होम लैब और छोटे फ्लीट के लिए बनाया गया। प्रारंभिक रिलीज़ – बग और API परिवर्तनों की उम्मीद करें।

यह क्या करता है

Santaman Santa के protobuf टेलीमेट्री स्ट्रीम को पढ़ता है, CEL अभिव्यक्तियों का उपयोग करके डिटेक्शन नियमों का मूल्यांकन करता है, और सुरक्षा सिग्नल को बैकएंड पर भेजता है। कच्ची टेलीमेट्री एंडपॉइंट पर रहती है—केवल डिटेक्शन ही अग्रेषित किए जाते हैं।

मुख्य क्षमताएं:

• स्थानीय डिटेक्शन: CEL-आधारित नियम डिवाइस पर घटनाओं का मूल्यांकन करते हैं
• तीन नियम प्रकार: साधारण मिलान, समय-खिड़की सहसंबंध, बेसलाइन (पहली बार देखा गया)
• प्रक्रिया वंशावली: वैकल्पिक रूप से निष्पादन सिग्नल में पूर्ण प्रक्रिया ट्री संलग्न करें
• एम्बेडेड स्थिति: BoltDB सहसंबंध, पहली बार देखा गया डेटा, और सिग्नल कतार को ट्रैक करता है
• लचीला शिपिंग: समवर्ती बैचिंग, पुनः प्रयास तर्क, सर्किट ब्रेकर

Santamon क्यों?

Santaman 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. वॉचर नए protobuf फ़ाइलों के लिए Santa के स्पूल निर्देशिका (/var/db/santa/spool/new/) की निगरानी करता है
2. डिकोडर स्पूल फ़ाइलों से protobuf संदेशों को पढ़ता और डीकंप्रेस करता है
3. नियम इंजन CEL अभिव्यक्तियों के विरुद्ध घटनाओं का मूल्यांकन करता है (सरल, सहसंबंध, बेसलाइन नियम)
4. सिग्नल जनरेटर नियम मिलान के लिए संदर्भ-समृद्ध सिग्नल बनाता है (वैकल्पिक प्रक्रिया ट्री के साथ)
5. शिपर बैच करता है और HTTPS के माध्यम से पुनः प्रयास तर्क और सर्किट ब्रेकर के साथ बैकएंड को सिग्नल भेजता है
6. स्थिति DB सहसंबंध स्थिति, बेसलाइन ट्रैकिंग, सिग्नल कतार और स्पूल जर्नल को बनाए रखता है

स्पूल जीवनचक्र:

• डिटेक्शन के बिना स्पूल फ़ाइलों को प्रसंस्करण के बाद हटा दिया जाता है ताकि Santa का स्पूल भरने से बचा रहे
• जिन फ़ाइलों में डिटेक्शन उत्पन्न हुआ, उन्हें santa.archive_dir (डिफ़ॉल्ट: /var/lib/santamon/spool_hits) में संग्रहीत किया जाता है
• सिग्नल में उपलब्ध होने पर संग्रहीत स्पूल पथ शामिल होता है ताकि आवश्यकता पड़ने पर आप protobuf प्राप्त कर सकें

प्रक्रिया वंशावली:

• हाल की प्रक्रिया निष्पादन इतिहास का इन-मेमोरी कैश
• निष्पादन डिटेक्शन के लिए पूर्ण प्रक्रिया ट्री संदर्भ सक्षम करता है
• TTL: 1 घंटा | अधिकतम: 50K प्रविष्टियाँ (LRU निष्कासन)
• बूट सत्र पृथक (कोई क्रॉस-बूट वंशावली नहीं)
• उपयोग के लिए RULES.md देखें

आवश्यकताएँ

• macOS 15.4+ (कुछ टेलीमेट्री प्रकार जैसे tcc_modification के लिए macOS 15+ आवश्यक है)
• protobuf टेलीमेट्री के साथ Santa 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
• लॉन्चडेमन: /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}"

LaunchDaemon plist में API कुंजी सेट करें:

# 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 देखें।

बैकएंड

Santaman को सिग्नल प्राप्त करने के लिए एक बैकएंड की आवश्यकता है। backend/ में एक न्यूनतम FastAPI बैकएंड शामिल है।

यह क्या करता है:

• POST /ingest के माध्यम से सिग्नल प्राप्त करता है (API कुंजी आवश्यक)
• SQLite डेटाबेस में सिग्नल संग्रहीत करता है
• क्वेरी API प्रदान करता है (GET /signals, GET /stats)
• हार्टबीट के माध्यम से एजेंट स्वास्थ्य को ट्रैक करता है (POST /agents/heartbeat)
• सिग्नल प्रबंधन के लिए वेब UI

त्वरित प्रारंभ:

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 - उदाहरण डिटेक्शन नियम