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

Обзор Валарм 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

    Запрос POST /v1/user/renew_secret генерирует новое значение секретного ключа и делает предыдущее значение невалидным. Для безопасного использования секретного ключа:

    • Сохраните в безопасном месте значение secret, полученное при первом вызове метода POST /v1/user/renew_secret. Значение секретного ключа больше нигде не отобразится.
    • Переиспользуйте сохраненное значение secret во всех запросах к Валарм API.
    • Если вы сгенерировали новое значение secret, убедитесь, что предыдущее значение не используется на других клиентах API. Если предыдущее значение используется, замените его на новое.

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

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

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

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

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

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

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