API Weblock.

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

Server URL (базовый путь): http://waf.weblock.ru:1080/

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

Примечание

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

Эндпоинты oauth2

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

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

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

POST: oidc/oauth2/token

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

Тип данных

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

Описание

grant_type

string

*

Тип доступа

client_id

string

*

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

username

string

*

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

password

string

*

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

client_secret

string

*

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

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

{
    "grant_type": "password",
    "client_id": "waf-oidc",
    "username": "admin",
    "password": "Waf12345!",
    "client_secret": "secret"
}

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

Тип данных

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

Описание

access_token

string

*

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

200 OK

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

400 Error

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

403 Error

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

404 Error

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

409 Error

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

500 Error

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

Эндпоинты clusters

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

Authorization: Bearer $AccessToken

Content-Type: application/json

Пример.

--header 'authorization: Bearer eyJraWQiOiIwODM4MTAzZC1hZmM4LTRi'

Конец примера.

$AccessToken генерируется эндпоинтом oidc/oauth2/token «Получение AccessToken».

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

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

GET: controller/v1/clusters

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

-

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

servers

object[]

-

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

modsecurityConfigurations

object[]

-

Конфигурация правил

allowedKeys

string[]

-

Ключи доступа

licenceId

integer

-

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

agentApplied

boolean

-

Флаг агента

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

[ {
    "id": 0,
    "clusterName": "string",
    "passiveMode": true,
    "tenantId": "string",
    "servers": [ {
        "serverIndex": 1,
        "serverName": "server name",
        "modsec": {
            "passiveMode": true,
            "skipModSecurity": true,
            "configs": [ {
              "id": 0,
              "name": "string"
            } ]
        },
        "antiDdos": {
            "mode": "DISABLED",
            "initialScore": 0,
            "cost": 0,
            "postCost": 0,
            "patchCost": 0,
            "putCost": 0,
            "deleteCost": 0,
            "otherCost": 0,
            "errorCost": 0
        },
        "settings": {
            "logLevel": "INFO",
            "logBanlimBlockedRequests": true
        },
        "failToBanConfigurations": [ {
            "id": 1,
            "key": "string",
            "rejectCount": 10,
            "rejectCountStrict": 5,
            "banTime": 0,
            "antiDdosScoreExceedCountStrict": 0,
            "antiDdosScoreExceedCountBan": 0,
            "antiDdosNewCookieStrict": 0,
            "antiDdosNewCookieBan": 0
        } ],
        "requestsLimitConfigurations": [ {
            "id": 0,
            "key": "string",
            "rate": 0,
            "burst": 0,
            "delay": 0,
            "dryRun": true,
            "statusCode": 0
        } ],
        "locations": [ {
            "locationIndex": 0,
            "path": "string",
            "captcha": true,
            "proxyPass": true,
            "captchaValidator": true,
            "antiDdos": {
                "cost": 0,
                "postCost": 0,
                "patchCost": 0,
                "putCost": 0,
                "deleteCost": 0,
                "otherCost": 0,
                "errorCost": 0
            },
            "modsec": {
                "skipModSecurity": true,
                "passiveMode": true
            },
            "requestsLimitConfigurations": [ {
                "id": 0,
                "key": "string",
                "rate": 0,
                "burst": 0,
                "delay": 0,
                "dryRun": true,
                "statusCode": 0
            } ]
        } ]
    } ],
    "modsecurityConfigurations": [ {
        "id": 0,
        "name": "string"
    } ],
    "allowedKeys": ["string"],
    "licenceId": 0,
    "agentApplied": true
} ]

400 Error

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

403 Error

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

404 Error

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

409 Error

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

500 Error

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

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

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

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

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

Тип данных

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

Описание

clusterId

integer

*

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

serverIndex

integer

*

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

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

Тип данных

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

Описание

logBanlimBlockedRequests

boolean

*

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

logAllRequests

boolean

*

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

logLevel

enum

-

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

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

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

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

Тип данных

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

Описание

logLevel

enum

-

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

logBanlimBlockedRequests

boolean

-

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

logAllRequests

boolean

-

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

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

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

400 Error

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

403 Error

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

404 Error

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

409 Error

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

500 Error

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

Эндпоинты logs

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

Authorization: Bearer $AccessToken

Content-Type: application/json

Пример.

--header 'authorization: Bearer eyJraWQiOiIwODM4MTAzZC1hZmM4LTRi'

Конец примера.

$AccessToken генерируется эндпоинтом oidc/oauth2/token «Получение AccessToken».

Получение отчета - logs/intervention/report

Формирование и получение отчета.

POST: controller/v1/logs/intervention/report

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

Тип данных

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

Описание

clusterId

integer

*

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

filters

object[][]

-

Фильтры

filters.field

enum

-

Поле. Перечень значений: clusterId, clusterName, instanceId, serverId, requestId, clientIp, hostname, timestamp, isBlocked, maxSeverity, minSeverity, severity, ruleId, uri, statusCode, tags.

filters.value

string

-

Значение

filters.operator

enum

-

Оператор. Перечень значений: contains, equal, greater, greaterEqual, less, lessEqual, notContains.

orders

object[]

-

Сортировка результата

orders.field

enum

-

Поле. Перечень значений: clusterId, clusterName, instanceId, serverId, requestId, clientIp, hostname, timestamp, isBlocked, maxSeverity, minSeverity, severity, ruleId, uri, statusCode, tags.

orders.direction

enum

-

Вид сортировки. Перечень значений: ASC, DESC.

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

{
    "clusterId": 0,
    "filters": [
        [
            {
                "field": "clusterName",
                "value": "string",
                "operator": "equal"
            }
        ]
    ],
    "orders": [
        {
            "field": "clusterName",
            "direction": "ASC"
        }
    ]
}

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

Тип данных

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

Описание

instanceId

string

-

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

serverId

integer

-

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

requestId

string

-

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

hostname

string

-

IP-адрес хоста

clientIp

string

-

IP-адрес клиента

interventions

object[]

-

Данные атак

interventions.id

integer

-

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

interventions.statusCode

integer

-

Код статуса

interventions.ruleId

integer

-

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

interventions.timestamp

integer

-

Дата, время

interventions.rev

string

-

-

interventions.message

string

-

Информация

interventions.data

string

-

Тело атаки

interventions.severity

integer

-

Критичность (фактор риска)

interventions.ver

string

-

Версия защиты от атак

interventions.maturity

integer

-

Уровень зрелости

interventions.accuracy

integer

-

Точность

interventions.uri

string

-

URI запроса

interventions.passive

boolean

-

Режим работы правил ModSecurity

interventions.tags

string[]

-

Список тегов

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

[
    {
        "instanceId": "string",
        "serverId": 0,
        "requestId": "string",
        "hostname": "string",
        "clientIp": "string",
        "interventions": [
            {
                "id": 0,
                "statusCode": 0,
                "ruleId": 0,
                "timestamp": 0,
                "rev": "string",
                "message": "string",
                "data": "string",
                "severity": 0,
                "ver": "string",
                "maturity": 0,
                "accuracy": 0,
                "uri": "string",
                "passive": true,
                "tags": ["string"]
            }
        ]
    }
]

400 Error

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

403 Error

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

404 Error

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

409 Error

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

500 Error

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

Коды ролей и разрешений для эндпоинтов

Код роли применяется в API. По умолчанию задано три роли:

Роль

Код роли

Администратор (ADMIN)

ROLE_ADMIN

Оператор (OPERATOR)

ROLE_OPERATOR

Аудитор (READ_ONLY)

ROLE_READ_ONLY

Каждой роли назначаются разрешения. Каждое разрешение позволяет использовать набор эндпоинтов, приведенный в таблице ниже.

Существует ограничение назначения разрешений для роли. Пользователь не сможет быть добавлен в тенант, если его роли назначено хотя бы одно из следующих разрешений:

  • ROLE_EDIT (код разрешения) – Администрирование ролей (название разрешения),

  • TENANT_EDIT – Администрирование тенантов.

Таблица соответствия эндпоинтов и кодов разрешений представлена ниже.

Метод

Эндпоинт

USER_ADMIN (код разрешения)

POST

/api/v1/users

POST

/api/v1/users/create

GET

/api/v1/users/{id}

POST

/api/v1/users/update

PATCH

/api/v1/users/{id}/password

POST

/api/v1/users/disable

POST

/api/v1/users/enable

POST

/api/v1/users/delete

POST

/api/v1/users/mfa-disable

USER_SEARCH

POST

/api/v1/users

ROLE_EDIT

GET

/api/v1/roles

POST

/api/v1/roles/create

POST

/api/v1/roles/update

DELETE

/api/v1/roles/delete/{id}

ROLE_VIEW

GET

/api/v1/roles

USER_SESSION_VIEW

GET

/api/v1/sessions

SELF_MANAGEMENT

POST

/api/v1/users/current

PATCH

/api/v1/users/current/password

PATCH

/api/v1/users/current/mfa/generate

PATCH

/api/v1/users/current/mfa/enable

PATCH

/api/v1/users/current/mfa/disable

POST

/api/v1/parameters/types

GET

/api/v1/parameters

POST

/api/v1/parameters/{parameterId}

INTERVENTION_NOTIFICATION_EDIT

POST

/v1/schedule/intervention/notification

GET

/v1/schedule/intervention/notification

POST

/v1/schedule/intervention/notification/test

INTERVENTION_NOTIFICATION_VIEW

GET

/v1/schedule/intervention/notification

POST

/v1/schedule/intervention/notification/test

INTEGRATION_TOKEN_EDIT

POST

/api/v1/users/generate-token

DELETE

/api/v1/users/delete-token/{id}

CLUSTER_ADMIN

GET

/v1/instances

GET

/v1/instances/{instanceId}

POST

/v1/logs/intervention/filter

POST

/v1/logs/intervention/filter/count

GET

/v1/clusters

GET

/v1/clusters/{clusterId}

GET

/v1/clusters/{clusterId}/modsec

POST

/v1/clusters/{clusterId}/modsec/{index}

GET

/v1/modsec/{ruleId}

GET

/v1/configurations/modsec/{configId}

GET

/v1/clusters/{clusterId}/server/{serverIndex}/modsec

GET

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban

POST

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/{key}/whitelist/add

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/{key}/whitelist

POST

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/{key}/strictlist/add

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/{key}/strictlist

POST

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/{key}/banlist/add

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/{key}/banlist

POST

/v1/clusters/events

POST

/v1/user-service/token

GET

/v1/user-service/token/check

GET

/v1/clusters/info

GET

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges

GET

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges/mode

POST

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges/add

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges/delete

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges/delete/all

GET

/v1/clusters/{clusterId}/license

PATCH

/v1/clusters/{clusterId}/license

PATCH

/v1/clusters/{clusterId}/license/set

PATCH

/v1/clusters/{clusterId}/license/reset

PATCH

/v1/clusters/{clusterId}/license/update

POST

/v1/clusters/{clusterId}/mode

DELETE

/v1/clusters/{clusterId}

GET

/v1/clusters/{clusterId}/server/{serverIndex}

GET

/v1/clusters/{clusterId}/server/{serverIndex}/refresh

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}

GET

/v1/clusters/{clusterId}/reset

GET

/v1/clusters/{clusterId}/server/{serverIndex}/requests-limit

GET

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/requests-limit

CLUSTER_VIEW

GET

/v1/instances

GET

/v1/instances/{instanceId}

POST

/v1/logs/intervention/filter

POST

/v1/logs/intervention/filter/count

GET

/v1/clusters

GET

/v1/clusters/{clusterId}

GET

/v1/clusters/{clusterId}/server/{serverIndex}

GET

/v1/clusters/{clusterId}/server/{serverIndex}/refresh

GET

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban

GET

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/whitelist

GET

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/strictlist

GET

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/banlist

POST

/v1/clusters/events

GET

/v1/clusters/{clusterId}/modsec

GET

/v1/modsec/{ruleId}

GET

/v1/configurations/modsec/{configId}

GET

/v1/clusters/{clusterId}/server/{serverIndex}/modsec

GET

/v1/clusters/info

GET

/v1/clusters/{clusterId}/server/{serverIndex}/requests-limit

GET

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/requests-limit

GET

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges

CLUSTER_USER_EDIT

GET

/v1/clusters/{clusterId}/users

POST

/v1/clusters/{clusterId}/add-users

POST

/v1/clusters/{clusterId}/remove-users

CLUSTER_USER_VIEW

GET

/v1/clusters/{clusterId}/users

CLUSTER_ML_MANAGE

POST | /v1/ml/clusters/{clusterId}/force-start-learning

POST

/v1/ml/clusters/{clusterId}/force-switch-predict

CLUSTER_MODSEC_EDIT

GET

/v1/clusters/{clusterId}/modsec/raw

GET

/v1/clusters/{clusterId}/server/{serverIndex}/modsec/raw

POST

/v1/clusters/{clusterId}/modsec

POST

/v1/clusters/{clusterId}/server/{serverIndex}/modsec

POST

/v1/clusters/{clusterId}/modsec/send

POST

/v1/clusters/{clusterId}/modsec/{index}

POST

/v1/modsec/{ruleId}

POST

/v1/configurations/modsec/{configId}

DELETE

/v1/configurations/modsec/{configId}

POST

/v1/configurations/modsec/{configId}/add

GET

/v1/configurations/modsec/{configId}}/rules

POST

/v1/configurations/modsec/{configId}/rulesByIndex/{index}

POST

/v1/configurations/modsec/{configId}/rulesById/{ruleId}

DELETE

/v1/modsec/{ruleId}

DELETE

/v1/configurations/modsec/{configId}/rules/{index}

GET

/v1/configurations/modsec/{configId}/settings

GET

/v1/configurations/modsec/{configId}/settings

CLUSTER_MODSEC_VIEW

GET

/v1/configurations/modsec/{configId}/rules

GET

/v1/clusters/{clusterId}/modsec/raw

GET

/v1/clusters/{clusterId}/server/{serverIndex}/modsec/raw

GET

/v1/configurations/modsec/{configId}/settings

CLUSTER_CRS_EDIT

POST

/v1/clusters/{clusterId}/modsec/setup_crs

POST

/v1/clusters/{clusterId}/server/{serverIndex}/modsec/setup_crs

CLUSTER_SERVER_EDIT

POST

/v1/clusters/{clusterId}/server/{serverIndex}/anti-ddos

GET

/v1/clusters/{clusterId}/server/{serverIndex}/anti-ddos

POST

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/anti-ddos

GET

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/anti-ddos

GET

/v1/clusters/{clusterId}/server/{serverIndex}/locations

GET

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/modsec-config

POST

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/modsec-config

GET

/v1/clusters/{clusterId}/server/{serverIndex}/modsec-config

POST

/v1/clusters/{clusterId}/server/{serverIndex}/modsec-config

GET

/v1/clusters/{clusterId}/server/{serverIndex}/configuration

POST

/v1/clusters/{clusterId}/server/{serverIndex}/configuration

GET

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges/mode

POST

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges/add

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges/delete

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/ip-ranges/delete/all

POST

/v1/clusters/{clusterId}/server/{serverIndex}/requests-limit/add

POST

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/requests-limit/add

POST

/v1/clusters/{clusterId}/server/{serverIndex}/requests-limit

POST

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/requests-limit

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/requests-limit/{key}

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/location/{locationIndex}/requests-limit/{key}

CLUSTER_FAIL_TO_BAN_EDIT

POST

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/add

POST

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban

DELETE

/v1/clusters/{clusterId}/server/{serverIndex}/fail_to_ban/{key}

PATTERNS_EDIT

PATCH

/api/v1/patterns/update

POST

/api/v1/patterns

DELETE

/api/v1/patterns/{patternId}

GET

/api/v1/patterns

GET

/api/v1/patterns/all

PATTERNS_VIEW

GET

/api/v1/patterns

GET

/api/v1/patterns/all

TENANT_EDIT

GET

/api/v1/tenants

POST

/api/v1/tenants/create

POST

/api/v1/tenants/update

POST

/api/v1/tenants/{id}/add-users

POST

/api/v1/tenants/{id}/remove-users

GET

/api/v1/tenants/{id}/users

PATCH

/v1/clusters/tenant/set

PATCH

/v1/clusters/tenant/remove

TENANT_VIEW

GET

/api/v1/tenants

INTERVENTION_VIEW

GET

/v1/logs/request

INTERVENTION_DASHBOARD_VIEW

POST

/v1/dashboard/counter

POST

/v1/dashboard/severity

POST

/v1/dashboard/popular_ip

POST

/v1/dashboard/popular_user_agent

POST

/v1/dashboard/popular_attack_type

INTERVENTION_REPORT_VIEW

POST

/v1/logs/intervention/report

COMMON_LOG_RECORD_VIEW

GET

/v1/logs/common
../_images/Weblock_Logos_small.png