ГОСОПКА API 2025: обновляем интеграцию SIEM под новый формат уведомлений НКЦКИ

На прошлой неделе несколько клиентов одновременно написали об одном и том же: уведомления в ГОСОПКА перестали проходить. Коннекторы молчат, в логах - ошибки 400 или тихий таймаут. Начали разбираться - оказалось, что НКЦКИ обновил API и изменил структуру запроса. Без предупреждения, без миграционного периода. Просто взял и изменил.

Это случилось в феврале, а коннекторы у части клиентов стояли с 2023 года и до этого работали без вопросов. В итоге несколько организаций несколько дней фактически не передавали уведомления - что при проверке ФСТЭК выглядит плохо, даже если инцидентов за этот период не было.

Что изменилось в API

Мы собрали картину по нескольким клиентам и сравнили со старым форматом. Ключевых изменений три.

Структура полей уведомления. Старый формат использовал плоский JSON с полями типа incident_type, object_name, detection_time. Новый формат иерархический: основное уведомление - вложенный объект incident, внутри которого уже идут типизированные секции. Поля переименованы: detection_time стал detected_at, object_name разбился на kii_object.name и kii_object.registry_id. Если коннектор собирал запрос по-старому, сервер отдаёт 400 - и нередко без понятного сообщения об ошибке.

Обязательные поля. Добавились поля, которых раньше не было: kii_object.registry_id (номер в реестре значимых объектов), impact_category с фиксированным перечнем значений, notification_type (первичное/повторное). Если хотя бы одного нет - запрос не принимается. Это больно: реестровый идентификатор объекта не всегда был в SIEM-карточке события.

Сроки в обновлённом регламенте. Параллельно с API НКЦКИ уточнил формулировки по срокам: первичное уведомление - 3 часа с момента обнаружения для значимых объектов первой категории, 24 часа для второй и третьей. Это не новые цифры сами по себе, но теперь они зашиты в логику API: поле notification_type=primary с detected_at старше 3 часов у первой категории сервер помечает флагом нарушения срока. Раньше этого не было.

Как ломаются коннекторы

Паттернов поломки мы видели несколько, и они зависят от того, как именно был реализован коннектор.

У клиентов на MaxPatrol SIEM с кастомным коннектором под Python - самый распространённый случай. Коннектор брал данные из корреляционного правила и клал их в фиксированную структуру JSON. Структура жёстко зашита в код. При обновлении API сервер стал возвращать 400, Python-код это глотал без алерта - в логах просто пустая строка. Клиент несколько дней думал, что всё работает.

У одного клиента был самописный интегратор на PowerShell, который писался три года назад «временно». Там проблема была другая: detected_at собирался из поля Windows Event Log с локальным временем без таймзоны. Новый API стал требовать ISO 8601 с явным UTC-офсетом. Запросы уходили, но сервер их отклонял уже на стороне валидации содержимого.

Шаблон для MaxPatrol SIEM

Для клиентов на MaxPatrol SIEM мы подготовили обновлённый шаблон действия (action) в корреляционном правиле. Базовая структура запроса под новый формат выглядит так:

{
  "notification_type": "primary",
  "incident": {
    "detected_at": "{{event.time | to_iso8601_utc}}",
    "description": "{{event.description}}",
    "impact_category": "{{event.impact_category}}",
    "attack_vector": "{{event.attack_vector | default('unknown')}}",
    "kii_object": {
      "name": "{{asset.name}}",
      "registry_id": "{{asset.kii_registry_id}}"
    },
    "affected_systems": [
      {
        "hostname": "{{event.src_host}}",
        "ip": "{{event.src_ip}}"
      }
    ]
  },
  "reporter": {
    "organization": "{{org.name}}",
    "contact_email": "{{org.security_email}}"
  }
}

Переменные с двойными фигурными скобками - это MaxPatrol-синтаксис обогащения событий. Поля asset.kii_registry_id и org.security_email нужно завести в кастомных атрибутах актива заранее - они не появляются из коробки.

impact_category принимает одно из фиксированных значений: disruption, data_leak, unauthorized_access, destruction, other. Если ваше корреляционное правило не классифицирует инцидент по этой таксономии - нужно либо добавить логику маппинга, либо ставить other с описанием в description.

Для собственного коннектора

Если у вас не MaxPatrol, а собственный коннектор или интеграция через промежуточный скрипт - несколько вещей, которые стоит проверить сразу.

Формат времени. detected_at должен быть строго в ISO 8601 с UTC-офсетом: 2025-02-28T14:23:00+03:00 или 2025-02-28T11:23:00Z. Локальное время без зоны - 400.

kii_registry_id не опциональный. Это один из самых частых пропусков. Реестровый номер значимого объекта должен быть в данных на стороне SIEM или в конфигурации коннектора на момент отправки. Если у вас несколько значимых объектов с разными реестровыми номерами - коннектор должен уметь их различать.

Проверяйте ответ сервера. Новый API возвращает структурированный JSON с полем error_code при отказе. Если ваш код просто проверяет HTTP-статус 200/не-200 - вы можете пропустить частичный успех или специфичную ошибку валидации. Логируйте тело ответа.

Тестовый endpoint. НКЦКИ предоставляет тестовую среду. Прогоните через неё несколько сценариев, включая повторное уведомление (notification_type=update) и уведомление с нарушением срока - убедитесь, что ваш код корректно обрабатывает флаг delayed в ответе.

Где сейчас стоит точка

По состоянию на начало марта мы обновили интеграции у нескольких клиентов в рамках работ по интеграции. Большинство кейсов решились за день-два, один застрял на проблеме с реестровыми идентификаторами - там часть объектов вообще не была категорирована, и это уже другая история.

Рекомендация простая: если ваша интеграция с ГОСОПКА настраивалась до 2025 года - прогоните тест прямо сейчас. Не через месяц перед проверкой, а сейчас. Три часа на починку коннектора - это хорошо. Объяснять ФСТЭК, почему уведомления не уходили последние две недели, - значительно хуже.

Офиц документация НКЦКИ обновилась, но с задержкой - на момент написания там есть расхождения между описанием полей и реальным поведением API. Ориентируемся на тестовую среду и на то, что видим в ответах сервера.