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

Построение структуры API

С помощью модуля Структура API вы можете получить актуальную структуру REST API вашего приложения, построенную на основе данных о фактическом использовании API. Модуль непрерывно анализирует запросы из реального трафика, а также ответы API и по результатам анализа формирует структуру API.

По умолчанию модуль Структура API выключен.

Какие задачи решает модуль Структура API?

Основная задача, которую позволяет решить модуль — получение актуальной и полной структуры API.

Поддержание описания API в актуальном состоянии — сложная задача. Компания может использовать несколько API, создавать документацию на каждый API с помощью разных инструментов и процессов. Зачастую это приводит к неактуальности документации API, неполноте данных о его структуре и публичности.

Поскольку модуль Структура API использует реальный трафик в качестве источника данных, он помогает получать актуальную и полную документацию по API. Эта документация включает все эндпоинты, которые фактически обрабатывают запросы.

Cтруктура API, построенная Вебмониторэкс, позволяет:

  • Иметь картину всего API, включая список публичных и внутренних API.

  • Понимать, какие данные передаются в API.

  • Отфильтровать атакуемые API, сортировать их по количеству хитов.

  • Фиксировать API, в которых на сервер передаются чувствительные данные.

  • Экспортировать актуальную структуру API в формате OpenAPI v3 и сравнивать ее с вашим собственным описанием API. В ходе сравнения можно обнаружить:

    • Список эндпоинтов, обнаруженных Вебмониторэкс, но отсутствующих в вашей спецификации (недостающие эндпоинты, так называемый "Shadow API").
    • Список эндпоинтов, присутствующих в вашей спецификации, но не обнаруженных Вебмониторэкс (неиспользуемые эндпоинты, так называемый "Orphan API").
  • Отслеживать изменения в структуре API, произошедшие в выбранном промежутке времени.

  • Быстро создавать правила для любого эндпоинта.

  • Получать полный список вредоносных запросов, направленных на эндпоинт.

  • Предоставлять вашим разработчикам доступ к чтению и скачиванию построенной структуры API.

Как работает модуль Структура API?

Модуль Структура API опирается на статистику запросов и использует сложные алгоритмы для создания актуальных спецификаций API на основе его фактического использования.

Гибридный подход

Модуль Структура API использует гибридный подход: анализ данных осуществляется как локально, так и в Вычислительном кластере. Это обеспечивает конфиденциальность данных, так как данные запросов и чувствительные данные остаются в вашей локальной сети. Процесс анализа включает следующие этапы:

  1. Модуль Структура API локально анализирует, на какие эндпоинты поступает легитимный трафик и какие параметры передаются в запросах.

  2. На основе этих данных формируется статистика, которая отправляется в Вычислительный кластер в защищенном виде.

  3. Вычислительный кластер Вебмониторэкс агрегирует полученную статистику и строит на ее основе описание API.

    Определение шума

    Редкие или одиночные запросы определяются как шум и не учитываются в структуре API.

Определение шума

Модуль Структура API определяет шум, руководствуясь двумя базовыми параметрами трафика:

  • Стабильность эндпоинта – не менее 5 запросов должны быть зафиксированы в течение 5 минут с момента первого запроса к эндпоинту.

  • Стабильность параметра – частота появления параметра в запросах к эндпоинту должна быть больше 1 процента.

В структуре API отобразятся эндпоинты и параметры, превышающие эти лимиты. Время построения полной структуры API зависит от разнообразия и интенсивности трафика.

Дополнительно модуль Структура API фильтрует запросы по ряду других критериев:

  • Учитываются только запросы, на которые сервер вернул ответ 2xx.

  • Стандартные поля, такие как Сontent-Type, Accept и подобные отбрасываются.

Элементы структуры API

В структуру включены следующие элементы:

  • Эндпоинты API

  • Методы запросов к API (GET, POST и другие)

  • Обязательные и опциональные GET‑ и POST‑параметры, а также заголовки запросов к API, включая:

    • Тип/формат данных, которые передаются в каждом параметре
    • Наличие и тип чувствительных данных в параметре:

      • Технические данные, например: IP-адрес или MAC-адрес
      • Учетные данные, например: секретный ключ или пароль
      • Финансовые данные, например: номер банковской карты
      • Медицинские данные, например: номер страховки
      • Персональные данные (PII), например: ФИО, номер паспорта или водительского удостоверения
    • Дату последнего обновления информации о параметре

Типы и форматы данных в параметрах

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

  • Int32

  • Int64

  • Float

  • Double

  • Date

  • Datetime

  • Email

  • IPv4

  • IPv6

  • UUID

  • URI

  • Hostname

  • Byte

  • MAC

Если значение в параметре не попадает под конкретный формат данных, то будет указан один из общих типов данных:

  • Integer

  • Number

  • String

  • Boolean

Для каждого параметра в колонке Тип отображается:

  • Формат данных

  • Если формат не определен – тип данных

Информация о типе/формате позволяет проверить, передаются ли в параметрах данные ожидаемого формата. Несоответствия могут быть результатом атаки или сканирования вашего API, например:

  • В поле с IP передаются данные типа String

  • В поле, где должно быть значение не больше Int32, передается Double

Подписка

Для работы модуля Структура API нужна отдельная подписка. Вы можете отправить запрос на sales@webmonitorx.ru для уточнения деталей.

Работа с построенной структурой API

Секция Структура API предоставляет различные возможности для работы с построенной структурой API.

Обнаруженные эндпоинты API

Среди этих возможностей:

  • Отображение структуры в привычном виде, подобном Swagger UI.

  • Поиск и фильтры.

  • Возможность просмотра отдельно публичных и внутренних эндпоинтов.

  • Просмотр параметров эндпоинта.

  • Быстрый переход к атакам на выбранный эндпоинт.

  • Создание правил для выбранного эндпоинта.

  • Скачивание спецификации OpenAPI (OAS) вашей структуры API.

Подробнее о работе со структурой API →

Отслеживание изменений в структуре API

Если вы обновляете API или меняется структура трафика, модуль учитывает эти изменения и отображает их в построенной структуре API.

В одной компании могут работать несколько команд, использоваться разные фреймворки и языки программирования. Таким образом, изменения в структуру API могут приходить в разное время и из разных источников, отслеживать их становится трудно. Специалистам по безопасности важно быстро обнаруживать и анализировать эти изменения. Не проанализированные вовремя изменения могут нести риски, например:

  • Команда разработки начинает использование сторонней библиотеки с отдельным API, не оповестив другие команды и специалистов по безопасности. Появляются эндпоинты, которые не отслеживаются и не проверяются на наличие уязвимостей. Такие эндпоинты становятся потенциальными направлениями атак.

  • На эндпоинт начинают передаваться чувствительные (PII) данные, что приводит к несоответствию требованиям контролирующих организаций, а также создает репутационные риски.

  • Прекращаются запросы к эндпоинту, важному с точки зрения бизнес-логики (например, /login, /order/{order_id}/payment/).

  • Начинают передаваться другие параметры, которые передаваться не должны, например is_admin (кто-то получает доступ к эндпоинту с правами администратора).

При помощи модуля Структура API вы можете:

  • Отследить изменения в структуре API и проанализировать, не нарушают ли эти изменения текущие бизнес-процессы.

  • Убедиться, что в структуре API не появились неизвестные эндпоинты, которые могут выступить потенциальными направлениями атак.

  • Убедиться, что в измененной части API не передаются чувствительные (PII) или другие недопустимые параметры.

Подробнее о том, как отслеживать изменения в структуре API, вы можете узнать в руководстве пользователя.

Публичные и внутренние API

Эндпоинты, доступные из внешних сетей, являются главными объектами атак. Поэтому важно иметь возможность разделить обнаруженные эндпоинты на публичные и внутренние и просматривать публичные отдельно.

Вебмониторэкс автоматически определяет, являются ли обнаруженные эндпоинты публичным или внутренним. Эндпоинт считается внутренним, если располагается на:

  • Частном или локальном IP-адресе

  • Общем домене верхнего уровня (например: localhost, dashboard, и т.д.)

В остальных случая эндпоинт считается публичным.

По умолчанию отображается список всех (публичных и внутренних) эндпоинтов. В списке эндпоинтов вы можете просмотреть публичные и внутренние эндпоинты отдельно. Для этого нажмите Публичные или Внутренние.

Вариативные элементы в эндпоинтах

В эндпоинтах могут присутствовать вариативные элементы, такие как ID пользователя, например:

  • /api/articles/author/author-a-0001

  • /api/articles/author/author-a-1401

  • /api/articles/author/author-b-1401

Модуль Структура API объединяет подобные элементы в формате {parameter_X}, так что для приведенного выше примера вместо трех эндпоинтов будет один:

  • /api/articles/author/{parameter_X}

Нажмите на эндпоинт, чтобы в наборе параметров посмотреть тип, автоматически определенный для вариативного параметра.

Структура API - Переменная в пути эндпоинта

Обратите внимание, что алгоритм постоянно анализирует новый трафик. Если в определенный момент вы видите адреса, которые должны быть объединены, но этого еще не произошло, подождите. По мере поступления дополнительных данных система уточнит закономерности и объединит эндпоинты в один с нужным вариативным элементом.

Защита от атак типа BOLA

Поведенческие атаки типа Broken Object Level Authorization (BOLA) эксплуатируют одноименную уязвимость приложений. Данная уязвимость позволяет злоумышленнику обратиться к объекту по индентификатору через запрос API и получить или изменить его данные, обойдя механизм авторизации.

Потенциальные цели BOLA-атак — эндпоинты с вариативными элементами. Вебмониторэкс может автоматически находить и защищать такие эндпоинты среди обнаруженных модулем Структура API.

Вы можете включить автозащиту для уязвимых эндпоинтов API в Консоли управления → Защита от BOLA:

BOLA trigger

Защищенные эндпоинты подсвечиваются в структуре API, например:

BOLA trigger

Чтобы отфильтровать эндпоинты по наличию автозащиты от BOLA, укажите соответствующий параметр в фильтре Другие.

Безопасность данных в Вычислительном кластере Вебмониторэкс

Модуль Структура API анализирует большую часть трафика локально. Модуль отправляет в Вычислительный кластер Вебмониторэкс только эндпоинты, имена параметров и статистику (время, количество запросов и т.д.). Данные отправляются безопасным способом: значения параметров всех запросов хешируются согласно алгоритму SHA‑256.

На стороне Вычислительного кластера хешированные данные используются только для статистического анализа, например, для определения количества запросов с такими же параметрами.

Значения эндпоинтов, методы запросов и названия параметров не хешируются, так как это ключевые данные для построения структуры API, а восстановление из хеша их оригинальных значений невозможно.

Важно

Вебмониторэкс не пересылает в Вычислительный кластер значения параметров. Отправляются только эндпоинты, имена параметров и статистика по ним.

Включение и настройка

Пакет wallarm-appstructure поставляется со всеми формами ноды Вебмониторэкс версии 3.2 и выше (кроме Debian 11.x и Ubuntu 22.04). Модуль Структура API автоматически устанавливается из пакета wallarm-appstructure при деплое ноды, но по умолчанию не анализирует трафик.

Для корректной работы модуля Структура API:

  1. Добавьте план подписки для модуля Структура API. Для этого отправьте запрос на sales@webmonitorx.ru.

  2. Если вы хотите включить модуль Структура API только для определенных приложений, убедитесь, что эти приложения настроены.

    Если приложения не настроены, структуры API всех приложений будут сгруппированы в одно дерево.

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

    • Имя аккаунта вашей компании, зарегистрированного в Консоли управления Вебмониторэкс.
    • Название Вычислительного кластера Вебмониторэкс, которое вы используете (RU-Вычислительный кластер).
    • Идентификаторы приложений, для которых вы хотите построить структуру API.

После включения модуль начнет анализ трафика ваших приложений и построение структуры API. Построенная структура будет визуализирована в секции Структура API в Консоли управления Вебмониторэкс.

Отладка модуля Структура API

Для просмотра и анализа логов модуля Структура API вы можете использовать следующие методы:

  • Если нода установлена из из DEB‑ или RPM‑пакетов: использовать стандартную утилиту journalctl или systemctl внутри инстанса с нодой Вебмониторэкс.

    journalctl -u wallarm-appstructure
    
    systemctl status wallarm-appstructure
    
  • Если нода развернута как Docker‑контейнер: прочитать лог /var/log/wallarm/appstructure.log в контейнере.

  • Если нода развернута как Ingress‑контроллер Вебмониторэкс: проверить статус пода с контейнерами Tarantool и wallarm-appstructure. Под должен находиться в статусе Running.

    kubectl get po -l app=nginx-ingress,component=controller-wallarm-tarantool
    

    Прочитать логи контейнера с wallarm-appstructure:

    kubectl logs -l app=nginx-ingress,component=controller-wallarm-tarantool -c wallarm-appstructure