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

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

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

Требования

  • Установленный и настроенный Docker и Docker Compose

  • База данных SQLite с таблицей, содержащей одну или несколько спецификаций OpenAPI 3.0. База данных может быть одного из следующих форматов::

    • Имя таблицы – openapi_schemas.
    • schema_id, целое число (автоинкрементное) - идентификатор спецификации.
    • schema_version, строка - версия спецификации. Вы можете назначить любую предпочтительную версию. При изменении этого поля ПроAPI Защита предполагает, что сама спецификация изменилась, и обновляет ее соответствующим образом.
    • schema_format, строка - формат спецификации, может быть json или yaml.
    • schema_content, строка - содержимое спецификации.

    Используйте этот формат, если вам нужно контролировать, была ли спецификация из базы данных обработана ПроAPI Защита или нет.

    • Имя таблицы - openapi_schemas.
    • schema_id, целое число (автоинкрементное) - идентификатор спецификации.
    • schema_version, строка - версия спецификации. Вы можете назначить любую предпочтительную версию. При изменении этого поля ПроAPI Защита предполагает, что сама спецификация изменилась, и обновляет ее соответствующим образом.
    • schema_format, строка - формат спецификации, может быть json или yaml.
    • schema_content, строка - содержимое спецификации.
    • status, string - указывает, является ли спецификация new (еще не обработана) или applied (уже обработана). Ожидается, что по умолчанию для нее будет установлено значение new.

      При запуске ПроAPI Защита автоматически обновляет статус обработанной спецификации с new на applied.

      Во время APIFW_SPECIFICATION_UPDATE_PERIOD, обновления получают только спецификации, помеченные как new.

Запуск контейнера ПроAPI Защита

Чтобы использовать ПроAPI Защита для проверки запросов без дальнейшего прокси-сервера, вам необходимо смонтировать SQLite database containing OpenAPI 3.0 specifications to /var/lib/wallarm-api/1/wallarm_api.db внутри контейнера Docker ПроAPI Защита. Путь может быть изменен с помощью APIFW_API_MODE_DEBUG_PATH_DB переменной.

Используйте следующую команду для запуска контейнера ПроAPI Защита:

docker run --rm -it -v <PATH_TO_SQLITE_DATABASE>:/var/lib/wallarm-api/1/wallarm_api.db \
    -e APIFW_MODE=API -p 8282:8282 wallarm/api-firewall:v0.7.3

Вы можете передать контейнеру следующие переменные:

Переменная среды Описание Необходимый?
APIFW_MODE Устанавливает общий режим ПроAPI Защита. Возможные значения: PROXY (по умолчанию), graphql и API.

Подходящее значение для этого. случай — API.
Да
APIFW_URL URL-адрес API-брандмауэра. Например: http://0.0.0.0:8088/. Значение порта должно соответствовать порту контейнера, опубликованному на хосте.

Если ПроAPI Защита прослушивает протокол HTTPS, смонтируйте сгенерированный сертификат SSL/TLS и закрытый ключ в контейнер и передайте контейнеру Настройки SSL/TLS брандмауэра API.

Значение по умолчанию — http://0.0.0.0:8282/.
Нет
APIFW_API_MODE_DEBUG_PATH_DB Устанавливает путь к базе данных спецификаций внутри контейнера Docker.

Значение по умолчанию — /var/lib/wallarm-api/1/wallarm_api.db.
Нет
APIFW_SPECIFICATION_UPDATE_PERIOD Определяет частоту получения обновлений из смонтированной базы данных. Если установлено значение «0», обновление отключено. Значение по умолчанию — «1 м» (1 минута). Нет
APIFW_API_MODE_UNKNOWN_PARAMETERS_DETECTION Определяет, блокируются ли запросы с неопределенными параметрами в соответствии со спецификацией.

Если установлено значение «true», запросы с любыми необязательными, неопределенными параметрами отклоняются (например, GET test?a=123&b= 123 блокируется, если b не определен в спецификации конечной точки /test). Если установлено значение false, такие запросы разрешены при условии, что они содержат все необходимые параметры.

Значение по умолчанию — true.
Нет
APIFW_PASS_OPTIONS Если установлено значение true, ПроAPI Защита разрешает запросы OPTIONS к конечным точкам в спецификации, даже если метод OPTIONS не описан. Значение по умолчанию — «ложь». Нет
APIFW_READ_TIMEOUT Тайм-аут ПроAPI Защита для чтения полного запроса (включая тело). Значение по умолчанию — «5s». Нет
APIFW_WRITE_TIMEOUT Тайм-аут ПроAPI Защита для возврата ответа на запрос. Значение по умолчанию — «5s». Нет
APIFW_HEALTH_HOST Хозяин службы проверки здоровья. Значение по умолчанию — «0.0.0.0:9667». Путь службы проверки работоспособности – /v1/liveness, а путь службы проверки готовности – /v1/readiness. Нет
APIFW_API_MODE_DB_VERSION Определяет версию базы данных SQLite, на использование которой настроена ПроAPI Защита. Доступные параметры:
  • 0 (по умолчанию) — сначала пытается загрузить V2 (с полем status); в случае неудачи предпринимаются попытки V1. В обоих случаях брандмауэр не запускается.
  • 1 — распознать и обработать базу данных только как V1.
  • 2 — распознать и обработать базу данных только как V2.
Нет

Оценка запросов в соответствии со спецификацией

При оценке запросов на соответствие установленной спецификации включите заголовок X-Wallarm-Schema-ID: <schema_id> чтобы указать ПроAPI Защита, какую спецификацию следует использовать для проверки:

curl http://0.0.0.0:8282/path -H "X-Wallarm-Schema-ID: <SCHEMA_ID>"

Вы можете оценивать запросы на соответствие нескольким спецификациям одновременно. Для этого включите соответствующий список идентификаторов спецификаций в X-Wallarm-Schema-ID заголовок, разделенный запятыми. Например, чтобы сравнить запрос со спецификациями с идентификаторами 1 и 2, используйте следующий формат:

curl http://0.0.0.0:8282/path -H "X-Wallarm-Schema-ID: 1, 2"

Понимание ответов ПроAPI Защита

ПроAPI Защита отвечает 200 HTTP-кодом и JSON с подробной информацией о проверке запроса:

{
    "summary": [
        {
            "schema_id": 1,
            "status_code": 200
        }
    ]
}
{
    "summary": [
        {
            "schema_id":1,
            "status_code":403
        }
    ],
    "errors": [
        {
            "message":"method and path are not found",
            "code":"method_and_path_not_found",
            "schema_id":1
        }
    ]
}
{
    "summary": [
        {
            "schema_id": 0,
            "status_code": 500
        }
    ]
}
Ключ JSON Описание
summary Массив со сводкой проверки запроса.
summary.schema_id Идентификатор спецификации, на основе которой ПроAPI Защита выполнила проверку запроса.
summary.status_code Запросить код состояния проверки. Возможные значения:
  • 200, если запрос соответствует спецификации.
  • 403, если запрос не соответствует спецификации.
  • 500, если это так. не может обработать или подтвердить запрос.
errors Массив, содержащий сведения о причинах несоответствия запроса спецификации.
errors.message Объяснение несоответствия запроса спецификации.
errors.code Код, указывающий причину несоответствия запроса спецификации. [Возможные значения] (https://github.com/wallarm/api-firewall/blob/50451e6ae99daf958fa75e592d724c8416a098dd/cmd/api-firewall/internal/handlers/api/errors.go#L14).
errors.schema_version Версия спецификации, на основе которой ПроAPI Защита выполнила проверку запроса.
errors.based_fields Массив параметров, нарушающих спецификацию.
errors.based_fields_details Подробности о параметрах, нарушающих спецификацию.
errors.based_fields_details.name Имя параметра.
errors.based_fields_details.expected_type Ожидаемый тип параметра (если тип неправильный).
errors.lated_fields_details.current_value Значение параметра, передаваемое в запросе.
errors.based_fields_details.pattern Шаблон значения параметра, указанный в спецификации.

Проблемы с базой данных

Обработка недействительности в уже смонтированной базе данных SQLite

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

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

Пример

Предположим, ПроAPI Защита загрузил две спецификации, помеченные как 1 и 2. Если спецификация 1 изменена и становится недействительной (из-за синтаксических ошибок или проблем синтаксического анализа), ПроAPI Защита загрузит и будет использовать только спецификацию 2. Он зарегистрирует сообщение об ошибке. указывает на проблему и будет работать только со спецификацией 2.

Монтаж пустой SQLite база данных

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