Документация›Инженерия контента›2. Коннекторы и инстансы интеграций

Коннекторы и инстансы интеграций

Почему это важно. Коннектор — это то, как SOARForge дотягивается до внешней системы: алерты втекают внутрь через него, а команды реагирования вытекают наружу через него. Каждый инцидент, к которому когда-либо прикасается SOC-аналитик, зарождается на коннекторе — фиде SIEM, источнике Threat Intel, отслеживаемом почтовом ящике или системе тикетов. Эта глава — глубокий справочник для инженеров контента, которые подключают эти источники. Обзорную экскурсию по всему разделу Integrations на уровне навигации см. в руководстве администратора §2; эта глава спускается на уровень ниже.

2.1. Каталог коннекторов

Маршрут: /settings/connectors · Права: connectors.view (смотреть), connectors.manage (создавать, редактировать, тестировать, удалять)

Экран Connectors — это двухколоночное рабочее пространство. Левая колонка перечисляет типы коннекторов, установленные на этой платформе; правая колонка редактирует инстансы того коннектора, который вы выбрали.

Левая колонка — список коннекторов. Каждая строка показывает имя коннектора, его тег типа (siem, edr, threat_intel, email, ticketing, sandbox, ai_provider или custom), синий тег Managed, когда коннектор поставляет продуктизированный поток настройки, строку source key: <key> и число настроенных инстансов. Кликните строку, чтобы загрузить её инстансы справа. Список — это прямой перечень установленных коннекторов, здесь нет поля поиска или фильтра по категориям (это живёт в Marketplace, гайд администратора §5.2). Над списком стоят четыре элемента управления:

Кнопка	Назначение
New Integration	Зарегистрировать совершенно новый тип коннектора в редакторе с направляемым конструктором полей (§2.3).
Import Package	Загрузить пакет коннектора: `.zip` content-пак (устанавливается на сервере) или устаревший одиночный `.json` (открывается предзаполненным в редакторе).
Integration IDE	Открыть редактор кода для написания интеграции из Python + манифеста (§2.4).
⟳ (reload)	Перечитать список коннекторов.

Правая колонка — карточка инстансов. Её заголовок повторяет source key и зелёный тег Managed, когда применимо, и предлагает Edit Integration (редактировать выбранный тип коннектора), Export Package (скачать коннектор как JSON-пакет), Delete Integration (удалить тип коннектора) и New Instance (создать инстанс — §2.6). Однострочное описание сообщает, какой стиль конфигурации использует этот коннектор: направляемую форму по схеме, управляемый поток настройки или общий JSON-редактор.

2.2. Коннекторы и инстансы — и откуда берутся коннекторы

Два существительных проходят через всю эту главу, и различать их — значит избавить себя от многих недоразумений:

Коннектор (тип коннектора / интеграция) — это переиспользуемое определение системы, с которой SOARForge может разговаривать: её тип, её sourceKey, форма её формы учётных данных и Python-код за её командами. На один продукт приходится один коннектор (например, один коннектор «Office 365»).
Инстанс (конфигурация коннектора) — это одно настроенное, снабжённое учётными данными подключение, построенное из этого коннектора. Можно запускать много инстансов одного коннектора — по одному на ящик, на тенант, на кластер SIEM — каждый со своими учётными данными, классификатором, маппером и настройками fetch.

Коннекторы попадают на вашу платформу четырьмя каналами:

Встроенный seed. Базовый набор коннекторов засеивается при установке.
Content-паки Marketplace. Установка пака из Advanced → Marketplace регистрирует интеграции этого пака как коннекторы — они появляются в левом списке автоматически, со своей формой учётных данных, командами и любыми плейбуками-спутниками. Обновление или откат пака обновляет определение коннектора и каталог команд, не трогая ваши существующие инстансы, учётные данные, классификаторы или мапперы. (См. гайд администратора §5.2.)
New Integration — редактор с направляемым конструктором полей (§2.3).
Integration IDE / Import Package — авторинг «сначала код» (§2.4) или импорт файла-пакета.

Почему это важно. Наличие Python-пакета в рантайме само по себе не делает коннектор. Коннектор существует только тогда, когда у него есть зарегистрированный тип с sourceKey — через seed, установку из Marketplace или один из путей авторинга ниже. Если вы ждёте коннектор и не видите его в списке — значит, он ещё не установлен как коннектор.

2.3. Регистрация нового типа интеграции (New Integration)

Маршрут: /settings/connectors → New Integration · Право: connectors.manage

Используйте этот редактор, когда источнику нужны только форма учётных данных плюс (опционально) переносимый пакет автоматизации — без рукописного UI. Он регистрирует тип коннектора, который аналитики позже будут инстанцировать.

Модальное окно состоит из трёх частей:

1. Identity.

Поле	Примечания
Integration Name	Обязательно. Отображаемое имя (напр. `Check Point Harmony`).
Integration Type	Обязательно. Один из SIEM · EDR · Threat Intel · Email · Ticketing · Sandbox · AI Provider · Custom. Тип управляет поведением — только Email/SIEM/EDR (и управляемые коннекторы) показывают элементы сбора инцидентов; Threat Intel и AI Provider только по запросу.
Source Key	Обязательно. Только строчные буквы, цифры и подчёркивания (`^[a-z][a-z0-9_]*$`), напр. `harmony_edr`. Этот ключ — то, как ingest и инстансы резолвят интеграцию; выбирайте его обдуманно, это стабильный идентификатор коннектора.
Description / Icon URL	Опциональное оформление.
Active	Включён ли тип коннектора.

2. Instance Configuration Form. Этот конструктор полей определяет входы, которые аналитики видят при создании инстанса. Добавляйте поля через Add Config Field; у каждого поля есть:

Свойство	Назначение
Field Key	Хранимый ключ конфигурации (тот же строчный паттерн, что и Source Key).
Field Label	Подпись, показываемая в форме инстанса.
Field Type	Short text · Password / Secret · Number · Boolean · Select · URL. Поля Password/Secret шифруются в покое и отрисовываются как замаскированные вводы.
Help Text	Показывается под полем в форме инстанса.
Required	Помечает поле обязательным.
Default Value	Предзаполненное значение (`true` / `10` / строка).
Select Options	Варианты через запятую — используются, только когда Field Type = Select.

3. Automation Package (опционально). Вставьте или импортируйте переносимый рантайм-пакет (JSON), если этот коннектор должен автоматически провизионировать учётные данные и команды после создания инстанса. Экспортированные встроенные коннекторы уже несут этот пакет — именно это делает их управляемыми.

2.4. Написание кода интеграции — Integration IDE

Маршрут: /settings/integrations/editor[/:connectorId] · Право: connectors.manage

Когда формы полей недостаточно — нужны настоящие команды и вызовы API — Integration IDE позволяет написать интеграцию и тут же её протестировать, без отдельного шага сборки или деплоя. Откройте его кнопкой Integration IDE на экране Connectors.

Панель инструментов несёт всё, что нужно для авторинга и тестирования:

Элемент	Назначение
Integration name	Именует коннектор; `sourceKey` выводится из него при сохранении.
Template (Select)	Засеивает оба редактора из стартера: Enrichment, Fetch incidents или Response action.
cmd …	Команда для запуска при тесте (по умолчанию `test-module`).
Test command	Прогоняет текущую команду по вашему коду и показывает баннер pass/fail с сообщением и длительностью.
Save	Сохраняет код в пакет коннектора.
Python script (слева, редактор Monaco)	Код интеграции.
YAML manifest (справа, редактор Monaco)	Манифест интеграции — параметры конфигурации, команды и их аргументы/выводы.

Редакторы — это двухпанельная IDE: Python слева, YAML-манифест справа, оба с подсветкой синтаксиса и учётом темы. Стартовые шаблоны — реальные, запускаемые скелеты. Код интеграции — обычный Python, импортирующий SOARForge SDK и общий вспомогательный модуль:

import forgebot as forge
from CommonServerPython import *

def main() -> None:
    command = forge.command()
    args = forge.args()
    if command == 'test-module':
        return_results('ok')
    elif command == 'enrich':
        return_results(enrich_command(args))
    ...

Вы диспетчеризуете по forge.command(), читаете входы через forge.args() / forge.params(), забираете алерты через forge.incidents(...) и возвращаете результаты через return_results(...). Манифест объявляет поля конфигурации коннектора (которые становятся формой инстанса), его команды и аргументы и контекстные выводы каждой команды. Save записывает Python и манифест в пакет коннектора; при первом сохранении вас перенаправляет в тот же редактор, привязанный к id нового коннектора, так что дальнейшие правки обновляют его на месте.

Почему это важно. IDE спроектирована для плотного цикла авторинга: написать, Test command, прочитать баннер, поправить, повторить — всё это до того, как вы вообще создадите реальный инстанс или привяжете учётные данные. Тестирование здесь гоняет ваш несохранённый код, так что итерировать можно свободно.

2.5. Как Python-рантайм выполняет вашу интеграцию

Это стоит понимать на пользовательском уровне, потому что это объясняет, что на самом деле делают «Test» и «Run Command».

Код интеграции выполняется в выделенном сервисе — воркере integration-runtime — а не внутри API. API просит рантайм выполнить команду; рантайм загружает ваш пакет и запускает его.
Каждое выполнение — изолированный, убиваемый подпроцесс. Команды и inline- скрипты выполняются в собственном процессе, изолированные друг от друга и ограниченные таймаутом выполнения — сбежавшая команда (и любые порождённые ею дочерние процессы) завершается. Это не внутрипроцессный вызов и не контейнер на каждое выполнение.
SDK внедрён за вас. forgebot (и вспомогательный слой CommonServerPython) предоставляются рантаймом; интеграции, импортированные из upstream demisto/content, при импорте ребрендятся на SDK forgebot, так что большой пласт общественных интеграций работает без модификаций.
Несколько зависимо-тяжёлых коннекторов выполняются в собственном предсобранном virtualenv, запечённом в образ рантайма (по ADR-0012), потому что их Python-SDK конфликтуют с core-зависимостями рантайма. Для вас это невидимо — вы настраиваете, тестируете и запускаете их ровно как любой другой коннектор.
Учётные данные шифруются в покое и расшифровываются только в тот момент, когда они нужны команде; они никогда не возвращаются в API-ответах и не показываются обратно в форме.

Test command в IDE идёт особым inline-путём: API упаковывает ваш текущий код в памяти и просит рантайм выполнить одну команду во временной песочнице, затем выбрасывает её — ничего не устанавливается. Test на уровне инстанса (§2.8) — другое: он гоняет test-module установленной интеграции по живым, расшифрованным учётным данным инстанса.

2.6. Настройка инстанса: Connect, Collect, Runtime

Маршрут: /settings/connectors → выберите коннектор → New Instance (или Edit на строке) · Право: connectors.manage

Редактор инстанса — там, где происходит настоящая работа. Его раскладка адаптируется к коннектору: коннекторы, экспонирующие схему, получают направляемую, сгруппированную форму; коннекторы без схемы откатываются к сырому редактору Credentials JSON.

Заголовок — идентичность

Поле	Примечания
Instance Name	Обязательно. Человекочитаемая подпись, напр. `O365 SOC Mailbox`.
Source Instance Key	Уникальный, без пробелов ключ, идентифицирующий этот инстанс (напр. `o365-soc-mailbox`). Обязателен для управляемых коннекторов — каждому ящику/тенанту нужен свой ключ.
Source Reliability	Показывается только для коннекторов Threat Intel, которые не несут собственного поля надёжности. Рейтинг по шкале Admiralty (A++ … None, по умолчанию B), который говорит threat-скорингу, насколько доверять вердиктам этого источника.
Advanced Settings (переключатель)	Раскрывает расширенные элементы управления и расширенные поля каждой секции схемы (§2.7).

Connect / Collect / Runtime & network / General (форма по схеме)

Для коннектора со схемой поля учётных данных и поведения сгруппированы в подписанные секции, у каждой из которых иконка, счётчик и встроенная подсказка. Обязательные поля остаются видимыми; расширенные поля появляются только при включённом Advanced Settings.

Секция	Что держит
Connect	Учётные данные, идентичность tenant/application, полномочия на ящик и выбор облака.
Collect	Папку ящика, начальный lookback, лимиты на fetch и поведение фильтрации инцидентов.
Runtime & network	Прокси, сертификат, таймаут, именование вложений и опции безопасности процесса.
General	Поля, специфичные для коннектора, которые не объявляют вендорской секции.

Почтовый коннектор (Office 365) — хороший разобранный пример того, что отрисовывают эти секции:

Connect — Mailbox email address, Application (client) ID, Tenant ID, Application secret (пара идентификатор + секрет), плюс расширенные UPN mailbox override, Access type, Azure cloud и Use self-deployed Azure application.
Collect — Folder to fetch, First fetch window, Max per fetch и расширенные Fetch time field (время получения vs время изменения) и Mark fetched emails as read.
Runtime & network — Use system proxy, Trust any certificate, Exchange request timeout, Run in separate process, Legacy attachment names, Skip unparsable emails, Public folder.

Секретные поля отрисовываются замаскированными. Когда вы редактируете существующий инстанс, они показывают плейсхолдер Stored secret и примечание «leave blank to keep the current secret» — так что если ничего не набрать, сохранённое значение сохраняется, а если набрать новое, оно ротируется.

Max fetch и first fetch — поля интеграции, а не поля платформы. Единственный элемент управления fetch, которым владеет SOARForge, — это планировщиковый Fetch interval (§2.7). Сколько событий за опрос (max_fetch) и как далеко назад смотреть при первом опросе (first_fetch) живут в секции Collect коннектора и синхронизируются в коллектор в рантайме. Если хотите больший батч или более длинный начальный lookback — задайте их в Collect; смена одного интервала этого не сделает.

Карточка Collect (fetch)

Для коннекторов, которые принимают инциденты — Email, SIEM, EDR и управляемых коннекторов — появляется дополнительная карточка Collect с привязками опроса и классификации:

Элемент	Назначение
Fetches incidents (чекбокс)	Включает плановый опрос для этого инстанса.
Classifier	Единственный классификатор, прикреплённый к этому инстансу. Он первым определяет тип инцидента; затем входящий маппер применяет совпавшую ветку. Кнопки позволяют создать новый классификатор или перейти в редактор Classification.
Fallback incident type	Тип, используемый, когда классификатор не прикреплён или ни одно правило не совпало. Обязателен при включённом сборе инцидентов (и для управляемых коннекторов).
Mapper (incoming)	Единственный входящий маппер, прикреплённый к этому инстансу. Добавляйте ветки для конкретных типов внутри него, а не создавайте отдельный маппер на каждый тип инцидента.

У коннекторов «по запросу» нет карточки Collect. Коннекторы Threat Intel и AI Provider — а также коннекторы типа Ticketing/Sandbox/Custom — не опрашивают инциденты, поэтому у них никогда нет элементов fetch, classifier, fallback или incoming mapper. Они настраиваются для выполнения команд и обогащения.

Коннекторы без схемы

Коннектор, не экспонирующий схему, показывает единый редактор Credentials JSON вместо сгруппированных секций — вы вставляете учётные данные/рантайм-настройки инстанса как JSON. Классификация и маппинг всё равно живут в полноценных объектах Classifier и Mapper; общей является только форма учётных данных. При редактировании подпись становится «Credentials JSON (leave blank to keep current secrets)».

Управляемые коннекторы

Управляемый коннектор (его тип несёт продуктизированный рантайм, напр. Office 365) провизионирует свой коллектор автоматически: заполните форму, сохраните — и опрос настроен за вас. Управляемые инстансы требуют Source Instance Key и Fallback incident type, а редактор при сохранении показывает зелёное подтверждение, что автоматизация провизионирована.

Футер предлагает Cancel, Test (доступно только для сохранённого инстанса), Save и Save & Exit.

2.7. Расширенные настройки инстанса

Переключите Advanced Settings в заголовке, чтобы раскрыть:

Элемент	Назначение
Fetch interval	Как часто (в минутах) планировщик опрашивает этот инстанс. Только fetch-способные коннекторы. Управляет только каденцией — не размером батча и не lookback.
Mapper (outgoing)	Опциональный исходящий маппер, используемый для зеркалирования / внешней синхронизации.
Active	Включён ли инстанс вообще. Неактивный инстанс не опрашивается и не предлагается командам.
Use by default	Позволяет обобщённому выбору команд, резолву команд War Room и обнаружению Action в плейбуке выбирать этот инстанс. По умолчанию включено.
Auto enrichment	Позволяет автоматическому обогащению Threat Intel использовать этот инстанс. Ручные запуски всё равно могут его целить. По умолчанию включено.

При включённом Advanced Settings каждая секция схемы также разворачивается, показывая свои расширенные поля (прокси, доверие сертификатам, таймауты и подобное).

Привязки Classifier, Fallback incident type и Incoming/Outgoing mapper вместе образуют настройку классификации и маппинга инстанса — классификатор выбирает тип инцидента, входящий маппер формирует поля. Глава 3 разбирает сборку этих объектов; здесь вы их лишь прикрепляете к инстансу.

2.8. Тестирование инстанса

Используйте Test — кнопку панели инструментов в строке или кнопку Test в футере редактора (доступна после сохранения инстанса) — чтобы проверить подключение.

Что он делает: если интеграция загружена в рантайм, SOARForge гоняет команду test-module интеграции по живым, расшифрованным учётным данным этого инстанса. Если интеграция не загружена, вы всё равно получаете результат только с метаданными. Модальное окно результата («Instance test: ») сообщает:

Connection result — зелёный баннер «✓ Connection successful» или красный «✗ Connection failed» с сообщением рантайма и временем ответа в миллисекундах. Длинный или HTML-ответ (часто страница логина/ошибки) показывается в прокручиваемом блоке — сильная подсказка, что URL или учётные данные неверны.
Source key, Source instance (или not set), Fetch incidents (включено/выключено), Credentials present (да/нет) и Automation status.

Почему это важно. Зелёный тест означает, что SOARForge дотянулся до системы и аутентифицировался ровно теми учётными данными, которые этот инстанс будет использовать в проде — лучшая единственная проверка перед тем, как положиться на коннектор.

2.9. Запуск команды вручную

Run (кнопка панели инструментов на строке инстанса) открывает модальное окно Run Command — способ выполнить любую из команд интеграции вручную, для проверки или разовых действий.

Выберите команду из искомого списка (поиск по отображаемому имени или id команды; test-module исключена), и модальное окно отрисует аргументы этой команды как динамическую форму: обязательные аргументы помечены, низкочастотные опции сворачиваются за Show advanced arguments, а внутренние аргументы опроса скрыты. Некоторые команды реагирования (целящие в эндпоинты) требуют заполнить хотя бы одно поле выбора цели, прежде чем Execute станет доступной. Результат показывает зелёный тег Success с длительностью, панель Human Readable и сырой JSON Context Data, который произвела команда.

Если модальное окно показывает «No commands available», у интеграции нет команд, зарегистрированных в рантайме — код коннектора там не установлен (кастомный пак, который так и не установили как артефакт, или рассинхрон sourceKey).

2.10. Включение, отключение и жизненный цикл инстанса

Создайте инстанс через New Instance; Редактируйте его со строки. Каждое сохранение перевалидирует форму и (для управляемых коннекторов) перепровизионирует коллектор.
Active (в Advanced Settings) — главный выключатель: неактивный инстанс никогда не опрашивается и исключён из выбора команд. Use by default и Auto enrichment дополнительно ограничивают, могут ли команды и автоматическое обогащение его выбирать.
Удалите инстанс со строки (с подтверждением). Чтобы удалить целый тип коннектора, нужно сначала удалить его инстансы — иначе платформа блокирует удаление типа («Delete all integration instances first»).
Строка инстанса показывает живое здоровье: бейдж circuit-breaker появляется, когда коннектор перестаёт отвечать (◐ Half-open, пока он тестирует восстановление, ○ Open, когда он падает, с попыткой авто-восстановления каждые 30 секунд), а измеритель rate-limit показывает использование запросов относительно настроенного окна. Пока любой брейкер открыт, таблица обновляется автоматически каждые 30 секунд.

2.11. От fetch к кейсу — как события попадают в конвейер

Когда fetch-включённый инстанс опрашивает, возвращаемые им события не становятся кейсами напрямую. Планировщик передаёт их конвейеру ingest через RabbitMQ: возвращённые инциденты публикуются на exchange soar.ingest, воркер ingest персистит каждый в PostgreSQL (создавая кейс) и пишет строки outbox, которые распространяют его дальше. Классификация и маппинг полей — классификатор и входящий маппер инстанса — применяются вдоль этого пути, поэтому корректная их привязка (§2.6) важна. Полная архитектура ingest разобрана в Главе 1; здесь достаточно знать, что коннектор никогда не пишет кейсы прямо в базу данных — всё идёт через очередь ingest.

2.12. Проверка, что данные идут

После включения fetch проверяйте сквозь, а не доверяйте форме:

Строка инстанса. Колонка Automation должна читаться как Ready с тегом Polling и тегом интервала/max ({interval}m / {max}); бейдж circuit breaker показываться не должен.
Протестируйте инстанс (§2.8) на зелёное подключение.
Список Cases. Новые кейсы должны появляться в каденции опроса. Их тип инцидента должен совпадать с вашей привязкой classifier/fallback.
Превью живых событий. «Pull from live events» в редакторе Classification читает самые свежие события прямо из инстанса — быстрый способ подтвердить, что источник возвращает данные, и увидеть точный JSON, с которым будут работать ваш классификатор и маппер (разбирается в Главе 3).

2.13. Webhook'и и почта — альтернативные точки входа

Коннектор — правильный инструмент, когда SOARForge должен тянуть из системы (опрашивать API или ящик) или проталкивать команды в неё. Два соседа в разделе Integrations покрывают случаи, которые коннектор не покрывает:

Webhooks (/settings/webhooks, права webhooks.view / webhooks.manage) — для случая, когда внешняя система может протолкнуть к вам: она вызывает URL SOARForge, чтобы создать кейс или запустить плейбук, без опрашивающего коннектора посередине. Выбирайте webhook, когда источник эмитит события, но у вас нет fetch-интеграции для него, или когда push в near-real-time лучше интервального опроса. См. гайд администратора §2.3.
Mail Sender (/settings/mail-sender, право settings.view) — это исходящее направление: он выбирает, какой инстанс коннектора отправляет системную почту (алерты SLA, уведомления, отчёты). Настраивайте его, когда платформе нужно отправлять почту, а не получать. См. гайд администратора §2.4. (Входящая почта как источник алертов — это обычный Email-коннектор — §2.6.)

Распространённые ошибки

Нет fallback incident type. При включённом fetch Fallback incident type обязателен — без него сохранение блокируется. В рантайме, если классификатор прикреплён, но ни одно правило не совпало (или классификатора нет), кейс получает fallback-тип. Задайте разумный fallback, чтобы ничто не попадало без категории.
Неверная привязка classifier/mapper. Классификатор определяет тип; входящий маппер формирует поля. Привяжите оба и добавляйте ветки для конкретных типов внутри одного входящего маппера, а не создавайте отдельный маппер на каждый тип — редактор предупреждает против последнего.
Путаница fetch interval с батчем/lookback. Fetch interval — только каденция (минуты). Размер батча (max_fetch) и начальный lookback (first_fetch) живут в секции схемы Collect. Новый инстанс без чекпоинта и без окна first-fetch может стартовать «с сейчас» и вернуть ничего на первых опросах — задайте окно first-fetch, если нужна история.
Инстанс, который «Ready», но не работает. Ready отражает учётные данные и провизионирование, а не активность. Если Active выключен, планировщик его не опросит, а если выключен Use by default, команды и Action плейбука его не выберут.
Секреты тихо сохраняются. Редактируя инстанс и оставив пароль пустым, вы сохраняете сохранённый секрет — он не очищается. Чтобы ротировать учётные данные, наберите новое значение явно.
Сохранение управляемого коннектора падает. Управляемые коннекторы требуют уникальный, без пробелов Source Instance Key и Fallback incident type; без любого из них сохранение отклоняется.
«No commands available» / Test только с метаданными. Оба означают, что интеграция не загружена в рантайм — обычно кастомный пак, который так и не установили как артефакт, или sourceKey, не совпадающий с пакетом рантайма. Установите/проверьте пак, затем перетестируйте.
Коннекторы Threat Intel / AI Provider выглядят «пустыми». Они намеренно опускают элементы fetch, classifier и mapper — это коннекторы «по запросу». Чтобы включить источник Threat Intel в автоматическое обогащение, оставьте Auto enrichment включённым в Advanced Settings.
Circuit breaker открыт. Бейдж ○ Open означает, что интеграция перестала отвечать; SOARForge пытается восстановиться каждые 30 секунд, и таблица авто-обновляется в этой каденции. Устойчивый Open обычно указывает на просроченные учётные данные, сетевой путь или простой эндпоинта — запустите Test, чтобы увидеть подлежащую ошибку.