Спецификация API Weblock.

API обеспечивает интеграцию «Weblock.» с другими системами. Спецификация API «Weblock.» доступна в автодокументации. Здесь приведена спецификация отдельных эндпоинтов, которые упоминаются в данной документации.

Server URL (базовый путь) - IP-адрес или доменное имя установленного «Weblock.» с указанием порта.

Например, http://domain:1080/

Для работы с API потребуется AccessToken, который генерируется эндпоинтом oidc/oauth2/token либо в Личном кабинете (подробнее Токены).

Примечание

Все значения типа string имеют максимальную длину 250 символов.


Получение AccessToken - token

Генерация токена доступа.

POST: oidc/oauth2/token

Параметр заголовка Content-Type: application/x-www-form-urlencoded

Параметр тела запроса

Тип данных

Обязательность

Описание

grant_type

string

*

Тип доступа

client_id

string

*

Идентификатор пользователя

username

string

*

Имя пользователя

password

string

*

Пароль пользователя

client_secret

string

*

Одноразовый пароль пользователя

Пример запроса:

$ curl --request POST --url http://domain:1080/oidc/oauth2/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=password" --data "username=admin" --data "password=Waf12345!" \
--data "client_id=waf-oidc" --data "client_secret=secret"

Параметр ответа

Тип данных

Обязательность

Описание

access_token

string

*

Токен доступа

200 OK

Пример ответа: "access_token": "eyJraWQiOiIwODM4MTAzZC1hZmM4LTRi"

400 Error

Максимальная длина 250 символов

403 Error

Доступ запрещен

404 Error

Значения параметров не соответствуют схеме

409 Error

Несовместимость запросов

500 Error

Сервер не может обработать запрос


Чтение данных кластеров - clusters

Чтение данных всех кластеров, в том числе идентификаторов кластеров и серверов. Чтение данных кластеров для заданного тенанта, либо для всех тенантов.

GET: controller/v1/clusters

Параметры заголовка:

Authorization: Bearer $AccessToken

Content-Type: application/json

Пример заголовка:

--header 'authorization: Bearer eyJraWQiOiIwODM4MTAzZC1hZmM4LTRi'

Query-параметр запроса

Тип данных

Обязательность

Описание

tenantId

string

-

Идентификатор тенанта

Примеры запроса:

controller/v1/clusters

или

controller/v1/clusters?tenantId=TENANT_A

где TENANT_A - ID тенанта.

Параметр ответа 200 OK

Тип данных

Описание

id

integer

Идентификатор кластера

clusterName

string

Имя кластера

passiveMode

boolean

Флаг пассивного режима кластера

tenantId

string

Идентификатор тенента

clientId

string

Идентификатор лицензии

agentApplied

boolean

Флаг агента

clusterKeysStatus

enum

Режим работы набора правил. Перечень значений: «IN_WORK», «MISMATCHED_KEYS», «MISMATCHED_DOMAIN_NAMES»

allowedKeys

enum[]

Набор F2B ключей. Перечень значений: «$remote_addr», «$binary_remote_addr», «$server_name», «$request_method», «$http_user_agent», «$http_authorization»

servers

object[]

Данные серверов

servers.serverIndex

integer

Индекс сервера

servers.serverName

string

Имя сервера

servers.passiveMode

boolean

Флаг пассивного режима сервера

servers.serverPorts

string[]

Порты сервера

Пример ответа 200 OK:

[
   {
     "id": 42,
     "clusterName": "string",
     "passiveMode": true,
     "tenantId": "TENANT_1",
     "clientId": "4242",
     "agentApplied": true,
     "clusterKeysStatus": "IN_WORK",
     "allowedKeys": [
       "$remote_addr"
     ],
     "servers": [
       {
         "serverIndex": 0,
         "serverName": "string",
         "passiveMode": true,
         "serverPorts": [
           "string"
         ]
       }
     ]
   }
]

400 Error

Максимальная длина 250 символов

403 Error

Доступ запрещен

404 Error

Значения параметров не соответствуют схеме

409 Error

Несовместимость запросов

500 Error

Сервер не может обработать запрос


Настройка уровня фиксации сообщений - clusters/{clusterId}/server/{serverIndex}/configuration

Фиксация критичных сообщений.

POST: controller/v1/clusters/{clusterId}/server/{serverIndex}/configuration

Параметры заголовка:

Authorization: Bearer $AccessToken

Content-Type: application/json

Параметр адресной строки запроса

Тип данных

Обязательность

Описание

clusterId

integer

*

Идентификатор кластера

serverIndex

integer

*

Идентификатор сервера

Параметр тела запроса

Тип данных

Обязательность

Описание

logBanlimBlockedRequests

boolean

*

Флаг логирования запросов, заблокированных функционалом «F2B» и «Лимиты»

logAllRequests

boolean

*

Флаг логирования запросов, заблокированных любым функционалом защиты

logLevel

enum

*

Уровень фиксации сообщений. Перечень значений: «EMERGENCY», «ALERT», «CRITICAL», «ERROR», «WARNING», «NOTICE», «INFO», «DEBUG»

logRequestBody

boolean

*

Флаг логирования тела запроса

banSync

boolean

-

Флаг синхронизации блокировок

Пример тела запроса:

{
    "logBanlimBlockedRequests": true,
    "logAllRequests": true,
    "logLevel": "ERROR",
    "logRequestBody": true,
    "banSync": true
}

Параметр ответа 200 OK

Тип данных

Описание

result

enum

Тип результата. Перечень значений: «COMPLETED», «PARTIAL», «ERROR»

content

object

Параметры

content.logLevel

enum

Уровень фиксации сообщений. Перечень значений: «EMERGENCY», «ALERT», «CRITICAL», «ERROR», «WARNING», «NOTICE», «INFO», «DEBUG»

content.logBanlimBlockedRequests

boolean

Флаг логирования запросов, заблокированных функционалом «F2B» и «Лимиты»

content.logAllRequests

boolean

Флаг логирования запросов, заблокированных любым функционалом защиты

content.logRequestBody

boolean

Флаг логирования тела запроса

content.banSync

boolean

Флаг синхронизации блокировок

error

object

Данные ошибки

Пример ответа 200 OK:

{
  "result": "COMPLETED",
  "content": {
    "logLevel": "INFO",
    "logBanlimBlockedRequests": true,
    "logAllRequests": true,
    "logRequestBody": true,
    "banSync": true
  },
  "error": {
    "code": "42.42.42",
    "description": "No active instances",
    "details": [
      {
        "node": {},
        "error": {
          "description": "string",
          "messages": [
            {
              "time": "2024-01-08T07:09:39Z",
              "level": "ERROR",
              "type": "ANTI_DDOS_MODULE",
              "serverIndex": 0,
              "message": "Some log message"
            }
          ]
        }
      }
    ],
    "differentContent": {
      "additionalProp1": [
        {
          "content": {},
          "workers": [
            {
              "clusterName": "some_cluster",
              "instanceId": "a1b2c3",
           "workerProcessId": 42
            }
          ]
        }
      ],
      "additionalProp2": [
        {
          "content": {},
          "workers": [
            {
              "clusterName": "some_cluster",
              "instanceId": "a1b2c3",
             "workerProcessId": 42
            }
          ]
        }
      ],
      "additionalProp3": [
        {
          "content": {},
          "workers": [
            {
              "clusterName": "some_cluster",
              "instanceId": "a1b2c3",
             "workerProcessId": 42
            }
          ]
        }
      ]
    }
  }
}

400 Error

Максимальная длина 250 символов

403 Error

Доступ запрещен

404 Error

Значения параметров не соответствуют схеме

409 Error

Несовместимость запросов

500 Error

Сервер не может обработать запрос


Добавление правила в набор - configurations/modsec/{configId}/add

Добавление нового правила в набор.

POST: controller/v1/configurations/modsec/{configId}/add

Параметры заголовка:

Authorization: Bearer $AccessToken

Content-Type: application/json

Параметр адресной строки запроса

Тип данных

Обязательность

Описание

configId

integer

*

Идентификатор набора правил

Параметр тела запроса

Тип данных

Обязательность

Описание

content

string

*

Код правила

passive

boolean

-

Флаг пассивного режима

Пример тела запроса:

{
  "content": "string",
  "passive": true
}

Параметр ответа 200 OK

Тип данных

Описание

-

const[]

Тип результата

Пример ответа 200 OK:

[true]

400 Error

Максимальная длина 250 символов

403 Error

Доступ запрещен

404 Error

Значения параметров не соответствуют схеме

409 Error

Несовместимость запросов

500 Error

Сервер не может обработать запрос


Активация изменений правил - clusters/{clusterId}/modsec/send

Активация изменений правил.

POST: controller/v1/clusters/{clusterId}/modsec/send

Параметры заголовка:

Authorization: Bearer $AccessToken

Content-Type: application/json

Параметр адресной строки запроса

Тип данных

Обязательность

Описание

clusterId

integer

*

Идентификатор кластера

Параметр ответа 200 OK

Тип данных

Описание

result

enum

Тип результата. Перечень значений: «COMPLETED», «PARTIAL», «ERROR»

content

string

Результат активации

error

object

Данные ошибки

Пример ответа 200 OK:

{
  "result": "true",
  "content": "true",
  "error": {
    "code": "42.42.42",
    "description": "No active instances",
    "details": [
      {
        "node": {},
        "error": {
          "description": "string",
          "messages": [
            {
              "time": "2024-01-08T07:09:39Z",
              "level": "ERROR",
              "type": "ANTI_DDOS_MODULE",
              "serverIndex": 0,
              "message": "Some log message"
            }
          ]
        }
      }
    ],
    "differentContent": {
      "additionalProp1": [
        {
          "content": {},
          "workers": [
            {
              "clusterName": "some_cluster",
              "instanceId": "a1b2c3",
             "workerProcessId": 42
            }
          ]
        }
      ],
      "additionalProp2": [
        {
          "content": {},
          "workers": [
            {
              "clusterName": "some_cluster",
              "instanceId": "a1b2c3",
             "workerProcessId": 42
            }
          ]
        }
      ],
      "additionalProp3": [
        {
          "content": {},
          "workers": [
            {
              "clusterName": "some_cluster",
              "instanceId": "a1b2c3",
             "workerProcessId": 42
            }
          ]
        }
      ]
    }
  }
}

400 Error

Максимальная длина 250 символов

403 Error

Доступ запрещен

404 Error

Значения параметров не соответствуют схеме

409 Error

Несовместимость запросов

500 Error

Сервер не может обработать запрос


Чтение набора правил - configurations/modsec/{configId}/rules

Чтение набора правил.

GET: controller/v1/configurations/modsec/{configId}/rules

Параметры заголовка:

Authorization: Bearer $AccessToken

Content-Type: application/json

Параметр адресной строки запроса

Тип данных

Обязательность

Описание

configId

integer

*

Идентификатор набора правил

Query-параметр запроса

Тип данных

Обязательность

Описание

page

integer

*

Номер страницы выдачи

size

integer

*

Количество элементов на странице

sort

string

-

Поле и его сортировка

Примеры запроса:

controller/v1/configurations/modsec/1/rules?page=0&size=10&sort=ruleId,ASC

или

controller/v1/configurations/modsec/1/rules?page=0&size=10

Параметр ответа 200 OK

Тип данных

Описание

totalElements

integer

Всего элементов

totalPages

integer

Всего страниц

last

boolean

Флаг выдачи последней страницы

size

integer

Количество элементов на странице

content

оbject[]

Список правил

content.ruleId

integer

Идентификатор правила

content.index

integer

Индекс правила

content.content

string

Код правила

content.passive

boolean

Флаг пассивного режима

content.deleted

boolean

Флаг удаления

content.configId

integer

Идентификатор набора правил

number

integer

Номер страницы

sort

object

Сортировка

numberOfElements

integer

Количество элементов в списке

pageable

object

Данные страницы

empty

boolean

Флаг пустого списка

Пример ответа 200 OK:

{
  "totalElements": 0,
  "totalPages": 0,
  "first": true,
  "last": true,
  "size": 0,
  "content": [
    {
       "ruleId": 1800000,
       "index": 0,
       "content": "SecRule …",
       "passive": false,
       "deleted": false,
       "configId": 503
    }
  ],
  "number": 0,
  "sort": {
    "empty": true,
    "sorted": true,
    "unsorted": true
  },
  "numberOfElements": 0,
  "pageable": {
    "offset": 0,
    "sort": {
      "empty": true,
      "sorted": true,
      "unsorted": true
    },
    "pageSize": 0,
    "pageNumber": 0,
    "paged": true,
    "unpaged": true
  },
  "empty": true
}

400 Error

Максимальная длина 250 символов

403 Error

Доступ запрещен

404 Error

Значения параметров не соответствуют схеме

409 Error

Несовместимость запросов

500 Error

Сервер не может обработать запрос


Удаление правила - configurations/modsec/{configId}/rules/{index}

Удаление правила по индексу.

DELETE: controller/v1/configurations/modsec/{configId}/rules/{index}

Параметры заголовка:

Authorization: Bearer $AccessToken

Content-Type: application/json

Параметр адресной строки запроса

Тип данных

Обязательность

Описание

configId

integer

*

Идентификатор набора правил

index

integer

*

Индекс правила

Параметр ответа 200 OK

Тип данных

Описание

-

const

Результат удаления

Пример ответа 200 OK:

true

400 Error

Максимальная длина 250 символов

403 Error

Доступ запрещен

404 Error

Значения параметров не соответствуют схеме

409 Error

Несовместимость запросов

500 Error

Сервер не может обработать запрос


Изменение правила - configurations/modsec/{configId}/rulesByIndex/{index}

Изменение правила по индексу.

POST: controller/v1/configurations/modsec/{configId}/rulesByIndex/{index}

Параметры заголовка:

Authorization: Bearer $AccessToken

Content-Type: application/json

Параметр адресной строки запроса

Тип данных

Обязательность

Описание

configId

integer

*

Идентификатор набора правил

index

integer

*

Индекс правила

Параметр тела запроса

Тип данных

Обязательность

Описание

index

integer

-

Новый индекс правила

content

string

*

Код правила

passive

boolean

*

Флаг пассивного режима

Пример тела запроса:

{
  "index": 0,
  "content": "string",
  "passive": true
}

Параметр ответа 200 OK

Тип данных

Описание

-

const

Результат изменения

Пример ответа 200 OK:

true

400 Error

Максимальная длина 250 символов

403 Error

Доступ запрещен

404 Error

Значения параметров не соответствуют схеме

409 Error

Несовместимость запросов

500 Error

Сервер не может обработать запрос


../_images/Weblock_Logos_small.png