HA-WAF Handbook

Полное руководство по установке, настройке и эксплуатации HA-WAF.

Содержание

• Часть I: Введение
  • 1. Что такое HA-WAF
  • 2. Ключевые возможности
  • 3. Архитектура (кратко)
• Часть II: Установка
  • 4. Docker Compose (быстрый старт)
  • 5. Kubernetes / Helm
• Часть III: Конфигурационный файл
  • 6. Структура config.yaml
  • 7. Секция server
  • 8. Секция database
  • 9. Секция haproxy
  • 10. Секция spoa
  • 11. Секция auth
  • 12. Секция telemetry
• Часть IV: Сайты и бэкенды
  • 13. Создание HTTP/HTTPS сайта
  • 14. Создание TCP-сайта
  • 15. Бэкенды
  • 16. Алгоритмы балансировки
  • 17. Списки доменов (Domain Lists)
• Часть V: WAF
  • 18. Политика WAF
  • 19. Режимы WAF
  • 20. Уровень паранойи (Paranoia Level)
  • 21. Исключения правил (Rule Exclusions)
  • 22. Пользовательские правила (Custom Rules)
  • 23. События WAF
• Часть VI: Фильтрация по GeoIP
  • 24. Настройка GeoIP
  • 25. Формат GeoIP-карты
• Часть VII: IP-списки
  • 26. Белые списки (Whitelist)
  • 27. Чёрные списки (Blacklist)
• Часть VIII: Rate Limiting
  • 28. Правила ограничения частоты запросов
  • 29. Path-prefix и regex фильтры
• Часть IX: Path Rules (nginx location blocks)
  • 30. Обзор Path Rules
  • 31. Тип совпадения пути
  • 32. Действия (Actions)
  • 33. Проксирование (proxy)
  • 34. Статический ответ (return)
  • 35. Перенаправление (redirect)
  • 36. Условия (Conditions)
  • 37. Rate limit для Path Rule
  • 38. WAF-исключения для Path Rule
  • 39. Модификация заголовков
  • 40. WebSocket
  • 41. gRPC
  • 42. Множество upstream-серверов
  • 43. Приоритеты и порядок обработки
• Часть X: TLS и сертификаты
  • 44. Загрузка сертификата (Upload)
  • 45. Массовый импорт архива
  • 46. ACME-аккаунты — мультиаккаунтная модель
  • 47. Выпуск сертификата через ACME
  • 48. DNS-01 challenge
  • 49. Автообновление сертификатов
  • 50. Асинхронные job'ы выпуска (JobRunner)
  • 51. Отслеживание ошибок выпуска (Cert Failures)
  • 52. Per-site переопределение директории сертификатов
• Часть XI: Пользователи и API-ключи
  • 53. Управление пользователями
  • 54. Роли и права доступа
  • 55. API-ключи
• Часть XII: OIDC / SSO
  • 56. Настройка провайдера
  • 57. Поток входа
  • 58. Backchannel Logout
• Часть XIII: Лицензирование
  • 59. Модель лицензирования
  • 60. Статусы и фичи
• Часть XIV: k8sban — сетевой бан через Cilium
  • 61. Зачем это нужно
  • 62. Включение
  • 63. Как это работает
• Часть XV: Метрики и телеметрия
  • 64. Prometheus метрики
  • 65. OpenTelemetry (OTLP)
  • 66. Дашборд метрик в UI
• Часть XVI: Конфиг-ревизии
  • 67. Что такое ревизия
  • 68. Просмотр и откат
  • 69. Экспорт и импорт конфигурации
• Часть XVII: Страницы ошибок
  • 70. Кастомные error pages
• Часть XVIII: Настройки системы
  • 71. System Config через UI
• Часть XIX: CI/CD
  • 72. Пайплайн (.gitlab-ci.yml)
  • 73. Публикация образа и чарта
  • 74. Деплой в кластер
• Часть XX: Защита от ботов (Anti-Bot)
  • 75. Обзор стека защиты от ботов
  • 76. Per-site Bot Policy (UA-фильтры)
  • 77. Защита от Slowloris (conn_cur)
  • 78. Tarpit и decoy
  • 79. IP-Reputation фиды
  • 80. Verified bots
  • 81. Challenge (redirect → PoW)
  • 82. Honeypot
  • 83. Мониторинг и эксплуатация anti-bot
• Приложение A: REST API
• Приложение B: Справочник по config.yaml
• Приложение C: Переменные окружения
• Часть XXI: Известные проблемы безопасности
  • 84. Текущие security issues
  • 85. Roadmap исправлений

Часть I: Введение

1. Что такое HA-WAF

HA-WAF — это единый исполняемый файл (Go binary), который объединяет:

• HAProxy 3.2 — высокопроизводительный обратный прокси и балансировщик нагрузки
• Coraza WAF — OWASP-совместимый файрвол веб-приложений с полной поддержкой CRS v4
• REST API — полнофункциональный API управления конфигурацией
• Web UI — встроенный React-интерфейс для администрирования

HA-WAF управляет HAProxy как дочерним процессом: генерирует конфиг, запускает, перезагружает (бесшовно, через SIGUSR2) и взаимодействует через admin socket. WAF работает через SPOE-протокол на локальном TCP-порту.

2. Ключевые возможности

3. Архитектура (кратко)

Стандартная редакция (HA-WAF):

                        ┌──────────────────────────────────────────┐
                        │              ha-waf process               │
  Клиент ─── :80/443 ──►│                                          │
                        │  HAProxy 3.2 (child) ◄──SPOE──► Coraza  │
  Admin  ─── :8080 ───►│         REST API + Web UI                │
                        │         SQLite / PostgreSQL               │
                        └──────────────────────────────────────────┘

При каждом изменении конфигурации HA-WAF:

1. Пересчитывает HAProxy-конфиг из шаблонов
2. Атомарно перезагружает WAF-экземпляры (без потери соединений)
3. Выполняет seamless reload HAProxy через SIGUSR2

Часть II: Установка

4. Docker Compose (быстрый старт)

git clone https://github.com/ha-waf/ha-waf
cd ha-waf
docker compose up -d

Стек по умолчанию запускает:

• HA-WAF — порты 80, 443, 8080 (API + UI), 9091 (Prometheus)
• otel-collector — приём OTLP, маршрутизация в VictoriaMetrics / VictoriaLogs
• VictoriaMetrics — хранение метрик
• VictoriaLogs — хранение структурированных логов
• Grafana — дашборды (предустановлены)

Web UI доступен по адресу: http://localhost:8080

Учётные данные по умолчанию: admin / admin

Первое, что нужно сделать: сменить пароль администратора в разделе Settings → Users.

Переопределение конфига

Смонтируйте свой config.yaml:

# docker-compose.override.yml
services:
  ha-waf:
    volumes:
      - ./my-config.yaml:/etc/ha-waf/config.yaml:ro

5. Kubernetes / Helm

Чарт лежит в репозитории по пути deploy/ha-waf/ (не charts/ha-waf) и публикуется в OCI-registry (см. §73):

helm install ha-waf oci://ghcr.io/ha-waf/charts --version 0.4.1 \
  --set image.tag=v0.3.0 \
  --set config.database.driver=postgres \
  --set config.database.dsn="host=pg-primary ..." \
  --set ingress.enabled=true

Или локально из исходников: helm install ha-waf deploy/ha-waf/.

Чарт создаёт:

• Deployment с readinessProbe на /readyz
• Service (ha-waf-api — ClusterIP для управления, ha-waf-proxy — LoadBalancer на портах 80/443, опционально доп. порты через service.proxy.extraPorts)
• ServiceAccount (automountServiceAccountToken включён только при k8sNetworkBan.enabled)
• ClusterRole/ClusterRoleBinding — только при k8sNetworkBan.enabled (RBAC на ciliumclusterwidenetworkpolicies, см. Часть XIV: k8sban)
• Ingress (классический, ingress.enabled) и/или HTTPRoute (Gateway API, gateway.enabled) для UI/API
• PodDisruptionBudget, HorizontalPodAutoscaler
• PersistentVolumeClaim для SQLite (или используйте PostgreSQL)
• ConfigMap для config.yaml

При горизонтальном масштабировании используйте PostgreSQL с dsn_read для read replica. SQLite не поддерживает multi-replica.

Часть III: Конфигурационный файл

6. Структура config.yaml

server:    { ... }   # REST API сервер
database:  { ... }   # SQLite или PostgreSQL
haproxy:   { ... }   # HAProxy параметры
spoa:      { ... }   # Coraza SPOE адрес
auth:      { ... }   # JWT настройки
telemetry: { ... }   # Prometheus + OTLP

Флаг при запуске: -config /path/to/config.yaml (по умолчанию /etc/ha-waf/config.yaml).

7. Секция server

server:
  addr: ":8080"   # Адрес REST API и Web UI

8. Секция database

database:
  driver: sqlite
  dsn: /var/lib/ha-waf/ha-waf.db

SQLite

database:
  driver: sqlite
  dsn: /var/lib/ha-waf/ha-waf.db

PostgreSQL (один сервер)

database:
  driver: postgres
  dsn: "host=localhost port=5432 user=hawaf password=secret dbname=hawaf sslmode=disable"

PostgreSQL с read replica (Patroni, Citus, RDS)

database:
  driver: postgres
  dsn:      "host=pg-primary port=5432 user=hawaf password=secret dbname=hawaf sslmode=disable"
  dsn_read: "host=pg-replica port=5433 user=hawaf password=secret dbname=hawaf sslmode=disable"

Запросы на запись всегда идут на dsn (primary). Read-only запросы (GET) — на dsn_read.

9. Секция haproxy

haproxy:
  binary:      /usr/local/sbin/haproxy
  config_dir:  /etc/ha-waf/haproxy
  config_file: /etc/ha-waf/haproxy/haproxy.cfg
  pid_file:    /var/run/ha-waf/haproxy.pid
  socket_path: /var/run/ha-waf/haproxy-admin.sock

  maxconn:   50000
  ulimit_n:  200000
  ssl_options: "no-sslv3 no-tlsv10 no-tlsv11"

  http_port:  80
  https_port: 443

  ssl_cert_dir: /etc/ha-waf/certs/
  error_dir:    /etc/ha-waf/errors

  geoip_map_file: /etc/ha-waf/geoip.txt

  metrics_bind: ":8405"
  metrics_acls:
    - "127.0.0.1"
    - "192.168.0.0/16"

  internal_rate_table_port: 19999

10. Секция spoa

spoa:
  addr: "127.0.0.1:9000"

Не выставляйте SPOA наружу. Это внутренний протокол между HAProxy и Coraza.

11. Секция auth

auth:
  jwt_secret: "your-very-secret-key-here"
  token_ttl:  "24h"

В multi-replica режиме обязательно задайте одинаковый jwt_secret на всех узлах.

12. Секция telemetry

telemetry:
  prometheus_addr: ":9091"

  otlp:
    endpoint: "otel-collector:4317"
    insecure: true
    logs:
      enabled: true
    metrics:
      enabled: true
    traces:
      enabled: true

Часть IV: Сайты и бэкенды

13. Создание HTTP/HTTPS сайта

Web UI: Раздел Sites → кнопка Add Site.

API:

POST /api/v1/sites
Content-Type: application/json

{
  "name": "My App",
  "enabled": true,
  "mode": "http",
  "domains": ["app.example.com"],
  "domain_suffixes": [".app.example.com"],
  "http_enabled": true,
  "https_enabled": true,
  "redirect_http_to_https": true,
  "acme_enabled": true,
  "lb_algorithm": "roundrobin"
}

Поля сайта

Маршрутизация запросов

Каждый сайт получает ACL в HAProxy. Запрос направляется к сайту, если:

• Host header точно совпадает с одним из domains, или
• Host header заканчивается на один из domain_suffixes, или
• Сайт совпал через DomainList (список доменов), или
• Для сайта без domains, domain_suffixes и domain_lists — всегда (catch-all)

14. Создание TCP-сайта

TCP-сайты работают в режиме L4 pass-through: HAProxy не расшифровывает TLS, а перенаправляет трафик по SNI-имени хоста.

POST /api/v1/sites
{
  "name": "NetBird",
  "enabled": true,
  "mode": "tcp",
  "tcp_port": 443,
  "domains": ["vpn.example.com"],
  "domain_suffixes": [],
  "lb_algorithm": "roundrobin"
}

Как работает SNI-маршрутизация:

Если на одном TCP-порту несколько сайтов с разными domains/domain_suffixes, HAProxy:

1. Включает tcp-request inspect-delay 5s (ждёт TLS ClientHello)
2. Читает SNI из req.ssl_sni
3. Маршрутизирует к соответствующему бэкенду

Если только один сайт на порту — SNI-инспекция не включается (нет overhead).

Сайт без domains и domain_suffixes становится default_backend для данного порта.

Ограничения TCP-режима: WAF, GeoIP, IP-списки, Path Rules, Rate Limits не работают в TCP-режиме — HAProxy не видит HTTP-содержимое.

15. Бэкенды

К каждому сайту можно добавить несколько бэкенд-серверов.

API:

POST /api/v1/sites/{siteId}/backends
{
  "name": "web-1",
  "address": "10.0.0.10",
  "port": 8080,
  "weight": 10,
  "enabled": true,
  "ssl_enabled": false,
  "ssl_verify_none": false,
  "ssl_sni_from_host": false,
  "send_proxy": 0
}

Поля бэкенда

16. Алгоритмы балансировки

17. Списки доменов (Domain Lists)

Domain Lists позволяют загружать списки доменов из внешних URL и маршрутизировать трафик на специальный бэкенд.

Применение:

• Маршрутизация трафика для группы клиентских доменов
• Динамическое обновление (например, из внешней системы управления)

POST /api/v1/sites/{siteId}/domainlists
{
  "name": "Client Domains",
  "enabled": true,
  "source_url": "https://config.example.com/domains.txt",
  "fetch_interval": 300,
  "auth_user": "user",
  "auth_password": "secret",
  "backend_id": "uuid-of-backend"
}

Формат файла доменов

Один домен на строку:

client1.example.com
client2.example.com
# комментарии игнорируются

Поля Domain List

Часть V: WAF

18. Политика WAF

Каждый сайт имеет одну политику WAF (1:1). Политика управляет поведением Coraza + OWASP CRS.

API:

GET  /api/v1/sites/{siteId}/waf
PUT  /api/v1/sites/{siteId}/waf
{
  "enabled": true,
  "mode": "prevention",
  "paranoia_level": 1,
  "anomaly_threshold": 5,
  "response_body_check": false,
  "custom_directives": ""
}

19. Режимы WAF

Рекомендуемый workflow: начните с detection, изучите WAF-события в UI, добавьте исключения для ложных срабатываний, затем переключитесь на prevention.

20. Уровень паранойи (Paranoia Level)

Paranoia Level (PL) определяет, сколько правил CRS активировано. Более высокий уровень = лучшая защита, но больше ложных срабатываний.

21. Исключения правил (Rule Exclusions)

Исключения позволяют отключить конкретные CRS-правила или сузить их область применения.

API:

POST /api/v1/sites/{siteId}/exclusions
{
  "rule_id": 942100,
  "type": "disable",
  "comment": "SQL injection false positive in search form"
}

Типы исключений

Пример: отключить проверку поля q для правила 942100:

{
  "rule_id": 942100,
  "type": "exclude_arg",
  "target": "q"
}

Пример: отключить правило только для /api/search:

{
  "rule_id": 942100,
  "type": "exclude_url",
  "url_pattern": "/api/search"
}

Найти номер правила можно в разделе WAF Events — там отображается Rule ID сработавшего правила.

22. Пользовательские правила (Custom Rules)

Custom Rules позволяют писать произвольные директивы Coraza/ModSecurity.

Глобальные правила (site_id = "") применяются ко всем сайтам. Per-site правила применяются только к конкретному сайту.

POST /api/v1/sites/{siteId}/rules
{
  "name": "Block suspicious UA",
  "enabled": true,
  "priority": 10100,
  "directives": "SecRule REQUEST_HEADERS:User-Agent \"@contains evil-bot\" \"id:10100,phase:1,deny,status:403,msg:'Blocked UA'\""
}

Глобальные правила:

POST /api/v1/rules
{
  "name": "Global: block tor exit nodes",
  "priority": 9000,
  "directives": "..."
}

Поля Custom Rule

Порядок применения правил

1. SecRuleRemoveById (исключения disable)
2. SecRuleUpdateTargetById (исключения exclude_arg/header)
3. URL-scoped исключения (exclude_url)
4. Глобальные custom rules (sorted by priority)
5. Per-site custom rules (sorted by priority)
6. WAFPolicy.custom_directives (inline поле)

23. События WAF

Раздел UI: WAF Events (доступен глобально или через вкладку сайта).

Каждое срабатывание WAF записывает событие:

Используйте Rule ID из событий для создания точечных исключений.

Часть VI: Фильтрация по GeoIP

24. Настройка GeoIP

GeoIP-политика позволяет разрешить трафик только из определённых стран.

API:

GET /api/v1/sites/{siteId}/geoip
PUT /api/v1/sites/{siteId}/geoip
{
  "enabled": true,
  "map_file": "/etc/ha-waf/geoip.txt",
  "allowed_countries": ["RU", "BY", "KZ"],
  "deny_status": 403,
  "add_country_header": true
}

Логика: Если IP найден в карте и его страна НЕ в allowed_countries — блокировать. Если IP не найден в карте — разрешить (не блокировать неизвестных).

25. Формат GeoIP-карты

Файл карты: один CIDR на строку, разделённый пробелом от кода страны:

# GeoIP map — формат: CIDR ISO-3166-1
1.0.0.0/24 AU
1.0.1.0/24 CN
5.8.18.0/23 RU
77.88.0.0/18 RU

HA-WAF не скачивает GeoIP автоматически — вы должны предоставить карту самостоятельно. Рекомендуемые источники:

• MaxMind GeoLite2 (бесплатно с регистрацией)
• ip-api.com bulk export
• DB-IP free editions

При обновлении файла на диске достаточно нажать Reload в UI или вызвать POST /api/v1/reload.

Часть VII: IP-списки

26. Белые списки (Whitelist)

Whitelist разрешает трафик с указанных CIDR минуя все проверки.

POST /api/v1/sites/{siteId}/iplists
{
  "name": "Internal Networks",
  "type": "whitelist",
  "enabled": true,
  "cidrs": ["10.0.0.0/8", "192.168.0.0/16", "172.16.0.0/12"],
  "bypass_waf": true
}

Если bypass_waf = false, трафик разрешён, но WAF всё равно проверяет запросы.

27. Чёрные списки (Blacklist)

Blacklist блокирует трафик с указанных CIDR с кодом 403.

POST /api/v1/sites/{siteId}/iplists
{
  "name": "Blocked IPs",
  "type": "blacklist",
  "enabled": true,
  "cidrs": ["1.2.3.4/32", "5.6.7.0/24"]
}

Порядок проверок в HAProxy:

1. Blacklist: IP в чёрном списке? → 403
2. GeoIP: страна запрещена? → 403
3. Whitelist + bypass_waf: IP в белом списке? → разрешить (пропустить WAF)
4. WAF проверка
5. Whitelist без bypass_waf: IP в белом списке? → разрешить (после WAF)

Часть VIII: Rate Limiting

28. Правила ограничения частоты запросов

Rate Limiting работает через shared stick-table в HAProxy. Ограничения применяются по IP клиента.

POST /api/v1/sites/{siteId}/ratelimits
{
  "name": "Global rate limit",
  "enabled": true,
  "http_req_rate": 100,
  "conn_rate": 50,
  "bytes_in_rate": 1048576,
  "deny_status": 429
}

Можно задать несколько правил — они все применяются (логика OR: любое превышение → блокировка).

29. Path-prefix и regex фильтры

Rate Limit можно привязать только к определённому пути:

POST /api/v1/sites/{siteId}/ratelimits
{
  "name": "API rate limit",
  "http_req_rate": 30,
  "path_prefixes": ["/api/", "/graphql"],
  "deny_status": 429
}

Или по регулярному выражению:

{
  "path_regex": "^/api/v[0-9]+/",
  "http_req_rate": 20
}

path_prefixes и path_regex взаимоисключающие. Если оба пусты — правило применяется ко всем запросам сайта.

Часть IX: Path Rules (nginx location blocks)

30. Обзор Path Rules

Path Rules — аналог location блоков в nginx. Позволяют настроить специальное поведение для конкретных URL-путей L7 сайта:

• Проксировать на другой upstream (например, API → другой сервис)
• Вернуть статический ответ
• Выполнить redirect
• Применить rate limit только к этому пути
• Отключить WAF-правила для этого пути
• Настроить WebSocket или gRPC туннель
• Модифицировать заголовки запроса/ответа

Вкладка в UI: Site → Path Rules

31. Тип совпадения пути

POST /api/v1/sites/{siteId}/pathrules
{
  "name": "API Proxy",
  "enabled": true,
  "path": "/api/",
  "match_type": "prefix",
  "priority": 10,
  "action": "proxy",
  ...
}

32. Действия (Actions)

33. Проксирование (proxy)

{
  "action": "proxy",
  "upstream_addr": "10.0.0.20:3000",
  "upstream_scheme": "http",
  "websocket": false,
  "grpc": false,
  "ssl_enabled": false,
  "ssl_verify_none": false,
  "ssl_sni": "",
  "timeout_connect": 5,
  "timeout_server": 60,
  "lb_algorithm": "roundrobin",
  "retries": 2,
  "check_enabled": false
}

34. Статический ответ (return)

{
  "action": "return",
  "return_status": 200,
  "return_type": "application/json",
  "return_body": "{\"status\":\"ok\"}"
}

Применение: healthcheck-эндпоинты, заглушки для временно отключённых маршрутов, статические JSON-ответы.

35. Перенаправление (redirect)

{
  "action": "redirect",
  "redirect_url": "https://new-site.example.com/path",
  "redirect_code": 301
}

36. Условия (Conditions)

Conditions позволяют применять Path Rule только при выполнении дополнительных условий (кроме совпадения пути).

{
  "conditions": [
    {
      "type": "header",
      "name": "X-Internal",
      "value": "true",
      "negate": false
    },
    {
      "type": "src_cidr",
      "value": "10.0.0.0/8",
      "negate": false
    }
  ]
}

Все условия объединяются логикой AND — правило применяется, только если все условия выполнены.

Типы условий

Поле negate: true инвертирует условие (NOT).

37. Rate limit для Path Rule

{
  "rate_limit": {
    "enabled": true,
    "http_req_rate": 50,
    "conn_rate": 20,
    "bytes_in_rate": 524288,
    "window": 15,
    "deny_status": 429
  }
}

Rate limit для Path Rule использует отдельный счётчик (sc2) независимо от глобального rate limit сайта (sc0).

38. WAF-исключения для Path Rule

{
  "waf_exclude_ids": [942100, 942200, 941100]
}

Список CRS rule ID, которые отключаются только для запросов, совпавших с этим Path Rule. Генерирует Coraza SecRule с REQUEST_URI @beginsWith {path}.

Применение: API-эндпоинты, где тело запроса содержит SQL-подобные данные или специфический формат (например, GraphQL queries).

39. Модификация заголовков

{
  "request_headers": [
    {"action": "set",  "name": "X-Forwarded-Prefix", "value": "/api"},
    {"action": "del",  "name": "X-Internal-Token"}
  ],
  "response_headers": [
    {"action": "set",  "name": "X-Frame-Options", "value": "DENY"},
    {"action": "add",  "name": "X-Content-Type-Options", "value": "nosniff"}
  ]
}

40. WebSocket

{
  "action": "proxy",
  "path": "/ws",
  "match_type": "prefix",
  "upstream_addr": "10.0.0.5:3001",
  "websocket": true,
  "timeout_tunnel": 3600
}

При websocket: true HAProxy включает timeout tunnel для поддержки длительных соединений. Никакой специальной настройки proto не требуется — WebSocket-upgrade прозрачен через HTTP/1.1.

timeout_tunnel — время бездействия туннеля в секундах (по умолчанию 3600 = 1 час). Установите 0 для бесконечного туннеля.

41. gRPC

{
  "action": "proxy",
  "path": "/grpc.",
  "match_type": "prefix",
  "upstream_addr": "10.0.0.5:9090",
  "upstream_scheme": "h2c",
  "grpc": true,
  "timeout_tunnel": 3600
}

При grpc: true или upstream_scheme: "h2"/"h2c" HAProxy добавляет proto h2 в строку server, обеспечивая gRPC через cleartext HTTP/2 (h2c).

Для gRPC с TLS к upstream используйте upstream_scheme: "https" + ssl_enabled: true.

42. Множество upstream-серверов

Вместо upstream_addr можно задать список серверов (servers):

{
  "action": "proxy",
  "lb_algorithm": "leastconn",
  "servers": [
    {"name": "api-1", "address": "10.0.0.10", "port": 3000, "weight": 10},
    {"name": "api-2", "address": "10.0.0.11", "port": 3000, "weight": 10},
    {"name": "api-3", "address": "10.0.0.12", "port": 3000, "weight": 5}
  ]
}

Поля серверов в Path Rule аналогичны полям обычного бэкенда, плюс опции SSL и PROXY protocol.

43. Приоритеты и порядок обработки

Path Rules сортируются по полю priority (меньше = выше приоритет). В случае нескольких совпадений побеждает правило с наименьшим priority.

Рекомендованные диапазоны:

• 1–9 — критические маршруты (блокировки, health checks)
• 10–99 — основные маршруты
• 100–999 — fallback маршруты

Порядок в HAProxy-конфиге:

1. Все http-request return (статические ответы)
2. Все http-request redirect
3. Все http-request track-sc2 (rate limits)
4. use_backend be_ha_waf_api if acme_challenge
5. Все use_backend be_pr_* (path rule proxy)
6. use_backend be_* (основной бэкенд сайта)

Часть X: TLS и сертификаты

44. Загрузка сертификата (Upload)

UI: Раздел Certificates → кнопка Upload PEM

Принимается PEM-файл, содержащий сертификат (цепочку) + приватный ключ:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (intermediate CA)
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

API:

POST /api/v1/certs
Content-Type: application/json
{
  "name": "example.com.pem",
  "pem_data": "-----BEGIN CERTIFICATE-----\n..."
}

Сертификат сохраняется в БД и записывается в ssl_cert_dir при следующем reload. HAProxy загружает все .pem-файлы из директории.

45. Массовый импорт архива

Загрузка ZIP или TAR.GZ архива с множеством сертификатов. HA-WAF автоматически:

• Ищет пары .crt + .key (сопоставляет по CN)
• Распознаёт самодостаточные .pem бандлы
• Импортирует всё в базу данных

UI: Certificates → Import Archive

API:

POST /api/v1/certs/upload-archive?auto_renew=true
Content-Type: application/zip

<тело — сырые байты архива, не multipart>

Импорт выполняется асинхронно, эндпоинт сразу отвечает 202 Accepted с {"job_id": "..."}. Статус проверяется через:

GET /api/v1/certs/upload/{jobId}

Ответ содержит: status (pending/running/done/failed), done/total, список items с результатом по каждому сертификату.

46. ACME-аккаунты — мультиаккаунтная модель

HA-WAF поддерживает неограниченное количество ACME-аккаунтов. Это позволяет:

• Использовать разные Let's Encrypt-аккаунты для разных команд/клиентов
• Смешивать HTTP-01 и DNS-01 challenge в рамках одной инсталляции
• Подключать разных DNS-провайдеров для wildcard-сертификатов

Один аккаунт помечается default — он используется при выпуске сертификата без явного указания аккаунта.

Управление аккаунтами через UI

Settings → ACME Accounts — страница управления аккаунтами. Прямая ссылка: /#/settings?tab=acme.

Доступные действия:

• Add account — создать новый аккаунт (HTTP-01 или DNS-01)
• ✏️ Редактировать — изменить name, email, challenge, credentials
• ★ Set as default — назначить аккаунт по умолчанию
• 🗑 Delete — удалить (нельзя удалить default и последний аккаунт)

Создание аккаунта (API)

POST /api/v1/acme/accounts
{
  "name": "Production LE",
  "email": "ops@example.com",
  "challenge_type": "http01",
  "staging": false,
  "is_default": true
}

Ответ: 201 Created с объектом аккаунта (без приватного ключа).

Staging URL: https://acme-staging-v02.api.letsencrypt.org/directory

Получение и обновление аккаунта

GET    /api/v1/acme/accounts           # список всех аккаунтов
GET    /api/v1/acme/accounts/{id}      # один аккаунт
PUT    /api/v1/acme/accounts/{id}      # обновить
DELETE /api/v1/acme/accounts/{id}      # удалить
POST   /api/v1/acme/accounts/{id}/set-default  # назначить дефолтным

PUT-семантика:

• Изменение name — не сбрасывает ACME-регистрацию (экономит API-лимиты Let's Encrypt)
• Изменение email, directory_url или staging — сбрасывает регистрацию; при следующем выпуске сертификата HA-WAF перерегистрирует аккаунт на ACME-сервере
• DNS credentials: пустой {} в теле запроса означает «не менять»; чтобы обновить отдельные ключи, передай только изменившиеся

Назначение аккаунта по умолчанию

POST /api/v1/acme/accounts/{id}/set-default

Ответ: обновлённый объект аккаунта с "is_default": true. Предыдущий default сбрасывается атомарно.

47. Выпуск сертификата через ACME

Шаг 1: Убедиться, что аккаунт настроен

UI: Certificates — раздел ACME Accounts в верхней части страницы покажет текущий default-аккаунт. Кнопка Manage ведёт в Settings → ACME Accounts.

Шаг 2: Убедиться, что сайт доступен (для HTTP-01)

• Порт 80 должен быть доступен публично
• HA-WAF автоматически отвечает на /.well-known/acme-challenge/*
• Если бэкенд также запрашивает собственный LE-сертификат (например, Caddy), убедись, что он принимает PROXY protocol — HA-WAF пробрасывает challenge-запрос с PROXY v1 header, если бэкенд настроен с send_proxy

Шаг 3: Выпустить сертификат

UI: Кнопка Issue via ACME → ввести домены → выбрать аккаунт → Issue.

POST /api/v1/acme/issue
{
  "cert_name": "example.com.pem",
  "domains": ["example.com", "www.example.com"],
  "auto_renew": true,
  "account_id": ""
}

Ответ: 202 Accepted с объектом ACMEJob (см. §50). Статус выпуска можно опросить:

GET /api/v1/acme/jobs/{jobId}

Выпуск для конкретного сайта (все домены сайта автоматически):

POST /api/v1/sites/{siteId}/acme/issue

48. DNS-01 challenge

DNS-01 позволяет выпускать wildcard-сертификаты и работает без публичного доступа на порт 80.

Поддерживаемые DNS-провайдеры

Создание DNS-01 аккаунта

POST /api/v1/acme/accounts
{
  "name": "Wildcard via Cloudflare",
  "email": "admin@example.com",
  "challenge_type": "dns01",
  "dns_provider": "cloudflare",
  "dns_credentials": {
    "CF_API_TOKEN": "your-cloudflare-token"
  }
}

Безопасность: credentials хранятся в БД. UI никогда не возвращает сохранённые значения в GET-запросах — при редактировании аккаунта нужно ввести только изменившиеся ключи.

Выпуск wildcard-сертификата

POST /api/v1/acme/issue
{
  "cert_name": "example.com-wildcard.pem",
  "domains": ["*.example.com", "example.com"],
  "auto_renew": true,
  "account_id": "<id dns01-аккаунта>"
}

Yandex Cloud: подготовка ключа

# Создать сервисный аккаунт с ролью dns.editor
# Скачать JSON-ключ и закодировать:
cat key.json | base64 -w 0
# Полученную строку вставить в YANDEX_CLOUD_IAM_TOKEN

49. Автообновление сертификатов

HA-WAF каждые 12 часов проверяет все сертификаты с флагом auto_renew: true:

• Если до истечения осталось менее 30 дней — инициирует обновление через ACME
• Используется тот же аккаунт, который был указан при первоначальном выпуске
• Если аккаунт удалён — автоматически используется current default
• После обновления — автоматически применяет новый сертификат (reload HAProxy)

Включить/отключить auto_renew для сертификата:

PATCH /api/v1/certs/{name}
{"auto_renew": true}

В UI — кнопка 🔄 в строке сертификата (синяя = включено, серая = отключено).

Ручное обновление:

POST /api/v1/acme/renew/{name}

50. Асинхронные job'ы выпуска (JobRunner)

Выпуск и перевыпуск сертификатов (/acme/issue, /sites/{siteId}/acme/issue, /acme/renew/{name}) выполняются асинхронно: эндпоинт сразу отвечает 202 Accepted с объектом job'а, а сама работа с ACME-сервером идёт в фоне (internal/acme/jobs.go, JobRunner). Это защищает API-запрос от таймаута при медленном DNS-01 challenge или недоступном ACME-сервере.

GET /api/v1/acme/jobs           # все job'ы в памяти, новые сначала
GET /api/v1/acme/jobs/{jobId}   # статус конкретного job'а

Статусы: pending → running → done | failed. Типы: issue (ручной выпуск), renew (перевыпуск), site_issue (массовый выпуск для всех доменов сайта). JobRunner не даёт запустить второй job для того же cert_name/сайта параллельно — повторный запрос вернёт 409 Conflict.

Тот же JobRunner управляет и фоновым авто-обновлением (§49) — ручной запуск через API и автоматический таймер используют один и тот же механизм постановки в очередь.

51. Отслеживание ошибок выпуска (Cert Failures)

Если job выпуска/перевыпуска завершается неудачей, запись об этом сохраняется отдельно от самого job'а — с историей попыток и настраиваемым автоповтором (internal/certimport, таблица cert_failures).

GET    /api/v1/acme/failures                  # список
GET    /api/v1/acme/failures/{id}
PATCH  /api/v1/acme/failures/{id}             # изменить auto_retry / next_retry_at
DELETE /api/v1/acme/failures/{id}
POST   /api/v1/acme/failures/{id}/retry       # повторить немедленно

Статусы записи: pending (ожидает повтора) → resolved (сертификат успешно выпущен) | cancelled (повторы отключены вручную). Поле error_code классифицирует причину (напр. dns_challenge_failed, rate_limited) — используется UI для группировки ошибок в разделе Certificates → Failures.

52. Per-site переопределение директории сертификатов

По умолчанию HAProxy загружает сертификаты из глобальной ssl_cert_dir. Для конкретного сайта можно указать другую директорию:

PUT /api/v1/sites/{siteId}
{
  "ssl_cert_dir": "/etc/ha-waf/certs/tenant-a/"
}

Это позволяет изолировать сертификаты разных тенантов.

Часть XI: Пользователи и API-ключи

53. Управление пользователями

UI: Раздел Settings → Users

GET    /api/v1/users              # список пользователей
POST   /api/v1/users              # создать
PUT    /api/v1/users/{id}         # обновить (role и/или password)
DELETE /api/v1/users/{id}         # удалить
POST   /api/v1/auth/password      # сменить СВОЙ пароль (self-service)

POST /api/v1/users
{
  "username": "operator",
  "password": "secure-password",
  "role": "viewer"
}

Смена пароля другому пользователю администратором — через PUT /api/v1/users/{id} с полем password (не отдельный эндпоинт).

Пользователи, ожидающие подтверждения. Аккаунты, созданные через OIDC self-registration (см. Часть XII: OIDC / SSO), получают статус pending и не могут войти, пока администратор не назначит им роль:

GET /api/v1/users/pending           # список ожидающих
PUT /api/v1/users/{id}/role         # назначить роль → переводит в active
{ "role": "viewer" }

54. Роли и права доступа

55. API-ключи

API-ключи предназначены для автоматизации (скрипты, CI/CD, мониторинг).

Создать ключ:

POST /api/v1/users/{userId}/api-keys
{
  "name": "Deployment script",
  "expires_at": "2027-01-01T00:00:00Z"
}

Ответ содержит сырой ключ — он показывается один раз и нигде не сохраняется:

{
  "id": "uuid",
  "name": "Deployment script",
  "key": "hwaf_a3f8d2...",
  "expires_at": "2027-01-01T00:00:00Z"
}

Использование:

X-API-Key: hwaf_a3f8d2...

Список ключей пользователя:

GET /api/v1/users/{userId}/api-keys

Удалить ключ:

DELETE /api/v1/users/{userId}/api-keys/{keyId}

Часть XII: OIDC / SSO

Enterprise-функция: требует лицензию с фичей oidc (см. Часть XIII: Лицензирование). Без лицензии эта часть неактуальна — публичные роуты входа не регистрируются, а вход остаётся только по логину/паролю.

56. Настройка провайдера

Провайдер настраивается через Settings → SSO в UI или напрямую через API (admin-роль):

POST /api/v1/auth/providers
{
  "name": "Corporate SSO",
  "client_id": "ha-waf",
  "client_secret": "...",
  "discovery_url": "https://idp.example.com/.well-known/openid-configuration",
  "enabled": true
}

discovery_url должен указывать на OpenID Connect discovery document провайдера (Keycloak, Authentik, Okta, Azure AD и т.п. — любой стандартный OIDC IdP). client_secret шифруется перед сохранением тем же ключом, что и source_pass у списков доменов, и никогда не возвращается обратно через API. Изменение провайдера без указания client_secret в теле запроса сохраняет прежний секрет.

57. Поток входа

1. Пользователь на странице логина видит кнопку провайдера (список берётся из GET /auth/oidc/providers — публичный роут, отдаёт только {id, name} включённых провайдеров).
2. Переход на GET /auth/oidc/{providerId}/login — HA-WAF генерирует PKCE code verifier/challenge и state, кладёт их в HMAC-подписанную cookie (ключ выводится из JWT secret), и редиректит на authorization endpoint провайдера.
3. После входа провайдер редиректит обратно на GET /auth/oidc/{providerId}/callback — HA-WAF обменивает code на токены, проверяет id_token (issuer, audience, подпись), и по sub/email/name делает upsert пользователя.
4. Если пользователь новый — создаётся со статусом pending, вход отклоняется (редирект на /login?pending=true) до тех пор, пока администратор не назначит роль (см. §53). Уже одобренный пользователь получает обычный HA-WAF JWT и cookie-сессию.
5. Активная сессия сохраняется в таблице OIDCSession (по jti токена) — это нужно для backchannel logout.

Оба публичных роута (/auth/oidc/providers — без лимита, /auth/oidc/{id}/login — 10 запросов/мин с IP) находятся вне /api/v1, в отличие от остального API.

58. Backchannel Logout

HA-WAF реализует OpenID Connect Back-Channel Logout 1.0: если IdP инициирует логаут (например, администратор IdP принудительно завершает сессию пользователя), провайдер отправляет POST с logout_token на:

POST /auth/backchannel-logout    (без auth, 5 запросов/мин с IP, вне /api/v1)

HA-WAF извлекает issuer из токена (без полной валидации, только для поиска провайдера — signature проверяется отдельно), находит соответствующий OIDCProvider по issuer'у и отзывает все активные OIDCSession этого пользователя. Отозванная сессия перестаёт проходить JWT middleware при следующем запросе, даже если сам JWT ещё не истёк. Если провайдер не найден — эндпоинт всё равно отвечает 200 OK, чтобы не раскрывать список настроенных провайдеров.

Часть XIII: Лицензирование

59. Модель лицензирования

Лицензия — это offline-проверяемый JWT-токен (Ed25519-подпись), не требующий обращения к внешнему серверу активации. Публичный ключ для проверки подписи зашит в бинарник HA-WAF. Указывается в config.yaml:

license_key: "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...."

или через переменную окружения HAWAF_LICENSE_KEY (удобно для k8s Secret — не хранить ключ в ConfigMap открытым текстом).

Без ключа (или при пустом license_key) HA-WAF работает в режиме Community — все базовые функции (WAF, сайты, сертификаты, rate limiting, GeoIP, k8sban и т.д.) доступны без ограничений; лицензия нужна только для отдельных enterprise-фич.

60. Статусы и фичи

GET /api/v1/license

{
  "status": "valid",
  "customer": "Acme Corp",
  "features": ["oidc"],
  "expires_at": "2027-01-01T00:00:00Z",
  "days_until_expiry": 180
}

На момент написания единственная лицензируемая фича — oidc (SSO-провайдеры, см. Часть XII). Попытка обратиться к её эндпоинтам без валидной лицензии возвращает 402 Payment Required.

Часть XIV: k8sban — сетевой бан через Cilium

Только для установки в Kubernetes с CNI Cilium. На self-hosted (Docker Compose) — недоступно.

61. Зачем это нужно

Штатный «WAF IP Ban» (config.haproxy.waf_ban_enabled) банит IP на уровне HAProxy: после N WAF-блокировок IP получает 429 на все последующие запросы. Это работает, но каждый забаненный запрос всё равно доходит до HAProxy — тратится TCP/TLS-хендшейк и цикл обработки запроса. k8sban зеркалит те же баны в CiliumClusterwideNetworkPolicy, чтобы Cilium дропал трафик забаненного IP на сетевом уровне (eBPF), до попадания в под HA-WAF — HAProxy такой пакет вообще не видит.

62. Включение

Два независимых переключателя — нужны оба:

1. На уровне чарта (деплой-тайм, даёт RBAC):

   # values.yaml
   k8sNetworkBan:
     enabled: true   # по умолчанию true с версии чарта 0.4.1
   
   config:
     k8s_network_ban:
       enabled: true
       policy_name: ha-waf-ip-ban   # опционально
       poll_interval: "10s"          # опционально
       ports: ["80", "443"]          # опционально
   

   Включение создаёт ClusterRole/ClusterRoleBinding с правами get/list/watch/create/update/patch на ciliumclusterwidenetworkpolicies (cluster-scoped ресурс) и монтирует токен ServiceAccount пода — это реальное расширение прав, см. SECURITY.md.
2. На уровне рантайма (тот же тумблер, что и для L7-бана): config.haproxy.waf_ban_enabled: true — без него k8sban ничего не забанит, даже если чарт-флаг включён.

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

Раз в poll_interval (по умолчанию 10с) каждый под HA-WAF независимо:

1. Читает свою локальную HAProxy stick-table (show table ha_waf_ban_table через admin socket) — список IP, у которых счётчик WAF-блокировок достиг порога.
2. Сливает эти IP в общий объект CiliumClusterwideNetworkPolicy с именем policy_name (по умолчанию ha-waf-ip-ban), выставляя spec.ingressDeny.fromCIDR.
3. Одновременно выставляет spec.ingress с fromEntities: ["all"] на те же порты — без этого правила ingressDeny перевёл бы под в режим default-deny для всего входящего трафика, а не только для забаненных IP (это реальная авария, поймана и исправлена при внедрении фичи — см. issue-трекер проекта).

Почему без leader election. Stick-table у каждого пода своя и не синхронизируется между репликами (peers-секция в HAProxy не настроена). Вместо того чтобы выяснять, какой под «владеет» каким баном, срок жизни каждой записи хранится в JSON-аннотации на самом объекте (ha-waf.io/ban-expiry: {"1.2.3.4/32": "2026-07-28T22:00:00Z"}). Любой под на каждом цикле: добавляет свои текущие баны с новым временем истечения и удаляет из общего списка записи, чей срок истёк — вне зависимости от того, кто их туда добавил. После падения/пересоздания пода его баны просто перестают продлеваться и самостоятельно «вымываются» остальными репликами при следующем истечении TTL.

Посмотреть текущие баны:

kubectl get ciliumclusterwidenetworkpolicies.cilium.io ha-waf-ip-ban -o yaml

Что это не защищает. Дроп происходит на узле, куда пакет уже попал (до userspace HAProxy) — это снимает нагрузку с пода/узла, но не спасает от насыщения аплинк-канала при объёмной атаке (для этого нужен внешний anti-DDoS слой — Cloud Armor/Shield или RTBH у транзитного оператора, вне зоны ответственности HA-WAF).

Часть XV: Метрики и телеметрия

64. Prometheus метрики

HA-WAF экспортирует метрики через два endpoint:

Ключевые метрики HAProxy

Для фильтрации по конкретному сайту используйте label:

proxy="be_<site_id_with_underscores>"

Пример PromQL для запросов к сайту my-app (UUID abc-def):

sum(rate(haproxy_backend_http_responses_total{proxy="be_abc_def"}[5m]))

Метрика WAF

Пер-доменная разбивка по sni не является label метрик waf_*_total — метки намеренно ограничены (site_id/mode), чтобы избежать неограниченной кардинальности и риска для памяти сервиса. Стройте графики по доменам из логов: HAProxy access-логи несут sni (все запросы), лог WAF-события несёт sni для заблокированных — на уровне преобразования лог→метрика (Loki/Prometheus recording rules и т.п.).

65. OpenTelemetry (OTLP)

HA-WAF поддерживает отправку traces, metrics и logs через OTLP gRPC.

telemetry:
  otlp:
    endpoint: "otel-collector:4317"
    insecure: true
    logs:
      enabled: true
    metrics:
      enabled: true
    traces:
      enabled: true

Дополнительные OTLP-exporters можно настроить через UI (раздел Telemetry) или API:

POST /api/v1/telemetry/exporters
{
  "name": "Main collector",
  "type": "otlp",
  "enabled": true,
  "endpoint": "collector.monitoring.svc:4317",
  "insecure": true,
  "signals": ["logs", "metrics", "traces"]
}

66. Дашборд метрик в UI

Раздел UI: Metrics

Показывает PromQL-графики за выбранный временной диапазон:

• Requests/sec (входящие)
• HTTP Error Rate (4xx, 5xx)
• Active Connections
• Bandwidth (bytes in/out)
• WAF blocks/sec
• P95 Response Time

Фильтр по сайту: Выбор конкретного сайта из dropdown скрыт в header дашборда — автоматически добавляет {proxy="be_<id>"} к каждому PromQL-запросу.

Для работы дашборда необходим Prometheus/VictoriaMetrics с метриками HAProxy на :8405.

Часть XVI: Конфиг-ревизии

67. Что такое ревизия

При каждом reload HA-WAF создаёт снапшот конфигурации:

• Полный дамп всех сущностей БД в JSON
• Сгенерированный текст haproxy.cfg
• Время применения и пользователь

UI: Раздел Config → Revisions

68. Просмотр и откат

Список ревизий:

GET /api/v1/config/revisions

Просмотр конкретной ревизии:

GET /api/v1/config/revisions/{id}

Diff между текущим состоянием БД и последней ревизией:

GET /api/v1/config/diff

Возвращает JSON diff с полями added, removed, changed для каждой сущности.

Откат к ревизии:

POST /api/v1/config/revisions/{id}/rollback

Восстанавливает состояние БД из ревизии и выполняет reload. Создаёт новую ревизию.

Статус несохранённых изменений:

GET /api/v1/config/status
# {"has_pending_changes": true}

Отменить несохранённые изменения:

POST /api/v1/config/discard

69. Экспорт и импорт конфигурации

Экспорт (полный бэкап конфига):

GET /api/v1/export

Возвращает JSON со всеми сущностями. Используйте для бэкапов и переноса конфига между инстансами.

Импорт:

POST /api/v1/import
Content-Type: application/json

{"sites": [...], "certs": [...], ...}

Импорт заменяет существующую конфигурацию. Сделайте экспорт перед импортом.

Часть XVII: Страницы ошибок

70. Кастомные error pages

HA-WAF позволяет задать кастомные HTML-страницы для стандартных HTTP ошибок.

UI: Раздел Error Pages

Поддерживаемые коды: 400, 403, 404, 429, 500, 502, 503, 504

GET /api/v1/error-pages                     # список
GET /api/v1/error-pages/{code}              # получить страницу
PUT /api/v1/error-pages/{code}              # сохранить
DELETE /api/v1/error-pages/{code}           # сбросить к умолчанию

PUT /api/v1/error-pages/403
{
  "code": 403,
  "content": "<!DOCTYPE html><html>...</html>"
}

Страницы сохраняются в error_dir (/etc/ha-waf/errors/) и подключаются в HAProxy через директиву errorfile.

Часть XVIII: Настройки системы

71. System Config через UI

UI: Раздел Settings → System

Позволяет переопределить параметры из config.yaml через веб-интерфейс без перезапуска сервиса. Изменения сохраняются в БД и применяются при следующем reload.

Управляемые параметры:

• HAProxy maxconn, таймауты, SSL-опции
• Порты HTTP/HTTPS
• Адрес SPOA
• Bind метрик
• Параметры GeoIP

GET /api/v1/config
PUT /api/v1/config
{
  "maxconn": 100000,
  "timeout_connect": 5,
  "timeout_client": 30,
  "timeout_server": 60
}

Часть XX: Защита от ботов (Anti-Bot)

75. Обзор стека защиты от ботов

HA-WAF включает встроенный anti-bot стек — набор механизмов, встроенных в генерируемый конфиг HAProxy и SPOA-агент Coraza. Стек развивался в два этапа: этап 1 (#157) — quick wins чистым конфигом HAProxy, этап 2 (#158) — IP-reputation, verified bots, challenge и honeypot.

Порядок обработки запроса (фиксирован шаблоном конфига):

whitelist (bypass WAF) → WAF domain bypass → GeoIP → IP-reputation →
IP-blacklist → verified bots → Bot Policy (UA-фильтры) →
Coraza/SPOE (CRS + honeypot/challenge-детект) → WAF-deny →
honeypot-реакция → challenge → rate limits (conn_cur и др.) →
throttle → path rules → backend

Принцип: дешёвые проверки — раньше дорогих. Бот, заблокированный UA-фильтром или reputation-фидом, не расходует WAF-конвейер; challenge стоит после SPOE, потому что его вердикты приходят оттуда же.

Матрица «угроза → механизм»:

Глубокая документация по каждому механизму — в каталоге docs/anti-bot/ (README стека + stage-доки).

UI: механизмы настраиваются вкладками сайта — Политика ботов, IP-репутация, Челлендж, Ловушки, а conn_cur — в Ограничениях запросов.

76. Per-site Bot Policy (UA-фильтры)

Per-site фильтрация по заголовку User-Agent. Работает на уровне HAProxy-ACL до Coraza/SPOE — заблокированный бот не расходует WAF.

Вкладка в UI: Site → Политика ботов

PUT /api/v1/sites/{siteId}/bot-policy
{
  "enabled": true,
  "entries": [
    {"pattern": "python-requests", "match_type": "sub",   "action": "block",  "comment": "скрипты"},
    {"pattern": "scrapy",          "match_type": "sub",   "action": "tarpit", "comment": "скрейпер"},
    {"pattern": "UptimeRobot",     "match_type": "sub",   "action": "allow",  "comment": "мониторинг"},
    {"pattern": "",                "match_type": "empty", "action": "block"}
  ]
}

Порядок обработки: allow-записи вычисляются первыми, затем reject-действия. Кроме bot_allow reject-правила обходят: ACME-путь /.well-known/acme-challenge/ (паттерн вроде bot не ломает выпуск сертификатов), верифицированные боты (txn.verified_bot, гл. 80) и WAF-whitelist (txn.waf_bypass).

Валидация паттернов. Паттерны вставляются в конфиг HAProxy без кавычек, поэтому API отвергает пробелы, переводы строк и # (инъекция директив), а также паттерн с завершающим \ (склейка строк). Для match_type=reg регекс проверяется компиляцией Go RE2 — отдельные PCRE-конструкции (lookahead, backreference) допустимы в HAProxy, но API их не пропустит.

Tarpit удерживает слот maxconn на всё время удержания соединения — используйте только для точечных записей. Decoy отвечает нейтральным 200 OK и не раскрывает блокировку.

Матчинг всех типов регистронезависимый; empty ловит и полностью отсутствующий заголовок, и User-Agent: нулевой длины.

Типичные паттерны: curl, python-requests, scrapy, wget, Go-http-client (sub + block); пустой UA (empty + block); агент мониторинга (UptimeRobot и т.п. — sub + allow). Не блокируйте UA честных краулеров (Googlebot, bingbot) — спуфинг их UA закрывает verified bots (гл. 80), а блокировка может отрезать настоящий поисковый краулер.

77. Защита от Slowloris (conn_cur)

Медленные L7-атаки (Slowloris: клиент держит соединения открытыми, досыпая заголовки каплями) закрываются двумя настройками.

Вкладка в UI: Site → Ограничения запросов, блок «Текущие соединения (0 = отключено)», поле «Макс. одновременных».

POST /api/v1/sites/{siteId}/ratelimits
{
  "name": "Conn cap",
  "enabled": true,
  "conn_cur": 15
}

Счётчики ведутся в общей stick-table ha_waf_rate_table (ключ sc0, общий с прочими rate-метриками сайта). Консервативный порог — 10–20; UI подставляет дефолт 10.

CGNAT. За общим NAT (мобильные операторы, корпоративные сети) сотни легитимных пользователей идут с одного IP — не ставьте порог агрессивно низко. Для сайтов с мобильной аудиторией поднимайте по факту трафика (десятки–сотни).

Вторая линия — глобальный timeout http-request 10s (в defaults сгенерированного конфига): клиент, не завершивший отправку запроса за 10 секунд, обрывается, не удерживая слот бесконечно.

Ограничения: per-site rate-правила (включая conn_cur) рендерятся на HTTPS-фронтенде и кастомных HTTP/HTTPS-портах, но не на общем фронтенде :80 — включайте site-level «Redirect HTTP → HTTPS», чтобы plain-HTTP-трафик не обходил лимиты. Stick-table имеет тип ip — счётчики ведутся только для IPv4-клиентов.

78. Tarpit и decoy

Два «тихих» действия антибот-арсенала. Доступны как действия Bot Policy (гл. 76) и как реакция honeypot (гл. 82).

Tarpit занимает слот maxconn на всё время удержания. Массовые tarpit-правила (сотни паттернов, public-сайт под нагрузкой) съедают лимит соединений — держите tarpit для узкого списка. Для массовой фильтрации используйте block или decoy.

Оба действия наследуют гварды reject-правил Bot Policy: не срабатывают на ACME-пути, для верифицированных ботов, allow-записей и WAF-whitelist.

79. IP-Reputation фиды

Блокировка (или логирование) IP из внешних reputation-фидов: Spamhaus DROP, FireHOL, blocklist.de. Фиды скачивает сам HA-WAF в map-файлы; внешних сервисов и ключей не нужно.

Вкладка в UI: Site → IP-репутация (там же — статус снапшотов фидов).

PUT /api/v1/sites/{siteId}/ip-reputation
{
  "enabled": true,
  "mode": "log",
  "sources": ["spamhaus_drop", "firehol_l1"],
  "exceptions": ["203.0.113.0/24"]
}

Глобального переключателя нет: фиды скачиваются всегда (≈6 мелких запросов в час, условный GET с ETag), управление — только per-site политиками. Политика стоит в пайплайне сразу после GeoIP, до IP-blacklist и bot-правил.

Статус фидов (внизу вкладки / GET /api/v1/iprep/status): по каждому источнику — возраст снапшота, количество IP (ips), флаги stale (снапшот старше 24 ч или отсутствует) и held (новый снапшот отличался от предыдущего больше чем на ±50 % записей — обновление отложено, источник держится на старом списке). В enforce-режиме stale-источники не блокируют (поведение как в log); сайт, у которого все выбранные источники stale, целиком переходит в log-режим.

Начинайте с log. Держите режим наблюдения 1–2 недели до перехода на enforce: фид может занести ваш корпоративный диапазон — сразу заведите его в exceptions.

blocklist.de собирается из fail2ban-отчётов и даёт высокий риск ложных срабатываний на CGNAT-соседей. Не используйте как единственный источник. spamhaus_asndrop сейчас парсится в пустой список (фид содержит только ASN без префиксов) — статус честно показывает ips: 0.

Юридическая оговорка. HA-WAF не редистрибутирует списки — скачивает их на лету для своего экземпляра и ссылается на первоисточники. Условия использования каждого списка — на сайтах Spamhaus / FireHOL / blocklist.de; для коммерческих применений Spamhaus требует собственного соглашения.

80. Verified bots

Настоящий Googlebot не должен попадать под UA-фильтры и прочие антибот-механизмы — а спуфер, притворяющийся Googlebot, — должен. Verified bots решают обе задачи двухфакторной проверкой UA-claim × IP:

1. Издательские диапазоны (map-файл verified_ranges.map): HA-WAF раз в сутки качает официальные JSON-списки префиксов (Google Googlebot/special-crawlers/user-triggered-fetchers, Bing, OpenAI GPTBot/OAI-SearchBot/ChatGPT-User, Applebot, Anthropic, PerplexityBot). Недоступный источник сохраняет префиксы прошлого успешного обновления (fail-open).
2. FCrDNS (stick-table): для издателей без публикуемых диапазонов (Яндекс, Amazon, Meta) — forward-confirmed reverse DNS: PTR-имя под суффиксом издателя (с ведущей точкой — evilgooglebot.com не проходит проверку .googlebot.com), и forward-lookup обязан вернуть исходный IP. Проверки идут вне горячего пути: HAProxy регистрирует UA-кандидатов в таблице, воркер HA-WAF верифицирует их через runtime-CLI каждые 10 с.

Клиент с IP из диапазонов издателя или positive-вердиктом FCrDNS получает txn.verified_bot — и снимаются только блокировки (deny/tarpit/decoy) Bot Policy.

Семантика fail-open: «невозможно проверить ≠ спуфер». Механизм только снимает блокировки, никогда не добавляет их — боты без опубликованных диапазонов и FCrDNS не режутся этим механизмом.

Конфигурация (yaml, дефолты):

bots:
  enabled: true            # включено по умолчанию; false → конфиг байт-в-байт без фичи
  map_file: /etc/ha-waf/verified_ranges.map
  sync_interval: 24h
  verify_interval: 10s
  dns_timeout: 2s
  workers: 4
haproxy:
  verified_table_port: 19996

Порт 19996 слушает FCrDNS stick-table на 127.0.0.1. Если порт занят на хосте, HAProxy не стартует — переопределите haproxy.verified_table_port. При включённой фиче HAProxy также поднимает tune.stick-counters до 4 (sc0–sc3).

Ограничение: stick-table verified-ботов имеет тип ip — FCrDNS-фактор работает только для IPv4 (map-фактор покрывает и IPv6-префиксы издателей).

81. Challenge (redirect → PoW)

Двухступенчатый челлендж для подозрительных клиентов (подход Anubis): вместо блокировки — доказательство работы.

• Ступень 1 — redirect-челлендж без JS: клиент получает 302 на /_waf/challenge, API ставит подписанную pending-cookie (HMAC) и возвращает на исходный URL.
• Ступень 2 — proof-of-work-интерстишл (SHA-256, ведущие нулевые нибблы), который рендерит сам HAProxy. Решение → passed-cookie на TTL политики; cookie подписана HMAC и привязана к IP-префиксу (/24 v4, /56 v6) + классу UA.

Вкладка в UI: Site → Челлендж

PUT /api/v1/sites/{siteId}/challenge
{
  "enabled": true,
  "mode": "shadow",
  "paths": ["/login", "/api/"],
  "cookie_ttl_hours": 168,
  "rechallenge_pct": 2,
  "pow_difficulty": 5,
  "require_pow": true
}

Автоматически не челленджатся (exemption-цепочка по приоритету): верифицированные боты (гл. 80), robots.txt и /.well-known/*, фиды *.xml/*.atom, не-Mozilla UA (curl/git/RSS — JS не исполнят), WAF-whitelist. Cookie __Host-hw_chal (Secure, HttpOnly, SameSite=Lax) требует HTTPS.

Enforce требует HTTPS на сайте. Редирект челленджа ведёт на абсолютный https://-адрес — на HTTP-only сайте это мёртвый эндпоинт, который запирает Mozilla-UA клиентов. API отвергает mode: enforce для сайта без https_enabled (#172). Включите HTTPS или используйте shadow.

Enforce только на HTTPS-сайтах ≠ «только на HTTPS-порту»: custom HTTP-порт с waf_enabled=false не рендерит enforcement, даже если у сайта WAF включён (вердиктов на таком порту не будет).

Челлендж ездит на SPOE-конвейере: сайт с выключенным WAF-политикой челлендж не получает. При деградации SPOA (агент недоступен или перегружен) enforce-политики автоматически даунгрейдятся в shadow (метрика challenge_degraded, гл. 83) — redirect-лупы на живом сайте не будет.

Секрет cookie — yaml challenge.secret (или env HAWAF_CHALLENGE_SECRET); пусто → случайный секрет при старте + предупреждение (cookie протекут на рестарте), для multi-replica задавайте явно. Смена любой настройки политики инвалидирует все cookie сайта (policy-hash в подписи).

SEO: оставляйте paths пустыми только осознанно — массовый 302 бьёт по краулингу; челленджьте избранные префиксы (/search, /login, /api). robots.txt и фиды уже в exemption-цепочке — не дублируйте.

82. Honeypot

Скрытые поля-ловушки в формах: поле, которое человек не видит и не заполняет, а бот заполняет. Детект — до CRS в Coraza (через SPOE), реакция — тихая; бан — только повторными срабатываниями через общий WAF gpc0-счётчик. Первый этап выката — shadow (только счётчики).

Вкладка в UI: Site → Ловушки

Workflow владельца сайта:

1. Включите политику (сначала shadow!):

   PUT /api/v1/sites/{siteId}/honeypot
   {"enabled": true, "mode": "shadow", "action": "silent200"}
   

2. Создайте поле — POST /api/v1/sites/{siteId}/honeypot/fields. Имя генерирует бэкенд: hp_ + 12 hex (криптослучайное).
3. Встройте сниппет в форму (кнопка «Показать сниппет» на вкладке):

   <input type="hidden" name="hp_0123456789ab" value="">
   <input type="hidden" name="hp_0123456789ab_token" value="1737050000.9f2c…">
   <style>
     input[name="hp_0123456789ab"] { position:absolute; left:-9999px; top:-9999px; }
   </style>
   

   Первый инпут — ловушка (у человека всегда пустой), второй — embed-токен бэкенда. Прячьте поле off-screen позиционированием (не display:none — часть ботов такие поля пропускает), с tabindex="-1" и aria-hidden="true".
4. Примените конфигурацию (POST /api/v1/reload).
5. Наблюдайте: счётчики на вкладке (GET /api/v1/honeypot/status) и метрика honeypot_hits_total. Накопили статистику — переключите mode в enforce.

Сигналы:

Реакция (enforce): silent200 — нейтральный 200 OK («бот видит успех», ловушка не раскрывается) или tarpit (гл. 78). Никогда — 4xx и никогда прямой бан с первого срабатывания: каждое hit инкрементит общий gpc0 WAF-бан-счётчик, 429 наступает только при повторах.

Защита от форжа третьей стороной: токен публичен (он вшит в HTML), поэтому защита — не в секретности, а в Origin-гейте SPOA: браузер обязан ставить Origin на cross-origin POST и не может подделать его со страницы. Нет Origin / same-origin → обычный путь hit (клиент без браузера = бот); чужой/null Origin → сигнал forged, жертва не тарпитруется и не банится. Query-вектор исключён структурой правила (матчится только ARGS_POST + метод POST).

robots.txt не нужен. Ловушка — скрытое поле в реальной форме, а не отдельная страница-URL: честные краулеры формы не отправляют и в ловушку не попадают, менять robots.txt для honeypot не требуется. (Классические page-trap'ы — запрещённые в robots.txt ссылки-ловушки — в HA-WAF не реализованы.)

CSS-рефакторинг форм — главный враг ловушки. Если рефакторинг сделает поле видимым (сломалось off-screen-позиционирование, переименование поля), люди начнут его заполнять. Симптом: счётчик срабатываний внезапно растёт после релиза фронтенда при неизменном трафике ботов. Не называйте поле «человеческими» именами — автозаполнение браузеров заполнит его (имя hp_+hex выбрано специально).

Счётчики /honeypot/status — in-memory, сбрасываются на рестарте (история — в метрике honeypot_hits_total). Токены не истекают; смена challenge.secret инвалидирует их (старые станут notoken — слабым сигналом, не блоком).

83. Мониторинг и эксплуатация anti-bot

Метрики anti-bot стека (Prometheus-эндпоинт control-plane / OTel):

JA4 (#159, наблюдательная фаза). На терминируемых HTTPS-фронтендах считается TLS-фингерпринт JA4: поле ja4 в access-логе и заголовок X-TLS-JA4 бэкенду; метрики с per-fingerprint label нет (кардинальность), TCP-passthrough и :80 фингерпринта не имеют. Только наблюдение — блокировки по JA4 (комбо-правила) в будущей фазе #188, детали в docs/anti-bot/ja4.md.

Деградация SPOA и auto-downgrade. Enforce-challenge зависит от SPOE-вердиктов. Сценарий «HAProxy жив, вердиктов нет» (перегрузка агента, рестарт control-plane) даёт бесконечный redirect-луп. Монитор control-plane каждые 5 с проверяет TCP-доступность SPOA (тот же адрес, что у health-check'а HAProxy) и долю провалов обработки SPOE-сообщений: окно 30 с, >50 % провалов при ≥20 обработанных сообщениях → проба считается неуспешной (низкий трафик перегрузкой не считается). Гистерезис 3 неудачи/3 успеха (15 с) → challenge_degraded=1, все enforce-политики рендерятся как shadow; восстановление автоматом, в БД ничего не меняется.

Что алертить:

• challenge_degraded == 1 дольше 5 минут — SPOA перегружен/недоступен;
• рост rate(spoa_processing_failures_total) при живом порте агента — перегрузка с живым TCP (второй сигнал монитора);
• скачок honeypot_hits_total{signal=hit} после релиза фронтенда — CSS-регрессия скрытия поля (гл. 82);
• устойчивый challenge_verdicts_total{verdict=challenge} у одного сайта — redirect-луп (у клиента выключены cookies) или слишком широкие paths;
• iprep stale: true / held: true — фид не обновляется дольше суток.

Типовые проблемы:

Приложение A: REST API

Полный справочник со всеми эндпоинтами, полями тел запросов/ответов и примерами — docs/api.md. Здесь дублировать его не имеет смысла: этот список так же выходил из синхронизации с кодом, как и остальная документация — держать одну точку правды проще, чем две.

Аутентификация — три взаимозаменяемых способа: Authorization: Bearer <JWT>, cookie auth_token (+ X-CSRF-Token для небезопасных методов), X-API-Key: hwaf_<key>. Подробности — в docs/api.md → Аутентификация.

Приложение B: Справочник по config.yaml

# ──────────────────────────────────────────────
# REST API server
# ──────────────────────────────────────────────
server:
  addr: ":8080"                          # API + Web UI bind address

# ──────────────────────────────────────────────
# Database
# ──────────────────────────────────────────────
database:
  driver: sqlite                         # sqlite | postgres
  dsn: /var/lib/ha-waf/ha-waf.db        # path (sqlite) or connstring (postgres)
  dsn_read: ""                           # read-only replica (postgres only)

# ──────────────────────────────────────────────
# HAProxy
# ──────────────────────────────────────────────
haproxy:
  binary:      /usr/local/sbin/haproxy
  config_dir:  /etc/ha-waf/haproxy
  config_file: /etc/ha-waf/haproxy/haproxy.cfg
  pid_file:    /var/run/ha-waf/haproxy.pid
  socket_path: /var/run/ha-waf/haproxy-admin.sock

  # Performance
  maxconn:   50000
  ulimit_n:  200000

  # TLS
  ssl_options: "no-sslv3 no-tlsv10 no-tlsv11"
  ssl_cert_dir: /etc/ha-waf/certs/

  # Ports
  http_port:  80
  https_port: 443

  # Paths
  error_dir:      /etc/ha-waf/errors
  geoip_map_file: /etc/ha-waf/geoip.txt

  # Prometheus endpoint (HAProxy native)
  metrics_bind: ":8405"
  metrics_acls:
    - "127.0.0.1"

  # Internal rate-limit stick-table
  internal_rate_table_port: 19999

# ──────────────────────────────────────────────
# Coraza WAF SPOE
# ──────────────────────────────────────────────
spoa:
  addr: "127.0.0.1:9000"

# ──────────────────────────────────────────────
# Authentication
# ──────────────────────────────────────────────
auth:
  jwt_secret: ""          # empty = random on startup (set explicitly in production)
  token_ttl: "24h"        # Go duration: 1h, 24h, 168h

# ──────────────────────────────────────────────
# Telemetry
# ──────────────────────────────────────────────
telemetry:
  prometheus_addr: ":9091"   # empty = disabled

  # otlp:
  #   endpoint: "otel-collector:4317"
  #   insecure: true
  #   logs:    { enabled: true }
  #   metrics: { enabled: true }
  #   traces:  { enabled: true }

# ──────────────────────────────────────────────
# k8sban — сетевой бан через Cilium (k8s only, см. Часть XIV)
# ──────────────────────────────────────────────
k8s_network_ban:
  enabled: false          # false на self-hosted (Docker Compose) — секция игнорируется
  policy_name: ha-waf-ip-ban
  poll_interval: "10s"
  ports: ["80", "443"]

# ──────────────────────────────────────────────
# Верхнеуровневые поля
# ──────────────────────────────────────────────
license_key: ""            # см. Часть XIII; можно задать через переменную окружения HAWAF_LICENSE_KEY
log_level: info             # debug | info | warn | error

Приложение C: Переменные окружения

HA-WAF читает основной конфиг только из файла (-config флаг) — переменные окружения не подставляются в config.yaml шаблонизатором. Единственное исключение:

Флаг запуска:

ha-waf -config /etc/ha-waf/config.yaml

Проверка версии:

ha-waf -version

Health endpoints:

GET /healthz   → 200 сразу после запуска (liveness)
GET /readyz    → 200 после полной инициализации (readiness)

Часть XXI: Известные проблемы безопасности

84. Текущие security issues

85. Roadmap исправлений

P0 (Completed):

1. ✅ Fix IDOR в DeleteAPIKey — добавлен user_id в WHERE clause (9587f25)
2. ✅ Добавлен Secure flag к OIDC cookies (09c668d)
3. ✅ Убраны DNS credentials из env vars — Config structs (806dc59)
4. ✅ Fix error comparison — err == → errors.Is() (1c4030d, 37341e0)
5. ✅ Fix hash collision — FNV-1a в urlExclusionID (df5167b)
6. ✅ Dockerfile — запуск от non-root (4799a17)
7. ✅ CI DinD TLS (41d6ffd)
8. ✅ JWT → httpOnly cookies (bcde570)
9. ✅ Rate limiting на /login (a55d620)
10. ✅ Open Redirect validation (d519d4e)
11. ✅ Request body limits (d12a8b4)
12. ✅ CookieSecure default true + rate limiter IP spoof fix (a0f8c0e)

P1 (Short-term — остались): 6. Rate limiting distributed (Redis) — enhancement 7. Security headers middleware 8. CSP headers

P2 (Medium-term): 9. Code-splitting frontend 10. Refactor god objects