Структура API¶

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

Какие задачи решает Структура API?¶

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

Построенная структура API позволяет:

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

Как работает ПроAPI Структура?¶

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

Стабильность эндпоинта – не менее 5 запросов в течение 5 минут.
Стабильность параметра – параметр встречается более чем в 1% успешных запросов к данному эндпоинту.
Учитываются только запросы с ответом 2xx. Стандартные поля (Content-Type, Accept) отбрасываются.

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

Эндпоинты API и методы запросов (GET, POST и др.).
Обязательные и опциональные GET/POST параметры и заголовки.
Тип/формат данных и наличие чувствительных данных (AI, учетные данные, финансовые, медицинские, PII, технические).
Дату последнего обновления информации о параметре.

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

Система определяет форматы: Int32, Int64, Float, Double, Date, Datetime, Email, IPv4, IPv6, UUID, URI, Hostname, Byte, MAC.
Если формат не определен, указывается общий тип: Integer, Number, String, Boolean.

Поиск и фильтрация эндпоинтов¶

Доступны поисковая строка и фильтры для получения специфических выборок:

Эндпоинты, измененные за последнюю неделю и обрабатывающие чувствительные данные.
Эндпоинты для загрузки данных на сервер (частая цель атак).
Эндпоинты с банковскими данными клиентов.
Эндпоинты устаревшей версии API (например, /v1).
Эндпоинты с высоким уровнем риска.
Эндпоинты, относящиеся к критическим бизнес-сценариям (биллинг, авторизация).

Отслеживание изменений¶

Система независимо определяет:

Состояние эндпоинта.
Наличие изменений в его структуре.

Для расчёта используется окно наблюдения продолжительностью 7 дней.

Состояние эндпоинта¶

Эндпоинт может находиться в одном из следующих состояний:

Новый – впервые обнаружен в течение последних 7 дней.
Активный – обнаружен более 7 дней назад и наблюдался в течение последних 7 дней.
Неиспользуемый – обнаружен более 7 дней назад и не наблюдался в течение последних 7 дней.

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

Изменения структуры¶

Структура эндпоинта считается изменённой, если в течение последних 7 дней система зафиксировала хотя бы одно из следующих событий:

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

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

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

Если обращения к эндпоинту прекращаются, система сохраняет его последнюю подтверждённую структуру.

Отображение статусов¶

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

Статус	Изменение структуры	Отображение
Новый	Без изменений	Новый
Новый	Изменённый	Новый с оранжевой точкой
Активный	Без изменений	Отметка не отображается
Активный	Изменённый	Изменённый
Неиспользуемый	Без изменений	Неиспользуемый
Неиспользуемый	Изменённый	Неиспользуемый с оранжевой точкой

Таким образом, изменение структуры отображается одним из двух способов:

Текстом «Изменённый» – для активного эндпоинта.
Оранжевой точкой – для нового или неиспользуемого эндпоинта.

Индикатор изменения структуры¶

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

Фильтрация¶

Для отбора эндпоинтов используются два независимых фильтра: «Статус» и «Изменения».

Фильтр «Статус»

Позволяет выбрать состояние эндпоинта:

Новый
Активный
Неиспользуемый

Фильтр «Изменения»

Позволяет выбрать состояние структуры эндпоинта:

Изменённый – в течение последних 7 дней зафиксировано изменение структуры.
Без изменений – в течение последних 7 дней структурные изменения не зафиксированы.

В каждом фильтре можно выбрать одно или несколько значений. Значения внутри одного фильтра объединяются по условию «ИЛИ».

Между фильтрами применяется условие «И». Эндпоинт должен соответствовать выбранным значениям обоих фильтров.

Если значение в одном из фильтров не выбрано, соответствующая характеристика не ограничивает результаты.

Shadow API¶

Эндпоинты, обнаруженные в фактическом трафике, но отсутствующие в загруженной спецификации, система отмечает как Shadow API.
В общем списке Shadow API обозначается специальной иконкой в столбце Безопасность. В карточке такого эндпоинта рядом с HTTP-методом и URL отображается метка Shadow API.
Обнаруженный Shadow API рекомендуется проверить: это может быть легитимный, но не задокументированный эндпоинт либо API, использование которого не было согласовано.

Публичные и внутренние эндпоинты¶

Эндпоинт считается внутренним, если располагается на частном/локальном IP-адресе или общем домене верхнего уровня (localhost и т.д.). В остальных случаях – публичный. По умолчанию отображаются все эндпоинты, но можно переключиться на просмотр только публичных или внутренних.

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

ПроAPI Структура объединяет вариативные элементы (например, ID пользователя) в формате {parameter_X}.

Пример: /api/articles/author/author-a-0001 и /api/articles/author/author-b-1401 станут /api/articles/author/{parameter_X}.

Просмотр информации об эндпоинте¶

Чтобы открыть карточку эндпоинта, нажмите на его строку в структуре API.

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

В разделе Общая информация представлены:

Хост API
Приложение
Дата и время обнаружения эндпоинта
Активные режимы работы
Наличие чувствительных данных (PII)
Связанный бизнес-сценарий
Оценка риска
Общее количество параметров
Количество запросов за последние 24 часа и 7 дней
RPS за последние 5 минут

Параметры запроса¶

На вкладке Запрос отображаются параметры, обнаруженные в запросах к эндпоинту.
Параметры сгруппированы по месту передачи:

Параметры пути
Параметры запроса
Заголовки

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

Параметры ответа¶

На вкладке Ответ отображаются параметры, обнаруженные в ответах API.
Если для эндпоинта зафиксировано несколько HTTP-кодов ответа, выберите нужный код, например 200. После выбора система покажет параметры, относящиеся к ответам с этим кодом.
Параметры ответа сгруппированы по месту передачи:

Заголовки — заголовки HTTP-ответа
Тело — параметры тела ответа

Чтобы посмотреть названия параметров, их тип или формат и наличие чувствительных данных, раверните группу.
Переключатель Не показывать исключённые заголовки позволяет скрыть заголовки, исключённые из анализа структуры API. Переключатель доступен при просмотре параметров как запроса, так и ответа.

Очистка структуры приложения¶

В разделе Структура API можно очистить накопленные данные о структуре API – как полностью, так и выборочно (с учётом фильтров).

Как это работает

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

Когда применять

Подготовка структуры к повторному анализу после изменения спецификации API.
Удаление устаревших, некорректных или временно ненужных данных.
Точечная очистка определённого сегмента API без потери остальных данных.

Чтобы очистить структуру:

Выберите нужное приложение.
При необходимости настройте фильтры в верхней панели (по хосту, методу, группе и т. д.).
Нажмите 🗑 Очистить структуру.
Подтвердите действие.
Система выполнит очистку либо всей структуры, либо только отфильтрованной выборки – в зависимости от того, были ли заданы фильтры.

Выгрузка спецификации¶

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

Форматы выгрузки: JSON и YAML.
Гибкая фильтрация позволяет экспортировать только нужные эндпоинты, методы или параметры. Например, можно выгрузить спецификацию одного функционального блока.
Полученная спецификация содержит только элементы, соответствующие активным фильтрам.

Сценарии использования

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

Чтобы выгрузить спецификацию:

Выберите нужное приложение.
Установите необходимые фильтры (по хосту, эндпоинту, методу, группе и т. п.). Если фильтры не заданы – будет выгружена вся структура.
Нажмите Выгрузить спецификацию ∨.
Выберите формат (JSON / YAML) и сохраните файл.

Разметка неидентифицированного трафика¶

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

Как это работает

Анализ трафика на дефолтном приложении
Настройте дефолтное приложение так, чтобы оно принимало весь неклассифицированный трафик, и дождитесь накопления данных в его структуре.
Фильтрация и выгрузка спецификации нового приложения
Определите признаки целевого приложения (например, конкретные хосты или паттерны URL). Установите фильтры, соответствующие этому сегменту, и выполните выгрузку спецификации (JSON или YAML) — вы получите описание только нужной части трафика.
Очистка дефолтного приложения по тому же фильтру
Не снимая установленных фильтров, выполните очистку структуры дефолтного приложения. Это удалит из него данные, которые уже выделены в отдельную спецификацию, и предотвратит дублирование.
Создание нового приложения
Создайте новое приложение и загрузите в него ранее выгруженный файл спецификации.
Результат
Трафик, соответствующий спецификации, начнёт обрабатываться уже новым приложением.

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