Перейти к содержанию

Валарм API

Валарм API обеспечивает взаимодействие компонентов системы Валарм. Вы можете использовать методы Валарм API для добавления, получения или изменения следующих сущностей:

  • уязвимости,

  • атаки,

  • инциденты,

  • пользователи,

  • клиенты,

  • WAF‑ноды и т.д.

Описание методов API доступно в справочнике API по ссылке:

Справочник Валарм API

Конечная точка API

Запросы API отправляются на следующий URL:

Аутентификация в API

Способ аутентификации в API зависит от клиента, с которого отправляется запрос:

  • Из интерфейса справочника API

  • С собственного клиента

Из интерфейса справочника API

Для аутентификации используется токен, полученный после входа в ваш аккаунт Валарм.

  1. Войдите в ваш аккаунт Валарм по ссылке для EU‑облака или для RU‑облака.

  2. Обновите справочник API по ссылке:

  3. Перейдите к нужному методу > секция Try it out, введите значения параметров и выполните запрос.

С собственного клиента

Для аутентификации используются ваши UUID и секретный ключ.

  1. Войдите в ваш аккаунт Валарм по ссылке для EU‑облака или для RU‑облака.

  2. Обновите справочник API по ссылке:

  3. Выполните запрос POST /v1/user из интерфейса справочника API и скопируйте значение параметра uuid из ответа.

  4. Выполните запрос POST /v1/user/renew_secret из интерфейса справочника API и скопируйте значение параметра secret из ответа.

  5. Выполните нужный запрос с собственного клиента, используя полученные значения:

    • uuid в заголовке в параметре X‑WallarmAPI‑UUID,
    • secret в заголовке в параметре X‑WallarmAPI‑Secret.

Ограничения API

Валарм API устанавливает ограничение на количество запросов в секунду. С одного IP‑адреса можно отправить до 500 запросов в секунду.

Примеры запросов к API

Ниже приведены примеры запросов к Валарм API. Вы также можете сгенерировать пример кода из интерфейса справочника API по ссылке для EU‑облака или для RU‑облака или посмотреть реальные запросы через консоль разработчика в браузере. Более подробная информация о консоли разработчика приведена в документации браузеров: Safari, Chrome, Firefox, Vivaldi.

  • Получение первых 50 атак, обнаруженных за последние 24 часа

    Значение TIMESTAMP необходимо заменить на дату 24 часа назад в формате Unix Timestamp.

curl -v -X POST "https://api.wallarm.com/v1/objects/attack" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID], \"time\": [TIMESTAMP] }, \"offset\": 0, \"limit\": 50, \"order_by\": \"last_time\", \"order_desc\": true}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/attack" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID], \"time\": [TIMESTAMP] }, \"offset\": 0, \"limit\": 50, \"order_by\": \"last_time\", \"order_desc\": true}"
  • Получение первых 50 инцидентов, обнаруженных за последние 24 часа

    Для получения инцидентов используется запрос, приведенный в примере выше, с параметром "!vulnid": null. Параметр указывает, что необходимо вернуть атаки, которые не содержат ID обнаруженных уязвимостей.

    Значение TIMESTAMP необходимо заменить на дату 24 часа назад в формате Unix Timestamp.

curl -v -X POST "https://api.wallarm.com/v1/objects/attack" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID], \"!vulnid\": null, \"time\": [TIMESTAMP] }, \"offset\": 0, \"limit\": 50, \"order_by\": \"last_time\", \"order_desc\": true}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/attack" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID], \"!vulnid\": null, \"time\": [TIMESTAMP] }, \"offset\": 0, \"limit\": 50, \"order_by\": \"last_time\", \"order_desc\": true}"
  • Получение первых 50 уязвимостей, обнаруженных за последние 24 часа

    Значение TIMESTAMP необходимо заменить на дату 24 часа назад в формате Unix Timestamp.

curl -v -X POST "https://api.wallarm.com/v1/objects/vuln" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"limit\":50, \"offset\":0, \"filter\":{\"clientid\":[YOUR_CLIENT_ID], \"testrun_id\":null, \"validated\":true, \"time\":[[TIMESTAMP]]}}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/vuln" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"limit\":50, \"offset\":0, \"filter\":{\"clientid\":[YOUR_CLIENT_ID], \"testrun_id\":null, \"validated\":true, \"time\":[[TIMESTAMP]]}}"
curl -v -X POST "https://api.wallarm.com/v1/objects/hint" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"filter\":{\"clientid\": [YOUR_CLIENT_ID]},\"order_by\": \"updated_at\",\"order_desc\": true,\"limit\": 1000,\"offset\": 0}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/hint" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"filter\":{\"clientid\": [YOUR_CLIENT_ID]},\"order_by\": \"updated_at\",\"order_desc\": true,\"limit\": 1000,\"offset\": 0}"
  • Получение настроенных условий блокировки запросов
curl -v -X POST "https://api.wallarm.com/v1/objects/action" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID] }, \"offset\": 0, \"limit\": 1000}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/action" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID] }, \"offset\": 0, \"limit\": 1000}"
  • Получение правил по ID условия
curl -v -X POST "https://api.wallarm.com/v1/objects/hint" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"filter\":{\"clientid\": [YOUR_CLIENT_ID],\"actionid\": YOUR_CONDITION_ID},\"limit\": 1000,\"offset\": 0}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/hint" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"filter\":{\"clientid\": [YOUR_CLIENT_ID],\"actionid\": YOUR_CONDITION_ID},\"limit\": 1000,\"offset\": 0}"
  • Создание правила для блокировки всех запросов к /my/api/*
curl -v -X POST "https://api.wallarm.com/v1/objects/hint/create" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"clientid\": YOUR_CLIENT_ID, \"type\": \"vpatch\", \"action\": [ {\"type\":\"equal\",\"value\":\"my\",\"point\":[\"path\",0]}, {\"type\":\"equal\",\"value\":\"api\",\"point\":[\"path\",1]}, {\"type\":\"equal\",\"value\":\"endpoint\",\"point\":[\"header\",\"2\"]}], \"validated\": false, \"point\": [ [ \"header\", \"HOST\" ] ], \"attack_type\": \"any\"}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/hint/create" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"clientid\": YOUR_CLIENT_ID, \"type\": \"vpatch\", \"action\": [ {\"type\":\"equal\",\"value\":\"my\",\"point\":[\"path\",0]}, {\"type\":\"equal\",\"value\":\"api\",\"point\":[\"path\",1]}, {\"type\":\"equal\",\"value\":\"endpoint\",\"point\":[\"header\",\"2\"]}], \"validated\": false, \"point\": [ [ \"header\", \"HOST\" ] ], \"attack_type\": \"any\"}"
  • Создание правила для блокировки всех запросов к /my/api/* для ID отдельного приложения

    ID приложения указывается в параметре action.value.

curl -v -X POST "https://api.wallarm.com/v1/objects/hint/create" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"type\":\"vpatch\",\"action\":[{\"point\":[\"instance\"],\"type\":\"equal\",\"value\":\"-1\",\"weight\":102},{\"point\":[\"path\",0],\"type\":\"equal\",\"value\":\"my\",\"weight\":72},{\"point\":[\"path\",1],\"type\":\"equal\",\"value\":\"api\",\"weight\":72},{\"point\":[\"header\",\"2\"],\"type\":\"equal\",\"value\":\"endpoint\",\"weight\":42}],\"clientid\":YOUR_CLIENT_ID,\"validated\":false,\"point\":[[\"header\",\"HOST\"]],\"attack_type\":\"any\"}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/hint/create" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"type\":\"vpatch\",\"action\":[{\"point\":[\"instance\"],\"type\":\"equal\",\"value\":\"-1\",\"weight\":102},{\"point\":[\"path\",0],\"type\":\"equal\",\"value\":\"my\",\"weight\":72},{\"point\":[\"path\",1],\"type\":\"equal\",\"value\":\"api\",\"weight\":72},{\"point\":[\"header\",\"2\"],\"type\":\"equal\",\"value\":\"endpoint\",\"weight\":42}],\"clientid\":YOUR_CLIENT_ID,\"validated\":false,\"point\":[[\"header\",\"HOST\"]],\"attack_type\":\"any\"}"
  • Удаление правила по ID
curl -v -X POST "https://api.wallarm.com/v1/objects/hint/delete" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"filter\":{\"clientid\":[YOUR_CLIENT_ID],\"id\": YOUR_RULE_ID}}"
curl -v -X POST "https://api.wallarm.ru/v1/objects/hint/delete" -H "X-WallarmAPI-UUID: YOUR_UUID" -H "X-WallarmAPI-Secret: YOUR_SECRET_KEY" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"filter\":{\"clientid\":[YOUR_CLIENT_ID],\"id\": YOUR_RULE_ID}}"

Подход к разработке и документированию API в Валарм

Валарм использует подход API-first, поэтому поведение новых возможностей продукта описывается в коде API, затем в справочнике. Обычно публикация изменений в коде API и обновление справочника API выполняются одновременно, но в некоторых случаях изменения в коде не затрагивают документацию API. Описание некоторых методов API может быть опубликовано в справочнике позже или не опубликовано, если методы предназначены для внутреннего использования.

Справочник Валарм API автоматически генерируется из swagger-файла с помощью инструмента Swagger UI. Справочник содержит описание методов API, параметров запроса и ответа и других атрибутов API. Вы можете выполнить любой описанный запрос через секцию Try it out справочника API.