Enhance add_header_redefinition plugin to support case-insensitive header allowlist; update documentation with new CLI options #34

Author: dvershinin

README.md

@@ -114,6 +114,28 @@ Total issues:
 
 Or something else, you can find all other `gixy` arguments with the help command: `gixy --help`
 
+### Plugin options
+
+Some plugins expose options which you can set via CLI flags or config file. CLI flags follow the pattern `--<PluginName>-<option>` with dashes, while config file uses `[PluginName]` sections with dashed keys.
+
+- `origins`:
+  - `--origins-domains domains`: Comma-separated list of trusted registrable domains. Use `*` to disable third‑party checks. Example: `--origins-domains example.com,foo.bar`. Default: `*`.
+  - `--origins-https-only true|false`: When true, only the `https` scheme is considered valid for `Origin`/`Referer`. Default: `false`.
+  - `--origins-lower-hostname true|false`: Normalize hostnames to lowercase before validation. Default: `true`.
+
+- `add_header_redefinition`:
+  - `--add-header-redefinition-headers headers`: Comma-separated allowlist of header names (case-insensitive). When set, only dropped headers from this list will be reported; when unset, all dropped headers are reported. Example: `--add-header-redefinition-headers x-frame-options,content-security-policy`. Default: unset (report all).
+
+Examples (config file):
+```
+[origins]
+domains = example.com, example.org
+https-only = true
+
+[add_header_redefinition]
+headers = x-frame-options, content-security-policy
+```
+
 You can also make `gixy` use pipes (stdin), like so:
 
 ```bash

docs/en/plugins/addheaderredefinition.md

@@ -63,3 +63,13 @@ There are several ways to solve this problem:
  - use [ngx_headers_more](https://nginx-extras.getpagespeed.com/modules/headers-more/) module.
 
 --8<-- "en/snippets/nginx-extras-cta.md"
+
+### CLI and config options
+
+- `--add-header-redefinition-headers headers` (Default: unset): Comma-separated, case-insensitive allowlist of headers to report when dropped. When unset, all dropped parent headers are reported. Example: `--add-header-redefinition-headers x-frame-options,content-security-policy`.
+
+Config file example:
+```
+[add_header_redefinition]
+headers = x-frame-options, content-security-policy
+```

docs/en/plugins/origins.md

@@ -10,6 +10,19 @@ The most common errors with this configuration are:
 > Notice: by default, Gixy doesn't check regexes for third-party origins matching.
 > You can pass a list of trusted domains by using the option `--origins-domains example.com,foo.bar`. When enabled, Gixy recognizes origins by registrable domain (via Public Suffix List) and will flag regexes that allow off-domain values.
 
+### CLI and config options
+
+- `--origins-domains domains` (Default: `*`): Comma-separated list of trusted registrable domains. Use `*` to disable third‑party checks. Example: `--origins-domains example.com,foo.bar`.
+- `--origins-https-only true|false` (Default: `false`): When true, only the `https` scheme is considered valid for `Origin`/`Referer`.
+- `--origins-lower-hostname true|false` (Default: `true`): Normalize hostnames to lowercase before validation.
+
+Config file example:
+```
+[origins]
+domains = example.com, example.org
+https-only = true
+```
+
 ## How can I find it?
 "Eazy"-breezy:
   - you have to find all the `if` directives that are in charge of `$http_origin` or `$http_referer` check;

docs/ru/plugins/addheaderredefinition.md

@@ -63,3 +63,13 @@ new-headers
   - использовать модуль [ngx_headers_more](https://nginx-extras.getpagespeed.com/modules/headers-more/).
 
 Каждый из способов имеет свои преимущества и недостатки, какой предпочесть зависит от ваших потребностей. 
+
+### Опции CLI и конфигурации
+
+- `--add-header-redefinition-headers headers` (По умолчанию: не задано): Список заголовков (без учета регистра) через запятую, по которым будет вестись отчет при их «сбросе». Если опция не задана, будет отчет по всем сброшенным заголовкам. Пример: `--add-header-redefinition-headers x-frame-options,content-security-policy`.
+
+Пример в конфиге:
+```
+[add_header_redefinition]
+headers = x-frame-options, content-security-policy
+```

docs/ru/plugins/origins.md

@@ -8,7 +8,20 @@
   - разрешение не доверенных third-party доменов.
 
 > По умолчанию Gixy не проверяет регулярные выражения на предмет матчинга third-party доменов, так как не знает кому можно верить.
-Передать список доверенных доменом можно при помощи опции `--origins-domains example.com,foo.bar`
+Список доверенных доменов можно передать с помощью опции `--origins-domains example.com,foo.bar`. При включении проверка выполняется на уровне регистрируемого домена (по Public Suffix List).
+
+### Опции CLI и конфигурации
+
+- `--origins-domains domains` (По умолчанию: `*`): Список доверенных доменов через запятую. `*` — отключить проверку third‑party доменов. Пример: `--origins-domains example.com,foo.bar`.
+- `--origins-https-only true|false` (По умолчанию: `false`): Если `true`, валиден только протокол `https` в `Origin`/`Referer`.
+- `--origins-lower-hostname true|false` (По умолчанию: `true`): Приводить имена хостов к нижнему регистру перед проверкой.
+
+Пример в конфиге:
+```
+[origins]
+domains = example.com, example.org
+https-only = true
+```
 
 ## Как самостоятельно обнаружить?
 Все довольно "просто":

docs/zh/plugins/addheaderredefinition.md

@@ -63,3 +63,13 @@ new-headers
 - 使用 [ngx_headers_more](https://nginx-extras.getpagespeed.com/modules/headers-more/) 模块。
 
 --8<-- "zh/snippets/nginx-extras-cta.md"
+
+### 命令行与配置选项
+
+- `--add-header-redefinition-headers headers`（默认：未设置）：以逗号分隔的响应头白名单（不区分大小写）。设置后，仅当这些头在子级被“丢弃”时才会报告；未设置则报告所有被丢弃的头。示例：`--add-header-redefinition-headers x-frame-options,content-security-policy`。
+
+配置示例：
+```
+[add_header_redefinition]
+headers = x-frame-options, content-security-policy
+```

docs/zh/plugins/origins.md

@@ -10,6 +10,19 @@
 > 注意：默认情况下，Gixy 不会检查正则是否允许第三方来源。
 > 你可以通过 `--origins-domains example.com,foo.bar` 传入可信域名列表。启用后，Gixy 会基于 Public Suffix List 以“可注册域”为单位识别来源，并标记那些放行域外值的正则。
 
+### 命令行与配置选项
+
+- `--origins-domains domains`（默认：`*`）：以逗号分隔的可信可注册域名列表。使用 `*` 关闭第三方检查。示例：`--origins-domains example.com,foo.bar`。
+- `--origins-https-only true|false`（默认：`false`）：为 `true` 时，仅允许 `https` 协议的 `Origin`/`Referer`。
+- `--origins-lower-hostname true|false`（默认：`true`）：校验前将主机名转换为小写。
+
+配置示例：
+```
+[origins]
+domains = example.com, example.org
+https-only = true
+```
+
 ## 如何发现？
 "简单粗暴" 的办法：
 - 找到所有对 `$http_origin` 或 `$http_referer` 进行校验的 `if` 指令；

gixy/cli/main.py

@@ -27,13 +27,31 @@ def _init_logger(debug=False):
     LOG.debug("logging initialized")
 
 
-def _create_plugin_help(option):
+def _create_plugin_help(plugin_cls, opt_key, option):
+    """Build help text for a plugin option, including usage hints and default.
+
+    Attempts to use plugin-provided descriptions via optional
+    `options_help` mapping on the plugin class.
+    """
     if isinstance(option, (tuple, list, set)):
         default = ",".join(list(option))
+        usage_hint = "Comma-separated list."
     else:
         default = str(option)
+        usage_hint = None
+
+    if isinstance(option, bool):
+        usage_hint = "Boolean (true/false)."
+
+    # Plugin-specific description if provided
+    base_desc = ""
+    if hasattr(plugin_cls, "options_help"):
+        options_help = plugin_cls.options_help
+        if isinstance(options_help, dict):
+            base_desc = options_help.get(opt_key, "")
 
-    return "Default: {0}".format(default)
+    parts = [p for p in [base_desc, usage_hint, "Default: {0}".format(default)] if p]
+    return " ".join(parts)
 
 
 def _get_cli_parser():
@@ -126,7 +144,7 @@ def _get_cli_parser():
                 metavar=opt_key,
                 dest=dst_name,
                 type=opt_type,
-                help=_create_plugin_help(opt_val),
+                help=_create_plugin_help(plugin_cls, opt_key, opt_val),
             )
 
     return parser

gixy/plugins/add_header_redefinition.py

@@ -18,11 +18,22 @@ class add_header_redefinition(Plugin):
                    'See documentation: https://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header')
     help_url = 'https://github.com/dvershinin/gixy/blob/master/docs/en/plugins/addheaderredefinition.md'
     directives = ['server', 'location', 'if']
+    # headers: optional set/list/tuple of header names to scope reporting to
+    # When empty, all dropped headers are reported. Case-insensitive; values are
+    # normalized to lowercase and compared to lowercase header names from config.
     options = {'headers': set()}
+    options_help = {
+        'headers': 'Only report dropped headers from this allowlist. Case-insensitive. Comma-separated list, e.g. "x-frame-options,content-security-policy".'
+    }
 
     def __init__(self, config):
         super(add_header_redefinition, self).__init__(config)
-        self.interesting_headers = self.config.get('headers')
+        raw_headers = self.config.get('headers')
+        # Normalize configured headers to lowercase set for case-insensitive matching
+        if isinstance(raw_headers, (list, tuple, set)):
+            self.interesting_headers = set(h.lower().strip() for h in raw_headers if h and isinstance(h, str))
+        else:
+            self.interesting_headers = set()
         # Define secure headers that should escalate severity
         self.secure_headers = [
             'x-frame-options',
@@ -48,7 +59,7 @@ def audit(self, directive):
 
             diff = parent_headers - actual_headers
 
-            if len(self.interesting_headers):
+            if self.interesting_headers:
                 diff = diff & self.interesting_headers
 
             if len(diff):

gixy/plugins/origins.py

@@ -53,6 +53,11 @@ class origins(Plugin):
         'https_only': False,
         'lower_hostname': True
     }
+    options_help = {
+        'domains': 'Comma-separated list of trusted registrable domains. Use * to disable third-party checks. Example: "example.com,foo.bar".',
+        'https_only': 'Boolean. Only allow https scheme in origins/referers when true.',
+        'lower_hostname': 'Boolean. Normalize hostnames to lowercase prior to validation.'
+    }
 
     def __init__(self, config):
         super(origins, self).__init__(config)