Santamon

Облегченный сайдкар обнаружения для macOS для Santa, который локально оценивает телеметрию Endpoint Security с помощью правил CEL и пересылает только совпавшие сигналы обнаружения на сервер бэкенда.

Экспериментальный. Создан для домашних лабораторий и небольших парков устройств. Ранний релиз – ожидайте ошибок и изменений API.

Что он делает

Santamon читает поток телеметрии protobuf от Santa, оценивает правила обнаружения с помощью выражений CEL и отправляет сигналы безопасности на бэкенд. Необработанная телеметрия остается на конечной точке – пересылаются только обнаружения.

Основные возможности:

• Локальное обнаружение: правила на основе CEL оценивают события на устройстве
• Три типа правил: простое сопоставление, временная корреляция, база (первое появление)
• Родословная процессов: опциональное присоединение полных деревьев процессов к сигналам выполнения
• Встроенное состояние: BoltDB отслеживает корреляции, данные о первом появлении и очередь сигналов
• Устойчивая отправка: одновременная пакетная обработка, логика повторных попыток, автоматический выключатель

Зачем Santamon?

Santamon – это сайдкар обнаружения для Santa, а не еще один клиент ESF.

Создание собственного инструмента ESF требует ограниченных привилегий Apple, профилей обеспечения и тщательной обработки высокообъемных событий Endpoint Security. Santa уже делает это и проверен в производстве.

Ценность Santamon:

• Использует Santa как уровень сенсора ESF (не нужны дополнительные привилегии)
• Запускает правила локально, рядом с данными, вместо потоковой передачи всего
• Легкое состояние через BoltDB для корреляций и дедупликации
• Низкая стоимость инфраструктуры – отправляет только сигналы высокой значимости

Santa берет на себя тяжелую работу по надежному и безопасному приему событий Endpoint Security; 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: 1 час | Макс.: 50K записей (вытеснение 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. Используйте предоставленный профиль конфигурации:

# Просмотрите и настройте, затем установите через Системные настройки
open configs/examples/santa-config.mobileconfig

# Проверьте
santactl status | grep "Log Type"
# Должно отображать: 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-ключ в plist LaunchDaemon:

# Сгенерируйте надежный API-ключ
openssl rand -hex 32

# Отредактируйте LaunchDaemon
sudo nano /Library/LaunchDaemons/com.santamon.plist

# Добавьте в раздел EnvironmentVariables:
<key>SANTAMON_API_KEY</key>
<string>your-generated-key-here</string>

5. Запуск

# Запустите службу
sudo make start

# Мониторинг логов
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
  archive_dir: "/var/lib/santamon/spool_hits"  # Архив файлов спула, вызвавших оповещения
  stability_wait: "2s"                  # Ожидание перед чтением новых файлов

rules:
  path: "/etc/santamon/rules.yaml"      # Файл или каталог

state:
  db_path: "/var/lib/santamon/state.db"
  sync_writes: true                     # Fsync после записи (безопаснее, но медленнее)

  first_seen:
    max_entries: 10000                  # LRU-кэш для базовых правил

  windows:
    max_events: 1000                    # Максимум событий на окно корреляции

shipper:
  batch_size: 100                       # Сигналов на пакет
  flush_interval: "30s"                 # Время между отправками
  timeout: "10s"                        # Таймаут HTTP-запроса
  tls_skip_verify: false                # НИКОГДА не true в продакшене

Полный справочник всех опций с подробными комментариями см. в configs/santamon.yaml.

Правила обнаружения

Правила — это выражения CEL, которые оценивают события Santa. Поддерживаются три типа: простое, корреляция и базовое.

rules:
  - id: SM-014
    title: "Неинтерактивный процесс, запускающий curl/wget"
    description: |
      Не терминальный, не пакетный менеджер процесс запускает curl или wget.
    expr: |
      kind == "execution" &&
      event.execution.target.executable.path in ["/usr/bin/curl", "/usr/bin/wget"] &&

      // Исключаем интерактивные оболочки
      !(
        event.execution.instigator.executable.path.startsWith("/bin/bash") ||
        event.execution.instigator.executable.path.startsWith("/bin/zsh") ||
        event.execution.instigator.executable.path.startsWith("/bin/sh")
      ) &&

      // Исключаем Homebrew / помощников пакетных менеджеров, которые законно часто используют curl
      !(
        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: "Процесс, обращающийся к нескольким хранилищам учетных данных"
    description: "Один процесс обращается к 3+ хранилищам учетных данных в течение 5 минут."
    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: "Впервые выполняется неподписанный бинарник из пользовательских путей"
    description: "Первый раз, когда неподписанный бинарник выполняется из путей /Users."
    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
• Предоставляет API запросов (GET /signals, GET /stats)
• Отслеживает состояние агента через сигналы пульса (POST /agents/heartbeat)
• Веб-интерфейс для управления сигналами

Быстрый старт:

cd backend
pip install fastapi uvicorn

# Установите API-ключ
export SANTAMON_API_KEY="your-key-here"

# Запуск (использует HTTPS, если существует cert.pem, иначе HTTP)
python backend.py

См. backend/README.md.

Команды CLI

# Запуск агента (передний план, подробный режим)
santamon run --verbose

# Проверка правил
santamon rules validate

# Показать статус
santamon status

# Операции с базой данных
santamon db stats      # Показать статистику
santamon db compact    # Сжать базу данных

# Версия
santamon version

Документация

• RULES.md — Руководство по написанию правил обнаружения
• SECURITY.md — Соображения безопасности и устойчивость агента
• backend/README.md — Руководство по развертыванию бэкенда
• configs/santamon.yaml — Полный справочник конфигурации
• configs/rules.yaml — Примеры правил обнаружения