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

Обзор Валарм 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‑облака → Настройки → Параметры для доступа к API.

  2. Cкопируйте значение UUID.

  3. Получите значение секретного ключа:

    • Если вам известно значение секретного ключа, вы можете продолжить использовать это значение, так как в интерфейсе отображается значение активного секретного ключа, но в зашифрованном виде.

    • Если вам неизвестно значение секретного ключа или ключ был утерян, сгенерируйте новый секретный ключ с помощью кнопки Обновить секретный ключ и скопируйте полученное значение. Значение ключа отобразится только один раз.

      Переиспользование секретного ключа

      Кнопка Обновить секретный ключ генерирует новое значение секретного ключа и делает предыдущее значение невалидным. Для безопасного использования секретного ключа:

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

  4. Передайте UUID и секретный ключ в запросе к Валарм API:

    • UUID в заголовке запроса в параметре X-WallarmAPI-UUID
    • Секретный ключ в заголовке запроса в параметре X-WallarmAPI-Secret

Параметры для аутентификации в Валарм API

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

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

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