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

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

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

По умолчанию модуль Обнаружение API выключен.

Какие задачи решает модуль для обнаружения API?

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

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

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

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

Как работает модуль для обнаружения API?

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

Полученная статистика выгружается в Облако Валарм. На основе статистики в Облаке формируется структура API, которая отображается в Консоли управления.

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

  • Эндпоинты API

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

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

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

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

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

Значения эндпоинтов, методы запросов и названия параметров не хешируются.

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

Пакет wallarm-appstructure поставляется со всеми формами WAF‑ноды версии 3.0 и выше. Модуль Обнаружение API автоматически устанавливается из пакета wallarm-appstructure при деплое WAF‑ноды, но по умолчанию не анализирует трафик.

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

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

    Например, чтобы включить модуль Обнаружение API для example.com и test.com, в соответствующих блоках server в конфигурационном файле NGINX должны быть добавлены директивы wallarm_instance с уникальными значениями:

    server {
        listen       80;
        server_name  example.com;
        wallarm_mode block;
        wallarm_instance 13;
    
        ...
    }
    
    server {
        listen       80;
        server_name  test.com;
        wallarm_mode monitoring;
        wallarm_instance 14;
    
        ...
    }
    

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

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

    • Имя аккаунта вашей компании, зарегистрированного в Консоли управления Валарм.
    • Название Облака Валарм, которое вы используете.
    • Идентификаторы приложений, для которых модуль должен строить структуры API. Идентификатор приложения — значение wallarm_instance. Чтобы включить модуль для всех приложений, передавать идентификатор каждого приложения не требуется.

      Техническая поддержка Валарм продублирует приложения в Консоли управления → Настройки → Приложения. Дублированные записи будут иметь префикс [API Discovery], названия приложений и уникальные ID. Например, если вы включаете модуль Обнаружение API для всех приложений, список приложений в Консоли управления Валарм будет иметь следующий вид:

      Приложения для Обнаружение API

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

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

Визуализация структуры API

Структура API каждого приложения отображается в виде отдельного дерева в секции Правила в Консоли управления Валарм.

В каждом дереве указывается название дубля приложения, для которого оно построено (название дубля имеет вид [API Discovery] <YOUR_APP_NAME>). Дерево состоит из следующих элементов:

  • Набор эндпоинтов API, которые обнаружил модуль для обнаружения API

  • Методы запросов, которые отправляются на эндпоинты

Эндпоинты, обнаруженные с Обнаружение API

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

Параметры запросов, обнаруженные с Обнаружение API

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

Отладка модуля для обнаружения API

Для просмотра и анализа логов модуля Обнаружение API вы можете использовать стандартную утилиту journalctl внутри инстанса с установленной WAF‑нодой:

journalctl -u wallarm-appstructure