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

Работа со структурой API

Данная инструкция описывает работу со структурой API, построенной ПО Структура API.

Построенная структура API отображается в разделе Структура API. Раздел доступен только пользователям со следующими ролями:

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

    Глобальный администратор и Глобальный аналитик в аккаунтах с опцией мультиарендности имеют такие же права.

  • Разработчик API может просматривать и скачивать структуру API, построенную ПО Структура API. Эта роль позволяет выделить пользователей, которым для решения рабочих задач необходимо иметь актуальную структуру API компании. Пользователи имеют доступ только к секциям Структура API и Настройки → Профиль.

Структура API отображается в привычном виде, подобном Swagger UI, и состоит из следующих элементов:

  • Клиентские приложения и хосты API.

  • Эндпоинты, сгруппированные по хостам API. Для каждого эндпоинта отображается HTTP-метод.

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

Фильтрация эндпоинтов

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

  • Только атакуемые эндпоинты, вы можете отсортировать их по количеству хитов.

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

  • Эндпоинты, которые используются для загрузки данных на ваш сервер (с помощью фильтра по методам API). Такие эндпоинты — частая цель атак, поэтому должны находиться под защитой. Получив выборку, вы сможете проверить, что все эндпоинты известны вам и защищены.

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

  • Запросить эндпоинты устаревшей версии API (например, поиск по /v1) и убедиться, что они больше не используются клиентами.

Вы также можете выгрузить отфильтрованные эндпоинты в формате OpenAPI v3 для дополнительного анализа.

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

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

Параметры запроса для обнаруженного эндпоинта API

Для каждого параметра приведена следующая информация:

  • Имя параметра и часть запроса, в которой он передается

  • Изменения в наборе параметров (новые параметры, удаленные параметры)

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

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

  • Тип/формат данных, которые передаются в этом параметре

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

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

  • Новый для эндпоинтов, добавленных в структуру в выбранном отрезке времени.

  • Изменен для эндпоинтов, у которых есть новые или удаленные параметры. Параметры будут иметь соответствующую отметку.

  • Удален для эндпоинтов, к которым не было обращений в течение определенного периода. Для каждого эндпоинта этот период определяется отдельно - вычисляется на основе статистики доступа к данному эндпоинту. Если на ранее удаленный эндпоинт снова поступают запросы, он отмечается как "новый".

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

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

  • Новые эндпоинты

  • Измененные эндпоинты

  • Удаленные эндпоинты

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

Отслеживание атак на эндпоинты API

Чтобы увидеть данные об атаках за выбранный период для какого-либо эндпоинта, щелкните число в колонке Хиты:

Эндпоинт API - связанные события

Отобразится секция События с примененным фильтром:

attacks <START_DATE_TIME - CURRENT_DATE_TIME> u:<YOUR_ENDPOINT>

Вы также можете скопировать URL какого-либо эндпоинта в буфер обмена и использовать его для поиска событий. Для этого в меню этого эндпоинта выберите Скопировать URL.

Структура API и правила

Вы можете быстро создать новое индивидуальное правило из строки любого эндпоинта в структуре API:

  1. В меню нужного эндпоинта выберите Создать правило. Появится окно создания правила. В окне адрес эндпоинта будет автоматически разбит на компоненты.

  2. В окне создания правила выберите правило, задайте его параметры и нажмите Создать.

Создание правила для эндпоинта

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

  1. Нажмите на нужный эндпоинт – откроется окно Информация об эндпоинте.

  2. В разделе Параметры нажмите на иконку справа от записи параметра, для которого необходимо создать правило – откроется меню выбора вида правила.

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

  1. Выберите правило для создания:

    Значения для выбранного параметра будут заполнены автоматически.

  2. В окне создания правила дополните необходимую информацию и нажмите Создать.

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

Нажмите Скачать OAS чтобы скачать файл swagger.json с описанием структуры вашего API, обнаруженной Вебмониторэкс. Формат описания в файле - OpenAPI v3.

Скачивание с учетом фильтров

Скачивание происходит с учетом фильтров. Скачиваются только отфильтрованные данные.

Информация о хостах API в скачанном Swagger-файле

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

Анализ скачанных данных позволяет обнаружить:

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

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

Настройка чувствительности

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

  • Нажмите Настроить в правом верхнем углу.

  • В окне Настроить Структуру API нажмите в списке на приложение, для которого нужно настроить чувствительность.

  • В блоке Чувствительность заполните числовыми значениями поля Количество запросов и Временной интервал.

  • После изменения значений нажмите кнопку Сохранить.

По умолчанию установлены 5 запросов на 300 секунд: данные значения необходимы для обеспечения стабильности эндпоинта.
Минимальное значение, которое можно установить для количества запросов – 1, для временного интервала – 0.

Настройка чувствительности

Очистка трафика

Очистка производится только для роутов, построенных на трафике.

Подключение функции очистки трафика

Для подключения функции Очистить трафик необходимо обратиться в техническую поддержку.
После подключения функция будет доступна только специалистам с ролью администратор.

После подключения вы можете очистить структуру эндпоинтов на уровне приложения:

  • Нажмите Настроить в правом верхнем углу.

  • В окне Настроить Структуру API нажмите в списке на приложение, для которого нужно очистить структуру.

  • Нажмите Очистить трафик и подтвердите действие в окне проверки.

Очистка трафика

Очистка трафика может занять до 5 минут.
После очистки трафика структура приложения будет повторно построена на основании трафика.

OpenAPI спецификация

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

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

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

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

BOLA trigger

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