Валарм API

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

  • уязвимости,
  • атаки,
  • инциденты,
  • пользователи,
  • клиенты,
  • фильтрующие узлы и т.д.

Запросы API отправляются на https://api.wallarm.com/. Описание методов приведено в справочнике API.

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

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

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

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

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

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

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

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

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

  1. Войдите в ваш аккаунт Валарм по ссылке.
  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 или посмотреть реальные запросы через консоль разработчика в браузере. Более подробная информация о консоли разработчика приведена в документации браузеров: 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}"
  • Получение первых 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}"
  • Получение первых 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.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.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}"
  • Получение правил по 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}"
  • Создание правила для блокировки всех запросов к /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\"}"
  • Создание правила для блокировки всех запросов к /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\"}"
  • Удаление правила по 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}}"

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

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

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

results matching ""

    No results matching ""