Спецификация API¶

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

Просмотр списка спецификаций¶

Откройте раздел Спецификация API и выберите приложение. Если приложение не выбрано, система предложит выбрать его.
В таблице для каждой спецификации отображаются:

• версия, дата загрузки и признак Активная;

• состояние сравнения, дата последнего успешного сравнения и режим;

• позиция в очереди, если сравнение ожидает запуска;

• количество эндпоинтов;

• количество теневых, зомби- и неиспользуемых API.
  Признак Активная означает, что спецификация используется для защиты приложения, и не является состоянием сравнения.
  Возможные состояния сравнения:

• Сравнивается – сравнение выполняется;

• В очереди – разовое сравнение ожидает запуска; отображается позиция в очереди;

• Ожидает очереди – регулярный запуск создан, но очередь заполнена;

• Сравнено – последнее разовое сравнение успешно завершено; отображается дата;

• Ошибка валидации – сравнение не запущено; нажмите статус, чтобы открыть список ошибок;

• Готова к сравнению – успешных запусков ещё не было.

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

Добавление спецификации¶

Чтобы добавить спецификацию:

1. Откройте раздел Спецификация API для нужного приложения.

2. Нажмите Добавить спецификацию.

3. При необходимости добавьте описание. Максимальная длина – 255 символов.

4. Перетащите файл в область загрузки или выберите его вручную. Поддерживаются спецификации OpenAPI 3.x в форматах JSON, YAML и YML.

5. При необходимости раскройте блок Детектирование неучтенных API и настройте параметры сравнения.

6. Включите или выключите Регулярное сравнение. При включении система автоматически сверяет спецификацию с трафиком каждый час.

7. Нажмите Добавить спецификацию.
   После загрузки система проверяет структуру файла. Корректная спецификация сохраняется и ставится в очередь на сравнение. Если файл не прошёл проверку, спецификация получает состояние Ошибка валидации.

Параметры детектирования¶

Теневой API¶

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

• эндпоинт;

• заголовок;

• параметр;

• тело запроса;

• тело ответа;

• метод;

• код ответа.

Неиспользуемый API¶

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

Зомби API¶

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

• Сравнение с пред. спецификацией – элемент отсутствует в текущей версии, но присутствовал в предыдущей;

• Устаревшие (deprecated) – элемент помечен как устаревший в текущей спецификации.
  Для устаревших элементов задайте порог обнаружения – период, в течение которого элемент продолжает получать трафик после объявления устаревшим. Порог можно указать в часах, днях или месяцах.

Список исключений¶

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

1. Нажмите Добавить исключение.

2. Укажите точный путь или шаблон пути в формате PCRE.

3. Выберите один или несколько методов: GET, POST, PUT, PATCH, DELETE либо «Все методы».

4. Выберите один или несколько типов: Теневой API, Зомби API или Неиспользуемый API.

5. При необходимости добавьте комментарий.

6. Нажмите Сохранить.
   После изменения исключений перезапустите сравнение, чтобы применить настройки к результатам.

Сравнение спецификации с трафиком¶

Доступны два режима:

• Разовое – запускается при добавлении спецификации или вручную командой Перезапустить сравнение;

• Регулярное – выполняется автоматически каждый час.
  Регулярное сравнение можно включить не более чем для четырёх спецификаций. Количество загруженных спецификаций не ограничено. Разовые сравнения доступны без ограничений.
  Если достигнут лимит регулярных сравнений, переключатель недоступен. Чтобы включить режим для другой спецификации, сначала выключите его у одной из текущих.

Ошибки валидации¶

Если спецификация некорректна, нажмите состояние Ошибка валидации. На странице ошибок для каждой записи отображаются:

• Место – путь к полю или элементу спецификации;

• Ошибка – причина, по которой файл не прошёл проверку.

Исправьте файл и загрузите новую версию спецификации.

Редактирование и действия¶

Откройте меню действий в строке спецификации. Доступны следующие команды:

• Редактировать – изменить описание, параметры детектирования, исключения и режим регулярного сравнения;

• Перезапустить сравнение – повторно сверить спецификацию с текущим трафиком;

• Скачать исходную – скачать загруженный файл;

• Скачать с неучтенными АПИ – скачать спецификацию, дополненную обнаруженными неучтёнными API;

• Удалить – удалить неактивную спецификацию. Для спецификации с признаком Активная команда недоступна.

Просмотр результатов¶

После успешного сравнения выберите строку спецификации. Результаты можно фильтровать:

• по хостам – все, публичные или внутренние;

• по типу – все, теневые, зомби или неиспользуемые API.

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

• метод;

• URL эндпоинта;

• тип изменения;

• признаки PII;

• признаки безопасности;

• бизнес-сценарий;

• уровень риска.

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