Переменные и Drop-in¶

Gixy распознаёт поддерживаемые переменные NGINX и использует описания их возможных значений при проверке безопасности. Переменная может содержать числа, фиксированные строки состояния кеша или произвольный текст. От этого зависит, какие проблемы Gixy сможет обнаружить.

Например, сторонняя переменная $brotli_ratio может содержать цифры и точки либо отсутствовать. Ограничение [0-9.]* исключает CR/LF и /, но сохраняет точки для консервативной проверки SSRF. Это следует из функции, возвращающей значение ngx_brotli v0.1.4. Поддержка имени не подтверждает установку или загрузку модуля и не гарантирует безопасность его вывода. Общего безопасного префикса brotli_ нет; неизвестные переменные по-прежнему вызывают диагностические сообщения.

Переменные модулей и объявления¶

Gixy 0.2.59: Объявления переменных модулей и встроенные описания в этом разделе доступны в 0.2.59. Многоуровневый каталог ниже доступен уже в 0.2.58.

Встроенные описания переменных охватывают коэффициенты сжатия, srcache, Echo, счётчики VTS, точные имена GeoIP/SSL и документированные JWT claims/headers. Описания задают возможные символы, но не подтверждают наличие модуля. Значения из базы, сертификатов, JWT и скриптов могут содержать любые символы, включая переносы строк, поэтому Gixy продолжает проверять их безопасность. Неизвестные имена $ssl_typo, $geoip_typo, $jwt_type не считаются безопасными. Матрица покрытия и исходники.

GeoIP2 регистрирует произвольные псевдонимы только непосредственно в http или stream. default=US и путь country iso_code не делают значение безопасным: база может вернуть произвольные байты. Значения по умолчанию буквальные, без подстановки переменных. Только точные формы metadata build_epoch, metadata last_check, metadata last_change ограничены десятичными символами. Gixy не открывает базы и не исполняет выражения source=.

Локальные имена нечувствительны к регистру. Последнее объявление GeoIP2 после раскрытия внешних include действует во всём главном контексте, включая ранние использования. Внутренний include в GeoIP2 недопустим и пропускается до чтения файлов или раскрытия дампа. Контексты HTTP/stream и отдельные аудиты изолированы; объявления конфигурации имеют приоритет над каталогом при отключённой загрузке системной политики. При совпадении имени с переменной map/geo/njs/Perl Gixy допускает любые символы в её значении и сообщает все места объявления. Локальный set сохраняет приоритет.

Результаты set_by_lua, set_by_lua_file, set_by_lua_block, perl_set, js_set, js_var могут содержать любые символы, включая переносы строк. Скрипты не исполняются, файлы не читаются; начальное значение изменяемого js_var не является постоянным ограничением. Динамический хост из конфигурации требует resolver, кроме доказанного буквального IP или upstream; регулярное выражение не считается именем хоста.

Слои и приоритет¶

Обычный CLI, включая запуск без аргументов и stdin, использует слои по возрастанию приоритета:

Встроенные описания переменных.
Файлы поставщиков в /usr/share/gixy/vars.d.
Файлы администратора в /etc/gixy/vars.d.
Явные каталоги --vars-dirs в указанном порядке (последний выше).

Каждый каталог представляет отдельный слой. Файлы .cfg и .conf читаются по имени; последнее корректное определение ключа побеждает, в том числе внутри одного файла. Ошибочная строка не удаляет предыдущее корректное определение: предупреждение содержит путь и номер строки.

Сначала выбирается самый высокий слой с подходящим определением, затем точное имя, затем самый длинный подходящий префикс с окончанием _. Поэтому http_ верхнего слоя перекрывает http_host нижнего. В одном слое точное имя выше префикса, а http_special_ выше http_ для $http_special_value. Это исправляет прежнюю зависимость выбора префикса от порядка вставки. Переменные, заданные в анализируемой конфигурации NGINX, сохраняют приоритет над каталогом описаний переменных.

Управление и изоляция¶

gixy --vars-dirs /etc/gixy/vars,~/.config/gixy/vars

# Скалярное значение, без квадратных скобок
vars-dirs = /etc/gixy/vars, ~/.config/gixy/vars
load-default-vars = false

--no-default-vars отключает системные каталоги, сохраняя встроенные описания переменных и явно выбранные каталоги. --load-default-vars включает системные каталоги. Противоположные флаги вместе запрещены. Канонический ключ: load-default-vars; переменная окружения: GIXY_LOAD_DEFAULT_VARS=true или false. Приоритет: CLI > окружение > конфигурация > значение режима. Явное false сохраняется, включая --write-config. Явные каталоги всегда выше включённых системных слоёв. Старые /etc/gixy/vars и ~/.config/gixy/vars работают при явном выборе.

Библиотека Config(load_default_vars=False) и --server по умолчанию используют только встроенные описания переменных. Оператор может включить системную политику или задать vars_dirs при запуске. Отдельные запросы сервера и загруженный текст NGINX не могут изменить политику или выбрать пути. Для каждой проверки создаётся новый каталог, общий для её дочерних контекстов: пользовательские описания переменных одной проверки не влияют на другую. Это не обещание общей потокобезопасности анализатора.

Формат и доверие¶

Строка: name value, name = value или name: value. Имя состоит из ASCII-букв, цифр и _, начинается с буквы или _, не содержит $; окончание _ задаёт префикс. Числовые regex-группы не входят в каталог.

foo_host "example.com"
foo_literal 'a.b[$http_host]'
foo_uri r'/[^\s]*',
legacy_uri /[^\s]*
operator_asserted_safe none

Обычные кавычки задают литерал без подстановки переменных, Python-декодирования или выполнения. r'...' и r"..." задают regex; старые regex без кавычек также поддерживаются. Синтаксис regex проверяется статически, без поиска по строкам. Допустима завершающая запятая. none, null (без учёта регистра), '' и "" явно утверждают отсутствие пользовательского управления. Это доверенная политика, способная подавлять находки: применяйте только с обоснованием. Пропущенное значение, незакрытые кавычки, неверное имя и некорректный regex отклоняются с предупреждением. Пустые строки и комментарии #/; игнорируются.

Автоматические файлы должны быть обычными файлами root, без записи для группы и остальных; те же требования действуют на каталог и всех предков. Символические ссылки, включая предков, отклоняются. Используются удерживаемые дескрипторы с no-follow; если платформа этого не поддерживает, системная политика пропускается с предупреждением. Отсутствующие необязательные каталоги допустимы; сканирование не создаёт каталогов.

Явные пути являются выбором доверенного оператора, поддерживают ~ и доступны не-root пользователям. Ошибки чтения и отсутствующие явные пути предупреждаются. Неявного поиска в текущем или домашнем каталоге нет. RPM модуля может поставлять обычный vendor-файл root:root/0644 без зависимости от Gixy. Общие vendor-каталоги имеют root:root/0755; локальные переопределения находятся в /etc/gixy/vars.d. После удаления файла модуля остаётся встроенное описание переменной. Политика меняет только анализ, а не поведение NGINX.