Создание и импорт OpenAPI-спецификации

WebVulnFinder может восстановить OpenAPI по выбранному фрагменту HTTP-ответа с помощью ИИ или импортировать готовый YAML/JSON-документ. AI-сценарий публикует операции как рекомендацию для проверки, а импорт добавляет операции из выбранного файла.

Создание OpenAPI по фрагменту ответа

Сценарий подходит, когда в JavaScript, HTML или другом текстовом ответе виден вызов API, но полного контракта рядом нет. Настройте подключение ИИ, добавьте разрешённые origin в проектный список HOSTS, затем:

1. Выделите непустой фрагмент в теле ответа в любом HTTP-редакторе Burp.
2. В контекстном меню откройте «Создать ИИ задачу» и выберите «Создать OpenAPI спецификацию».
3. Запустите подготовленную AI-задачу и дождитесь рекомендации «Применить OpenAPI спецификацию».

Модель получает выбранный фрагмент как отправную точку и может искать ограниченные контексты в уже сохранённых ответах. Это помогает проследить переменные URL, импортированные константы, обёртки HTTP-клиента и места их вызова без автоматической передачи целого файла. Модель сначала проверяет подготовленную схему: предупреждения о неподдерживаемых операциях возвращаются ей для уточнения. Затем она публикует рекомендацию из тех операций, для которых удалось построить запрос. Завершённую задачу можно продолжить сообщением, чтобы уточнить схему в том же диалоге.

Готовая рекомендация содержит исходный OpenAPI YAML и отдельную вкладку для каждой поддерживаемой операции:

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

WebVulnFinder отправляет проверочные запросы только тогда, когда точный origin операции присутствует в HOSTS. Для остальных origin отображается построенный запрос без ответа, а сетевой вызов не выполняется. Проверьте origin, параметры и данные авторизации перед изменением статуса операции. Для новой операции можно вручную выбрать CONFIRMED или ABSENT; для уже сохранённой доступна проверка исходного варианта из OpenAPI.

Меню принятия показывает число выбранных операций. Они применяются по очереди; в журнале виден результат каждой операции. Очередь можно приостановить или отменить, а ошибочный шаг — повторить или пропустить. Уже применённые операции помечаются отдельно и не повторяются при следующем принятии. Рекомендация становится принятой только после успешного завершения всех выбранных шагов.

Новые API создаются только для операций в состоянии CONFIRMED; уже сохранённые операции связываются с исходными свидетельствами. У применённых API появляется ссылка на запрос с исходным кодом, из которого восстановлен OpenAPI. Перед сохранением WebVulnFinder ещё раз исключает дубликаты. Отклонение рекомендации не меняет базу знаний.

Импорт внешней спецификации

Если OpenAPI-спецификация получена вне WebVulnFinder, её можно использовать как исходную карту API. Например, спецификацию может предоставить владелец тестируемой системы или программа тестирования; её также можно получить при анализе мобильного приложения, JAR или WAR с помощью BFScan, сформировать другим инструментом либо подготовить вручную.

WebVulnFinder читает OpenAPI 3 в YAML или JSON и создаёт ручные API-наблюдения с примерами HTTP-запросов. Это позволяет начать анализ endpoint-ов, которые ещё не встретились в Proxy, а затем подтвердить и дополнить импортированную модель реальным трафиком.

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

Если часть операций невозможно превратить в запрос, доступные операции всё равно импортируются. Для пропущенных операций показываются предупреждения с методом, путём и причиной. Адрес сервера с неразрешёнными переменными или учётными данными из URL не подменяется другим адресом автоматически.

Что учитывается

Часть спецификации	Как используется
servers	Формирует origin и базовый путь. Учитываются определения на глобальном уровне, уровне path и уровне operation; более конкретный уровень имеет приоритет. Переменные сервера подставляются из default или первого enum.
HTTP-операции	Импортируются GET, POST, PUT, DELETE и PATCH. Для каждой операции создаётся отдельное API-наблюдение.
Параметры	Обрабатываются path-, query-, header- и cookie-параметры с уровня path и operation. Учитываются обязательность, тип, описание, enum, example и default, заданные в schema.
Request body	Поддерживаются JSON, XML, multipart/form-data и application/x-www-form-urlencoded, включая вложенные объекты, массивы, XML-атрибуты, бинарные поля и additionalProperties.
Составные схемы	allOf объединяется; ссылки на схемы разрешаются. Для oneOf и anyOf используется первый вариант.
Security schemes	HTTP authentication, API key в header/query/cookie, OAuth2 и OpenID Connect превращаются в заголовки, cookies или параметры-заглушки для примера запроса.
Описание операции	summary и description сохраняются в комментарии, а tags — в отдельном поле тегов создаваемого наблюдения.

Если в спецификации нет servers, используется https://localhost. Перед выполнением импортированного запроса проверьте origin, примеры параметров и данные авторизации.

Что не учитывается или упрощается

• документ должен быть приведён к OpenAPI 3; совместимость с OpenAPI 2 / Swagger 2 не гарантируется;
• операции HEAD, OPTIONS и TRACE не импортируются;
• схемы, заголовки, примеры и коды ответов не используются для построения API-наблюдения;
• callbacks, webhooks и links не создают дополнительные операции;
• при нескольких servers на одном уровне используется первый;
• при нескольких форматах request body выбирается один: приоритет имеют JSON, XML, multipart и URL-encoded form, затем первый оставшийся формат;
• для oneOf и anyOf импортируется только первая альтернатива;
• значения авторизации заменяются безопасными заглушками и требуют настройки перед выполнением запросов;
• примеры, заданные вне schema, могут не попасть в сформированный запрос.

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