ICAP через API

Описание ICAP-сервера и блока ICAP/DLP-анализа доступно через REST API. Набор операций тот же, что и в интерфейсе, плюс параметр, которого в интерфейсе нет: выключение ICAP-сервера.

Запросы отправляйте на адрес сервера бэкенда, токен передавайте в заголовке Authorization:

POST /api/v1/clusters/{clusterId}/icap-profiles
Authorization: Bearer <токен>
Content-Type: application/json

Методы

Идентификатор кластера clusterId — имя кластера балансировки, идентификаторы profileId и serviceId — UUID из ответа о создании.

ICAP-сервер

Поля профиля

Обязательные поля: name, reqmod_url, enabled. Остальные можно не передавать.

• name — название ICAP-сервера, от 1 до 255 символов, уникально в кластере.
• description — описание, до 255 символов.
• reqmod_url — адрес проверки запросов, до 2048 символов, только схема icap:// с путём службы.
• respmod_url — адрес проверки ответов, до 2048 символов. Пустое значение означает, что передача ответов недоступна.
• auth_type — тип авторизации: none, basic или bearer, по умолчанию none.
• username — логин для basic, до 1024 символов. Символ : не допускается.
• password — пароль для basic, до 8192 символов. В ответе не возвращается.
• token — токен для bearer, до 8192 символов. В ответе не возвращается.
• enabled — включён ли ICAP-сервер.

Создание профиля DLP-системы с проверкой запросов и ответов:

{
  "name": "dlp-basic",
  "description": "Основная DLP-система",
  "enabled": true,
  "reqmod_url": "icap://icap-dlp.example:1344/reqmod",
  "respmod_url": "icap://icap-dlp.example:1344/respmod",
  "auth_type": "basic",
  "username": "icap-service",
  "password": "P7-example-secret"
}

Ответ 201 содержит описание созданного профиля: id, cluster_id, name, description, enabled, reqmod_url, respmod_url, auth_type, username, auth_configured, created_at, updated_at, linked_entities. Поле auth_configured сообщает, задан ли секрет для выбранного типа авторизации: у профиля без авторизации оно всегда true, поэтому по нему видно, сохранены ли Пароль или Токен.

Изменение профиля

Метод PUT заменяет значения полей, поэтому передавайте все поля, которые должны остаться, включая enabled. Пустое значение password или token сохраняет прежний секрет, если тип авторизации не менялся. При смене типа авторизации секрет нужно передать заново — без него сервер отвергнет запрос:

{
  "name": "dlp-basic",
  "description": "Основная DLP-система",
  "enabled": true,
  "reqmod_url": "icap://icap-dlp.example:1344/reqmod",
  "respmod_url": "",
  "auth_type": "bearer",
  "token": "P7-example-token"
}

Пустое respmod_url в этом запросе отключает передачу ответов: конфигурации балансировки продолжают ссылаться на профиль, но передача ответов в них работать не будет.

Связанные конфигурации балансировки

Массив linked_entities в ответе GET перечисляет конфигурации балансировки, ссылающиеся на профиль:

Выключение и удаление

Профиль, на который ссылается хотя бы одна конфигурация балансировки, нельзя ни выключить, ни удалить: сервер отвечает кодом 409. Выключение доступно только через API — в интерфейсе профили создаются включёнными. Перед выключением или удалением профиля уберите его из всех конфигураций балансировки кластера.

Выключенный профиль нельзя выбрать в конфигурации балансировки, а сохранение конфигурации, ссылающейся на выключенный профиль, отклоняется.

Проверка доступности

POST /api/v1/clusters/{clusterId}/icap-profiles/{profileId}/healthcheck

Проверка выполняется одновременно с каждого агента кластера в состоянии READY: сначала проверяется reqmod_url, затем respmod_url, если он задан. Метод ничего не меняет и не отвечает ошибкой, когда DLP-система недоступна, — результат передаётся в теле ответа.

Состав элемента массива agents:

Причина в error_type и её расшифровка — в разделе Проверка доступности. Значение status в agents совпадает с меткой Доступен или Недоступен в интерфейсе, а message и details — с текстом в колонке Пояснение.

Инспекция в конфигурации балансировки

Блок ICAP хранится в поле dlp_inspection объекта конфигурации балансировки. Поле одинаково в запросах POST и PUT и в ответе GET. Отсутствие поля означает, что инспекция не настроена.

Поля инспекции

• enabled — включена ли передача трафика на проверку.
• icap_profile_id — идентификатор ICAP-профиля. Обязателен при enabled: true, профиль должен существовать в этом же кластере и быть включён.
• mode — режим инспекции: mirror — асинхронное зеркалирование, inline — синхронная проверка запроса до отправки на клиентский сервер. Обязательное поле: пустое значение отклоняется.
• response_enabled — проверка ответов клиентского сервера, RESPMOD. Допустима только в режиме mirror для L7-протоколов HTTP, HTTPS и gRPC и только если у профиля задан respmod_url.
• timeout_ms — время ожидания вердикта, от 1 до 60000. Если поле не передано, используется 1000, явно переданный 0 отклоняется проверкой диапазона с кодом 422.
• block_status — код ответа клиенту при блокировке, от 200 до 599. Если поле не передано, используется 403, явно переданный 0 отклоняется проверкой диапазона с кодом 422. Учитывается только в режиме inline.

Фильтр проверяемого трафика

Фильтр задаётся объектом scope:

• methods — методы, попадающие на проверку, например ["POST", "PUT"]. Пустой массив — проверяются все методы.
• content_types — типы содержимого, например ["multipart/form-data"]. Пустой массив — проверяются все типы.
• include_paths — пути, для которых выполняется проверка, например ["/upload"]. Пустой массив — проверяются все пути.
• exclude_paths — пути, исключённые из проверки, например ["/health"]. Пустой массив — исключений нет. Путь из обоих списков исключается.
• request_body_limit_kb — порог полной передачи тела запроса, от 1 КБ. Если поле не передано, используется 102400 КБ, явно переданный 0 отклоняется проверкой диапазона с кодом 422. Для конфигураций без L7-протокола это максимальный размер зеркалируемого TCP-потока.
• response_body_limit_kb — порог полной передачи тела ответа, от 1 КБ. Если поле не передано, используется 102400 КБ, явно переданный 0 отклоняется проверкой диапазона с кодом 422.

Пример

Синхронная проверка загрузок с ограничением по методу, типу содержимого и путям:

{
  "dlp_inspection": {
    "enabled": true,
    "icap_profile_id": "019eeec7-b810-7b37-ae4a-b0f5574ee477",
    "mode": "inline",
    "response_enabled": false,
    "timeout_ms": 1500,
    "block_status": 403,
    "scope": {
      "methods": ["POST", "PUT"],
      "content_types": ["multipart/form-data"],
      "include_paths": ["/upload", "/api/documents"],
      "exclude_paths": [],
      "request_body_limit_kb": 20480,
      "response_body_limit_kb": 102400
    }
  }
}

Метод PUT принимает конфигурацию балансировки целиком. Чтобы не потерять остальные настройки, загрузите конфигурацию методом GET, внесите изменения в dlp_inspection и отправьте объект обратно.

Ограничения проверки применяются к dlp_inspection независимо от того, создан объект методом POST или изменён методом PUT. Нарушение любого из них отклоняет сохранение:

Ошибки

Тело ошибки содержит три поля:

Ошибка 422 означает нарушение ограничения из схемы метода, а 400 — нарушение смыслового условия: например, 422 вернётся для block_status вне диапазона 200–599, а 400 — для response_enabled в режиме inline.