Перейти к основному содержимому

Конфигурирование фильтра HTTP-запросов

Фильтр HTTP-запросов ограничивает, какие запросы вообще могут пройти через контур Netgap: политика задаётся списком правил «вот пути — вот разрешённые для них методы», и всё, что не разрешено явно, блокируется (deny by default).

Фильтр закрывает типовую задачу logical air gap: наружу опубликован один сетевой вход, но целевой сервис в доверенном сегменте должен быть доступен не целиком, а только в согласованной части своего API — например, только на чтение отчётов и создание заказов. Без фильтра любой путь и любой метод целевого сервиса доступны всем, кто дотянулся до внешнего порта шлюза.

Эта статья описывает конфигурирование фильтра. Синтаксис путей и методов, семантика сопоставления и типовые политики разобраны в подстранице Правила фильтра: пути и методы; что происходит с заблокированным запросом, какие события аудита и метрики он порождает и как разбирать инциденты — в подстранице Заблокированные запросы: ответ, аудит и метрики; выбор между контролем на обоих компонентах и контролем только на одном из них, с разбором векторов атаки и цены каждой схемы — в подстранице Схемы размещения фильтра.

Где применяется фильтр​

Политика проверяется дважды и независимо — сначала шлюзом, затем исполнителем:

  • netgap-gateway проверяет запрос сразу после разбора строки запроса и заголовков — до постановки в очередь. Заблокированный запрос не занимает место в очереди, не паркует клиентское соединение в пуле и никогда не достигает исполнителя.
  • netgap-executor проверяет запрос повторно — до вызова целевого сервиса. Это последний рубеж: даже если запрос попал в очередь в обход внешней проверки (например, шлюз работает со старой политикой), целевой сервис вызван не будет.

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

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

Фильтр применяется только к транзитному трафику — запросам клиентов, которые Netgap передаёт целевому сервису. Служебные точки самих компонентов (/health и /metrics подсистемы наблюдаемости) работают на отдельных портах и под действие http_filter не попадают: закрыть их доступность нужно сетевыми средствами, а не фильтром.

Сценарий: запрос разрешён обеими проверками​

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

Счётчики блокировок при этом не растут, событий request blocked by http filter в потоке аудита нет. Сценарии, в которых запрос не проходит проверку, разобраны в статье Заблокированные запросы.

Секция конфигурации http_filter​

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

http_filter:
  # Режим (обязателен): AllowAll — пропускать всё, AllowList — только по правилам.
  mode: AllowList
  # Правила допуска; используются только в режиме AllowList.
  rules:
    # Заказы: чтение и создание.
    - paths:
        - /api/orders
      methods:
        - GET
        - POST
    # Отчёты (любой вложенности) и проверка состояния: только чтение.
    - paths:
        - /api/reports/**
        - /health
      methods:
        - GET
    # Карточка пользователя (ровно один сегмент после /api/users): любой метод.
    - paths:
        - /api/users/*
      methods:
        - "*"
ПолеЗначенияНазначение
modeAllowAll, AllowListРежим фильтра. AllowAll — пропускать любые запросы, AllowList — пропускать только разрешённые правилами. Обязательное поле: значения по умолчанию нет.
rulesСписок правилAllow-список политики. Обязателен и непуст при AllowList, обязан отсутствовать или быть пустым при AllowAll.
rules[].pathsСписок строкПути правила: точное значение (/health) или шаблон по целым сегментам (/api/users/*, /api/reports/**). Список обязан быть непустым.
rules[].methodsСписок строкHTTP-методы, разрешённые для этих путей. Сопоставление без учёта регистра; "*" единственной записью разрешает любой метод. Список обязан быть непустым.

Запрос разрешён, если хотя бы одно правило совпало и по пути, и по методу; порядок правил значения не имеет. Подробности — в статье Правила фильтра: пути и методы.

Режимы​

РежимКогда использоватьПоведение
AllowAllОтладка, стенды, инсталляции, где ограничение задаётся внешними средствами (WAF, API-gateway, сетевые политики).Правила не применяются, любой запрос проходит дальше по конвейеру. Список rules обязан быть пустым.
AllowListПромышленная эксплуатация: наружу открывается только согласованная часть API целевого сервиса.Проходят только запросы, разрешённые правилами; остальные блокируются с 403 или 405. Список rules обязан быть непустым.

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

Отключить фильтр в работающем процессе нельзя: как и вся остальная конфигурация, политика читается один раз из stdin при старте, и её изменение — это перезапуск компонента с новой конфигурацией (см. Конфигурирование приложения).

Проверка конфигурации при старте (fail-fast)​

Конфигурация фильтра проверяется до открытия сетевых точек: компонент с некорректной или противоречивой политикой не запускается и сообщает причину.

ОшибкаПричинаЧто сделать
Секция http_filter отсутствует или поле mode не заполненоРежим работы фильтра не задан, а значения по умолчанию у него нет — неясно, ограничивается трафик или нет.Добавить секцию http_filter с явным mode: AllowAll или mode: AllowList с правилами.
http_filter: mode is AllowAll but the rules list is not emptyПравила написаны, но режим остался AllowAll — фильтр бы ничего не ограничивал, хотя оператор ожидал обратного.Переключить mode на AllowList или убрать правила.
http_filter: mode is AllowList but the rules list is emptyРежим ограничения включён, но список правил пуст — такая политика заблокировала бы весь трафик.Заполнить rules или вернуть mode: AllowAll.
http_filter.rules[N]: the paths list is emptyВ правиле не перечислены пути.Указать хотя бы один путь.
http_filter.rules[N]: the methods list is emptyВ правиле не перечислены методы.Указать методы или "*".
http_filter.rules[N]: paths entry '…' must start with '/'Путь записан без ведущего слэша (api/users).Начать путь с /.
http_filter.rules[N]: paths entry '…' must not contain whitespaceВ пути есть пробельные символы.Убрать пробелы; при необходимости взять значение в кавычки YAML.
http_filter.rules[N]: paths entry '…' uses '*' inside the segment '…'Подстановка использована как glob/regex (/api*, /*.json, /api/**suffix).Использовать * и ** только как целые сегменты пути.
http_filter.rules[N]: the '*' methods entry allows any method and must be the only entry"*" перечислен вместе с конкретными методами ([GET, "*"]).Оставить либо "*", либо список конкретных методов.

Индекс N — порядковый номер правила в списке rules, начиная с нуля.

Примеры конфигурации​

Фильтр выключен — минимально допустимая секция с явно указанным режимом:

http_filter:
  mode: AllowAll

Только чтение публичного API, всё остальное закрыто:

http_filter:
  mode: AllowList
  rules:
    - paths:
        - /api/**
      methods:
        - GET
        - HEAD

Разделение прав по ресурсам: справочники — только чтение, заказы — чтение и создание, служебная проверка целевого сервиса — чтение:

http_filter:
  mode: AllowList
  rules:
    - paths:
        - /api/catalog/**
        - /health
      methods:
        - GET
    - paths:
        - /api/orders
        - /api/orders/*
      methods:
        - GET
        - POST

Больше готовых политик и разбор синтаксиса — в статье Правила фильтра: пути и методы.

Готовые примеры в поставке​

В релизный бандл входят готовые конфигурации с ограничивающим фильтром — config/netgap-gateway-restricted.yaml и config/netgap-executor-restricted.yaml. Это минимальная рабочая конфигурация плюс секция http_filter в режиме AllowList с одинаковой политикой у обоих компонентов; файлы запускаются так же, как остальные примеры (см. Быстрый старт):

cat config/netgap-executor-restricted.yaml local-pki/netgap-executor-internal-transport.yaml | exec env -i ./bin/netgap-executor run
cat config/netgap-gateway-restricted.yaml local-pki/netgap-gateway-internal-transport.yaml | exec env -i ./bin/netgap-gateway run

Остальные примеры поставки содержат обязательный явный http_filter: mode: AllowAll, а документированные config/netgap-gateway.yaml и config/netgap-executor.yaml — ещё и закомментированный образец ограничивающей политики.

Границы применимости​

Фильтр отвечает ровно за одно решение: пропускать ли запрос с таким путём и таким методом. Он не выполняет:

  • аутентификацию и авторизацию клиента — фильтр не смотрит на заголовки, токены, cookies и адрес источника;
  • проверку содержимого — тело запроса, значения заголовков и параметры query-строки не анализируются (при сопоставлении query-строка и фрагмент отбрасываются);
  • сопоставление по произвольным регулярным выражениям — поддерживаются только точные пути и шаблоны по целым сегментам, чтобы политика читалась однозначно и не зависела от тонкостей regex-движка;
  • ограничение частоты запросов и защиту от нагрузки.

Фильтр — это ограничение поверхности атаки на границе контура, а не замена аутентификации на целевом сервисе.

Ссылки​