Синтаксис правил YAML

На этой странице документируется полная схема правил YAML, используемая в PRX-WAF. Каждый файл правил следует этой структуре.

Структура файла

Каждый YAML-файл правил имеет раздел метаданных верхнего уровня, за которым следует список правил:

version: "1.0"                     # Версия схемы (обязательно)
description: "Short description"   # Читаемая пользователем метка (обязательно)
source: "OWASP CRS v4.25.0"       # Происхождение правил (необязательно)
license: "Apache-2.0"             # Идентификатор лицензии SPDX (необязательно)

rules:
  - <rule>
  - <rule>

Схема правила

Каждое правило в списке rules имеет следующие поля:

- id: "CRS-942100"              # Уникальный строковый ID (ОБЯЗАТЕЛЬНО)
  name: "SQL injection attack"  # Краткое описание (ОБЯЗАТЕЛЬНО)
  category: "sqli"              # Тег категории (ОБЯЗАТЕЛЬНО)
  severity: "critical"          # Уровень серьёзности (ОБЯЗАТЕЛЬНО)
  paranoia: 1                   # Уровень паранойи 1-4 (необязательно, по умолчанию: 1)
  field: "all"                  # Поле запроса для проверки (ОБЯЗАТЕЛЬНО)
  operator: "regex"             # Оператор сопоставления (ОБЯЗАТЕЛЬНО)
  value: "(?i)select.+from"     # Паттерн или порог (ОБЯЗАТЕЛЬНО)
  action: "block"               # Действие при совпадении (ОБЯЗАТЕЛЬНО)
  tags:                         # Строковые теги (необязательно)
    - "owasp-crs"
    - "sqli"
  crs_id: 942100                # Оригинальный числовой ID CRS (необязательно)
  reference: "https://..."      # Ссылка на CVE или документацию (необязательно)

Обязательные поля

Поле	Тип	Описание
id	string	Уникальный идентификатор среди всех файлов правил. Формат: <PREFIX>-<CATEGORY>-<NNN>
name	string	Краткое читаемое пользователем описание (макс. ~120 символов)
category	string	Тег категории для фильтрации и отчётности
severity	string	Одно из: critical, high, medium, low, info, notice, warning, error, unknown
field	string	Какую часть запроса проверять (см. Справочник полей)
operator	string	Как сопоставлять значение (см. Справочник операторов)
value	string	Паттерн, порог или имя файла словаря
action	string	Что делать при совпадении правила (см. Справочник действий)

Необязательные поля

Поле	Тип	По умолчанию	Описание
paranoia	integer	1	Уровень паранойи 1-4
tags	string[]	[]	Теги для фильтрации и отображения в дашборде
crs_id	integer	—	Оригинальный числовой ID OWASP CRS
reference	string	—	URL на CVE, статью OWASP или обоснование

Справочник полей

Значение field определяет, какая часть HTTP-запроса проверяется:

Поле	Проверяет
path	Путь URI запроса (без строки запроса)
query	Строка запроса (все параметры, декодированные)
body	Тело запроса (декодированное)
headers	Все заголовки запроса (пары имя: значение)
user_agent	Только заголовок User-Agent
cookies	Куки запроса
method	HTTP-метод (GET, POST, PUT и т.д.)
content_type	Заголовок Content-Type
content_length	Значение Content-Length (для числового сравнения)
path_length	Длина пути URI (для числового сравнения)
query_arg_count	Количество параметров запроса (для числового сравнения)
all	Все перечисленные выше поля вместе

Справочник операторов

Значение operator определяет, как value сопоставляется с проверяемым полем:

Оператор	Описание	Формат значения
regex	PCRE-совместимое регулярное выражение	Паттерн regex
contains	Поле содержит буквальную строку	Буквальная строка
equals	Поле точно равно значению (с учётом регистра)	Буквальная строка
not_in	Значение поля НЕ в списке	Список, разделённый запятыми
gt	Значение поля (числовое) больше	Числовая строка
lt	Значение поля (числовое) меньше	Числовая строка
ge	Значение поля (числовое) больше или равно	Числовая строка
le	Значение поля (числовое) меньше или равно	Числовая строка
detect_sqli	Обнаружение SQL-инъекций через libinjection	"true" или ""
detect_xss	Обнаружение XSS через libinjection	"true" или ""
pm_from_file	Phrase-match против файла словаря	Имя файла в owasp-crs/data/
pm	Phrase-match против встроенного списка	Фразы, разделённые запятыми

Справочник действий

Значение action определяет, что происходит при совпадении правила:

Действие	Описание
block	Отклонить запрос с ответом 403 Forbidden
log	Разрешить запрос, но зарегистрировать совпадение (режим мониторинга)
allow	Явно разрешить запрос (переопределяет другие правила)
deny	Псевдоним для block
redirect	Перенаправить запрос (конфигурация движка)
drop	Тихо разорвать соединение

TIP

Начинайте новые правила с action: log, чтобы отслеживать ложные срабатывания перед переключением на action: block.

Соглашение о пространстве имён ID

ID правил должны следовать установленному соглашению о префиксах:

Каталог	Префикс ID	Пример
owasp-crs/	CRS-<number>	CRS-942100
modsecurity/	MODSEC-<CATEGORY>-<NNN>	MODSEC-IP-001
cve-patches/	CVE-<YEAR>-<SHORT>-<NNN>	CVE-2021-LOG4J-001
custom/	CUSTOM-<CATEGORY>-<NNN>	CUSTOM-API-001

Полный пример

version: "1.0"
description: "Application-specific access control rules"
source: "custom"
license: "Apache-2.0"

rules:
  - id: "CUSTOM-API-001"
    name: "Block access to internal admin API"
    category: "access-control"
    severity: "high"
    paranoia: 1
    field: "path"
    operator: "regex"
    value: "(?i)^/internal/"
    action: "block"
    tags: ["custom", "access-control"]

  - id: "CUSTOM-BOT-001"
    name: "Log suspicious automated tool user-agents"
    category: "scanner"
    severity: "medium"
    paranoia: 2
    field: "user_agent"
    operator: "regex"
    value: "(?i)(masscan|zgrab|python-requests/|go-http-client)"
    action: "log"
    tags: ["custom", "bot", "scanner"]

  - id: "CUSTOM-RATE-001"
    name: "Block requests with excessive query parameters"
    category: "dos"
    severity: "medium"
    paranoia: 1
    field: "query_arg_count"
    operator: "gt"
    value: "50"
    action: "block"
    tags: ["custom", "dos"]

Валидация правил

Проверяйте файлы правил перед развёртыванием:

# Проверить все правила
python rules/tools/validate.py rules/

# Проверить конкретный файл
python rules/tools/validate.py rules/custom/myapp.yaml

Валидатор проверяет:

• Обязательные поля присутствуют
• Нет дублирующихся ID правил в всех файлах
• Значения severity и action допустимы
• Уровни паранойи в диапазоне 1-4
• Regex компилируются корректно
• Числовые операторы не используются со строковыми значениями

Следующие шаги

• Встроенные правила — изучите правила OWASP CRS и CVE-патчи
• Пользовательские правила — создавайте собственные правила шаг за шагом
• Обзор движка правил — как конвейер обнаружения обрабатывает правила