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

Валарм 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 из ответа.

    Предыдущее значение параметра secret

    После генерации нового значения secret, предыдущее значение станет невалидным. Если предыдущее значение используется на других клиентах API, замените его на новое.

  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.