Спецификация 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 |
Пример ответа: |
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 |
Сервер не может обработать запрос |
