Интеграция событий безопасности CodeGraph с SIEM

CodeGraph формирует и отправляет события безопасности через настроенные Syslog, CEF и LEEF handlers. В интеграции разделены создание события, локальный dispatch, buffered retry, delivery status handler и receipt downstream-системой. Сохраняйте доказательство того этапа, который требует политика приёмки заказчика.

Контракт и источники

Текущая граница реализации:

• src/security/siem/base_handler.py — SecurityEventType, поля события и интерфейс handler;
• src/security/siem/dispatcher.py — регистрация handlers, попытки dispatch, status и activity;
• src/security/siem/buffer.py — ограниченный retry buffer;
• src/security/siem/syslog_handler.py, cef_handler.py, leef_handler.py — форматы;
• src/security/config.py и раздел security.siem в config.yaml — типизированные настройки.

Аутентифицированные маршруты конфигурации, статистики и последних событий доступны под актуальной поверхностью /api/v1/security/siem. Схемы берите из OpenAPI развёрнутой версии.

Контракт события

SecurityEvent содержит event type, timestamp, request ID, message, severity и опциональные поля пользователя, сессии, сети, провайдера, модели, DLP, токенов, latency, проекта, группы и деталей. Источник истины по типам — текущий enum SecurityEventType; не фиксируйте его количество в политике.

Существующие семейства охватывают LLM request/response/error, действия DLP, доступ и ротацию Vault, успех и отказ authentication, rate limiting, общие security alerts, path и IDOR violations, webhook replay и отказ MCP authentication. Новые релизы могут добавлять типы без изменения transport setup.

Настройка handlers

Включайте только форматы, которые использует SOC-получатель:

Используйте DNS и сертификаты под управлением заказчика. Между trust boundaries предпочитайте аутентифицированный и зашифрованный transport. Ограничьте egress получателем и не храните пароли и приватные ключи в закоммиченной конфигурации.

Dispatcher может инициализировать несколько handlers. Результат каждого handler проверяйте отдельно.

Dispatch и buffering

Без buffer синхронный dispatch сообщает, отправил ли событие хотя бы один handler. С buffer метод dispatch может подтвердить enqueue до фактической downstream-отправки. Переполненный или исчерпавший retries buffer означает деградацию security control.

Фиксируйте:

• включённые и успешно инициализированные handlers;
• per-handler status healthy или degraded и last error summary;
• последние попытки dispatch со статусом sent или failed;
• queue size, dropped и retried events, flush result и retry exhaustion;
• receiver-side event identity и ingestion time.

Не называйте подтверждение enqueue доставкой.

Сквозная проверка

Используйте синтетическое событие без секретов репозитория:

1. сохраните release, effective SIEM config и receiver index либо channel;
2. создайте событие типа, ожидаемого настроенным handler;
3. проверьте локальное событие и request ID;
4. проверьте per-handler dispatch activity и buffer state;
5. найдите ту же identity в downstream SIEM;
6. запишите latency, normalization, severity и mapping полей;
7. повторите контролируемый negative test с недоступным получателем или неверным TLS.

Для UDP доставку подтверждает receiver-side receipt. Для TCP или TLS indexing подтверждается записью у получателя.

Мониторинг и оповещения

Оповещайте об отключённом обязательном handler, degraded status, росте buffer, повторных retries, dropped events, устаревшем last-success и разрыве receiver ingestion. Пороговые значения должны опираться на SLO заказчика и измеренную частоту событий.

Проверьте, какие чувствительные поля следует редактировать до отправки. SIEM — отдельный получатель данных, поэтому включайте его в classification, retention, access и deletion policy.

Ошибка и восстановление

При отказе доставки:

1. сохраните первую ошибку и effective configuration без секретов;
2. разделите ошибки formatting, DNS, network, TLS, receiver и rate limit;
3. защитите buffer от бесконечного роста и тихой перезаписи;
4. восстановите handler или примените одобренный альтернативный канал;
5. выполните flush и сверку pending events;
6. подтвердите downstream receipt и явно закройте gap window.

Не отключайте SIEM молча ради доступности приложения. Если допускается degraded operation, зафиксируйте approver, duration, компенсирующий monitoring, backlog plan и exit condition.

Доказательства приёмки

Enterprise evidence packet должен включать digest конфигурации, inventory handlers, синтетические positive и negative tests, локальную dispatch activity, buffer statistics, downstream receipt, alert routing, владельца retention, известные gaps и recovery results. Это доказывает только контур SIEM, но не то, что каждое значимое действие продукта формирует требуемое событие.