feat: static trustedIPs helper for entrypoint forwardedHeaders (#118)

Adds a guided Trusted IPs helper in the Static Config editor that writes
forwardedHeaders.trustedIPs onto an entrypoint, so Traefik trusts
X-Forwarded-For from proxies you control (Cloudflare, your own LAN/proxies).

- New POST /api/static/trusted-ips/preview parses the current static YAML,
  merges the selected sources additively (dedup by normalized network) and
  returns the exact new raw plus a preview (existing / added / invalid /
  final). It never writes to disk; the result is saved through the existing
  static-config save path, so it keeps the backup and restart flow and works
  on the Host and on remote agents alike.
- Cloudflare IPv4+IPv6 ranges are hardcoded with a capture date and refreshed
  on release (no runtime fetch). Private-range and free-form CIDR sources are
  also offered; invalid CIDRs are flagged and skipped.
- UI: a Trusted IPs button in the Static Config header (Host and agent), a
  preview modal with a global/restart warning that links to the Client IP
  Diagnostic, and a trustedIPs count badge on each entrypoint row.
- Entrypoint edits preserve forwardedHeaders, so the helper never clobbers a
  hand-authored value.
- Docs: a Trusted IPs helper section in docs/static.md including a note on
  how to refresh the hardcoded Cloudflare ranges.

Author: fbnlrz

app.py

@@ -2684,6 +2684,143 @@ def api_static_section_update():
         return jsonify({'error': str(e)}), 500
 
 
+# Cloudflare edge ranges for forwardedHeaders.trustedIPs, captured 2026-07-23 from
+# https://www.cloudflare.com/ips/ (https://www.cloudflare.com/ips-v4 + /ips-v6).
+# Refresh on release: replace both lists from that source and bump _CLOUDFLARE_IPS_CAPTURED.
+_CLOUDFLARE_IPS_CAPTURED = '2026-07-23'
+_CLOUDFLARE_IPS_V4 = [
+    '173.245.48.0/20', '103.21.244.0/22', '103.22.200.0/22', '103.31.4.0/22',
+    '141.101.64.0/18', '108.162.192.0/18', '190.93.240.0/20', '188.114.96.0/20',
+    '197.234.240.0/22', '198.41.128.0/17', '162.158.0.0/15', '104.16.0.0/13',
+    '104.24.0.0/14', '172.64.0.0/13', '131.0.72.0/22',
+]
+_CLOUDFLARE_IPS_V6 = [
+    '2400:cb00::/32', '2606:4700::/32', '2803:f800::/32', '2405:b500::/32',
+    '2405:8100::/32', '2a06:98c0::/29', '2c0f:f248::/32',
+]
+_PRIVATE_IP_RANGES = ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', 'fc00::/7']
+
+
+def _trusted_ip_key(cidr: str) -> str:
+    try:
+        return str(ipaddress.ip_network(str(cidr).strip(), strict=False))
+    except ValueError:
+        return str(cidr).strip().lower()
+
+
+def _is_valid_cidr(cidr: str) -> bool:
+    try:
+        ipaddress.ip_network(str(cidr).strip(), strict=False)
+        return True
+    except ValueError:
+        return False
+
+
+def _merge_trusted_ips(existing: list, additions: list) -> tuple:
+    seen = {_trusted_ip_key(x) for x in existing}
+    added = []
+    for cidr in additions:
+        key = _trusted_ip_key(cidr)
+        if key in seen:
+            continue
+        seen.add(key)
+        added.append(cidr)
+    return list(existing) + added, added
+
+
+def _parse_cidr_input(raw) -> list:
+    if isinstance(raw, list):
+        parts = [str(x) for x in raw]
+    else:
+        parts = re.split(r'[\s,]+', str(raw or ''))
+    return [p.strip() for p in parts if p.strip()]
+
+
+@app.route('/api/static/trusted-ips/preview', methods=['POST'])
+@csrf_protect
+@login_required
+def api_static_trusted_ips_preview():
+    req = request.get_json(silent=True) or {}
+    current_raw = req.get('current_raw', '')
+    entrypoint  = str(req.get('entrypoint', '')).strip()
+    try:
+        _y = YAML()
+        _y.preserve_quotes = True
+        if current_raw:
+            config = _y.load(StringIO(current_raw)) or {}
+        else:
+            path = _get_static_config_path()
+            if not path or not os.path.exists(path):
+                return jsonify({'error': 'Static config not found'}), 404
+            with open(path, 'r') as f:
+                config = _y.load(f) or {}
+        if not isinstance(config, dict):
+            return jsonify({'error': 'Static config is not a mapping'}), 400
+        ep_key = 'entryPoints' if 'entryPoints' in config else ('entrypoints' if 'entrypoints' in config else 'entryPoints')
+        eps = config.get(ep_key)
+        summary = []
+        if isinstance(eps, dict):
+            for nm, cfg in eps.items():
+                cur = []
+                addr = ''
+                if isinstance(cfg, dict):
+                    addr = str(cfg.get('address', ''))
+                    fh = cfg.get('forwardedHeaders')
+                    if isinstance(fh, dict) and isinstance(fh.get('trustedIPs'), list):
+                        cur = [str(x) for x in fh['trustedIPs']]
+                summary.append({'name': str(nm), 'address': addr, 'trusted_ips': cur})
+        resp = {
+            'ok': True,
+            'entrypoints': summary,
+            'cloudflare_captured': _CLOUDFLARE_IPS_CAPTURED,
+            'cloudflare_ranges': _CLOUDFLARE_IPS_V4 + _CLOUDFLARE_IPS_V6,
+            'private_ranges': _PRIVATE_IP_RANGES,
+        }
+        if not entrypoint:
+            return jsonify(resp)
+        if not isinstance(eps, dict) or entrypoint not in eps:
+            return jsonify({'error': f'Entrypoint "{entrypoint}" not found in static config'}), 400
+        custom  = _parse_cidr_input(req.get('custom_cidrs', []))
+        invalid = [c for c in custom if not _is_valid_cidr(c)]
+        additions = []
+        if req.get('cloudflare'):
+            additions += _CLOUDFLARE_IPS_V4 + _CLOUDFLARE_IPS_V6
+        if req.get('private'):
+            additions += _PRIVATE_IP_RANGES
+        additions += [c for c in custom if _is_valid_cidr(c)]
+        ep = eps.get(entrypoint)
+        if not isinstance(ep, dict):
+            ep = {}
+        fh = ep.get('forwardedHeaders') if isinstance(ep.get('forwardedHeaders'), dict) else {}
+        cur_seq = fh.get('trustedIPs')
+        existing = [str(x) for x in cur_seq] if isinstance(cur_seq, list) else []
+        final, added = _merge_trusted_ips(existing, additions)
+        if isinstance(cur_seq, list):
+            for c in added:
+                cur_seq.append(DoubleQuotedScalarString(c))
+        else:
+            fh['trustedIPs'] = [DoubleQuotedScalarString(c) for c in final]
+        ep['forwardedHeaders'] = fh
+        eps[entrypoint] = ep
+        stream = StringIO()
+        _y.dump(config, stream)
+        new_raw = stream.getvalue()
+        parsed = SafeYAML(typ='safe').load(new_raw) or {}
+        resp.update({
+            'entrypoint': entrypoint,
+            'existing': existing,
+            'added': added,
+            'final': final,
+            'invalid': invalid,
+            'raw': new_raw,
+            'parsed': parsed,
+        })
+        return jsonify(resp)
+    except Exception as e:
+        logger.exception("Trusted IPs preview failed")
+        return jsonify({'error': str(e)}), 500
+
+
 @app.route('/api/setup/test-connection', methods=['POST'])
 @login_required
 def api_setup_test_connection():

docs/static.md

@@ -59,6 +59,26 @@ Multiple edits in one session only require a single restart.
 
 ---
 
+## Trusted IPs helper
+
+Behind a proxy such as Cloudflare, Traefik only believes `X-Forwarded-For` from sources listed in an entrypoint's `forwardedHeaders.trustedIPs`. Until those are set, your logs, CrowdSec, `ipAllowList` and the login limiter all see the proxy IP instead of the real client. The **Trusted IPs** button in the Static Config header opens a guided helper that writes that field for you.
+
+1. Pick the target entrypoint (for example `websecure`). Any `trustedIPs` already configured are shown.
+2. Choose one or more sources:
+   - **Cloudflare edge ranges** - the full IPv4 + IPv6 set, hardcoded with a capture date. Nothing is fetched at runtime.
+   - **Private ranges** - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`.
+   - **Your own proxies / LAN** - free-form CIDRs or single IPs, one per line. Invalid entries are flagged and skipped.
+3. Click **Preview change** to see exactly which ranges will be added. Existing entries are kept, and anything already trusted is deduplicated - the helper only ever adds.
+4. Click **Apply & Save** to stage the change into the static config, back it up, and save. As with any static change, a **Restart required** banner then appears.
+
+Because `trustedIPs` lives in the static config, this is global and needs a Traefik restart. Every trusted range can forge client IPs downstream, so only add proxies you control. Use the [Client IP Diagnostic](hardening.md) to confirm what actually reaches the app before and after. The helper works for the Host and for remote agents.
+
+::: tip Refreshing the Cloudflare ranges
+The hardcoded ranges live in `_CLOUDFLARE_IPS_V4` / `_CLOUDFLARE_IPS_V6` in `app.py`, sourced from [cloudflare.com/ips](https://www.cloudflare.com/ips/) (`/ips-v4` + `/ips-v6`). They are refreshed on release; replace both lists from that source and bump `_CLOUDFLARE_IPS_CAPTURED`.
+:::
+
+---
+
 ## Setup
 
 ### 1. Mount traefik.yml into TM

templates/index.html

@@ -424,6 +424,8 @@
 
 {% include 'modals/ip_diagnostic_modal.html' %}
 
+{% include 'modals/trusted_ips_modal.html' %}
+
 {% include 'modals/detail_panels.html' %}
 
 <script>
@@ -6862,6 +6864,7 @@ <h3 class="font-bold text-sm font-mono truncate" style="color:var(--text)" title
         const redir = ep.http?.redirections?.entryPoint?.to || '';
         const uhs   = ep.http?.underscoreHeadersStrategy || '';
         const http3 = !!ep.http3;
+        const tips  = Array.isArray(ep.forwardedHeaders?.trustedIPs) ? ep.forwardedHeaders.trustedIPs.length : 0;
         const port  = addr.replace(/^.*:/, '');
         const proto = port === '443' ? 'HTTPS' : port === '80' ? 'HTTP' : port ? port : '';
         const nd    = JSON.stringify(name);
@@ -6874,6 +6877,7 @@ <h3 class="font-bold text-sm font-mono truncate" style="color:var(--text)" title
                 ${redir ? `<span class="text-xs flex-shrink-0" style="color:var(--muted)">→ <span class="font-mono" style="color:var(--text)">${_esc(redir)}</span></span>` : ''}
                 ${http3 ? `<span class="text-xs px-1.5 py-0.5 rounded font-semibold flex-shrink-0" style="background:rgba(163,113,247,0.1);color:var(--purple)">HTTP/3</span>` : ''}
                 ${uhs ? `<span class="text-xs px-1.5 py-0.5 rounded font-semibold flex-shrink-0" style="background:rgba(63,185,80,0.12);color:var(--green)" title="underscoreHeadersStrategy: ${_esc(uhs)}"><i class="ph-bold ph-shield-check" style="font-size:10px"></i> ${_esc(uhs)}</span>` : ''}
+                ${tips ? `<span class="text-xs px-1.5 py-0.5 rounded font-semibold flex-shrink-0" style="background:rgba(36,161,222,0.1);color:var(--blue)" title="forwardedHeaders.trustedIPs: ${tips} range(s)"><i class="ph-bold ph-shield" style="font-size:10px"></i> ${tips} trusted</span>` : ''}
             </div>
             <div class="flex gap-1 flex-shrink-0">
                 <button onclick='openStaticEditForm("entrypoints",${nd})' class="btn-icon text-xs" title="Edit"><i class="ph-bold ph-pencil-simple"></i></button>
@@ -7515,6 +7519,120 @@ <h3 class="font-bold text-sm font-mono truncate" style="color:var(--text)" title
     await _loadStaticFromDisk();
 }
 
+let _tipData = null;
+
+function _tipBaseRaw() {
+    return _staticMonaco ? _staticMonaco.getValue() : _staticRawContent;
+}
+
+function _tipInvalidatePreview() {
+    if (_tipData) _tipData.preview = null;
+    const pv = document.getElementById('tipPreviewBox'); if (pv) pv.innerHTML = '';
+    const applyBtn = document.getElementById('tipApplyBtn'); if (applyBtn) applyBtn.disabled = true;
+}
+
+function openTrustedIpsHelper() {
+    const modal = document.getElementById('trustedIpsModal');
+    if (!modal) return;
+    _tipData = null;
+    document.getElementById('tipEntrypoint').innerHTML = '<option value="">Loading...</option>';
+    document.getElementById('tipCurrent').innerHTML = '';
+    document.getElementById('tipPreviewBox').innerHTML = '';
+    document.getElementById('tipCustom').value = '';
+    document.getElementById('tipSrcCloudflare').checked = true;
+    document.getElementById('tipSrcPrivate').checked = false;
+    document.getElementById('tipApplyBtn').disabled = true;
+    modal.style.display = 'flex';
+    _tipInspect();
+}
+
+function closeTrustedIpsModal() {
+    const m = document.getElementById('trustedIpsModal');
+    if (m) m.style.display = 'none';
+}
+
+async function _tipInspect() {
+    try {
+        const res = await fetch('/api/static/trusted-ips/preview', { method: 'POST', headers: { 'Content-Type': 'application/json', ..._csrfHeaders() }, body: JSON.stringify({ current_raw: _tipBaseRaw() }) });
+        const d = await res.json();
+        if (!res.ok || d.error) { showToast(d.error || 'Failed to read static config', 'error'); closeTrustedIpsModal(); return; }
+        _tipData = d;
+        const sel = document.getElementById('tipEntrypoint');
+        if (!d.entrypoints.length) {
+            sel.innerHTML = '<option value="">No entrypoints found</option>';
+        } else {
+            sel.innerHTML = d.entrypoints.map(e => `<option value="${_esc(e.name)}">${_esc(e.name)}${e.address ? ' (' + _esc(e.address) + ')' : ''}</option>`).join('');
+        }
+        const cf = document.getElementById('tipCfLabel');
+        if (cf) cf.textContent = `Cloudflare edge ranges (${(d.cloudflare_ranges || []).length}, captured ${d.cloudflare_captured})`;
+        _tipRenderCurrent();
+    } catch (e) { showToast('Failed to read static config', 'error'); closeTrustedIpsModal(); }
+}
+
+function _tipRenderCurrent() {
+    if (_tipData) _tipData.preview = null;
+    const applyBtn = document.getElementById('tipApplyBtn');
+    if (applyBtn) applyBtn.disabled = true;
+    const pv = document.getElementById('tipPreviewBox');
+    if (pv) pv.innerHTML = '';
+    const sel = document.getElementById('tipEntrypoint');
+    const name = sel ? sel.value : '';
+    const ep = (_tipData && _tipData.entrypoints || []).find(e => e.name === name);
+    const box = document.getElementById('tipCurrent');
+    if (!box) return;
+    const cur = (ep && ep.trusted_ips) || [];
+    if (!cur.length) {
+        box.innerHTML = `<span class="text-xs" style="color:var(--muted)">No <code class="font-mono">trustedIPs</code> on this entrypoint yet.</span>`;
+    } else {
+        box.innerHTML = `<div class="text-xs mb-1" style="color:var(--muted)">Current <code class="font-mono">trustedIPs</code> (${cur.length}):</div><div class="flex flex-wrap gap-1">` + cur.map(c => `<span class="text-xs font-mono px-1.5 py-0.5 rounded" style="background:var(--input-bg);color:var(--text)">${_esc(c)}</span>`).join('') + `</div>`;
+    }
+}
+
+async function tipPreview() {
+    const sel = document.getElementById('tipEntrypoint');
+    const entrypoint = sel ? sel.value : '';
+    if (!entrypoint) { showToast('Pick an entrypoint', 'error'); return; }
+    const cloudflare = document.getElementById('tipSrcCloudflare').checked;
+    const priv = document.getElementById('tipSrcPrivate').checked;
+    const custom = document.getElementById('tipCustom').value;
+    if (!cloudflare && !priv && !custom.trim()) { showToast('Select at least one source', 'error'); return; }
+    try {
+        const res = await fetch('/api/static/trusted-ips/preview', { method: 'POST', headers: { 'Content-Type': 'application/json', ..._csrfHeaders() }, body: JSON.stringify({ current_raw: _tipBaseRaw(), entrypoint, cloudflare, private: priv, custom_cidrs: custom }) });
+        const d = await res.json();
+        if (!res.ok || d.error) { showToast(d.error || 'Preview failed', 'error'); return; }
+        if (_tipData) _tipData.preview = d;
+        _tipRenderPreview(d);
+    } catch (e) { showToast('Preview failed', 'error'); }
+}
+
+function _tipRenderPreview(d) {
+    const box = document.getElementById('tipPreviewBox');
+    if (!box) return;
+    const added = d.added || [], invalid = d.invalid || [], existing = d.existing || [];
+    let html = '';
+    if (!added.length && !invalid.length) {
+        html += `<div class="text-xs px-3 py-2 rounded" style="background:rgba(234,179,8,0.1);color:#ca8a04">Nothing new to add - every selected range is already trusted on <span class="font-mono">${_esc(d.entrypoint)}</span>.</div>`;
+    }
+    if (added.length) {
+        html += `<div class="text-xs mb-1" style="color:var(--green)"><i class="ph-bold ph-plus-circle"></i> Adding ${added.length} range${added.length > 1 ? 's' : ''}:</div><div class="flex flex-wrap gap-1 mb-2">` + added.map(c => `<span class="text-xs font-mono px-1.5 py-0.5 rounded" style="background:rgba(63,185,80,0.12);color:var(--green)">${_esc(c)}</span>`).join('') + `</div>`;
+    }
+    if (invalid.length) {
+        html += `<div class="text-xs mb-1" style="color:var(--red)"><i class="ph-bold ph-warning"></i> Skipped ${invalid.length} invalid entr${invalid.length > 1 ? 'ies' : 'y'}:</div><div class="flex flex-wrap gap-1 mb-2">` + invalid.map(c => `<span class="text-xs font-mono px-1.5 py-0.5 rounded" style="background:rgba(239,68,68,0.12);color:var(--red)">${_esc(c)}</span>`).join('') + `</div>`;
+    }
+    html += `<div class="text-xs" style="color:var(--muted)">Result: <span style="color:var(--text);font-weight:600">${d.final.length}</span> trusted range${d.final.length !== 1 ? 's' : ''} on <span class="font-mono">${_esc(d.entrypoint)}</span> (was ${existing.length}).</div>`;
+    box.innerHTML = html;
+    document.getElementById('tipApplyBtn').disabled = !added.length;
+}
+
+async function tipApply() {
+    const d = _tipData && _tipData.preview;
+    if (!d || !d.raw) return;
+    _staticRawContent = d.raw;
+    if (_staticMonaco) _staticMonaco.setValue(d.raw);
+    closeTrustedIpsModal();
+    await saveStaticConfig();
+}
+
 const _origSetTheme = setTheme;
 setTheme = function(theme) {
     _origSetTheme(theme);

templates/modals/settings_modal.html

@@ -736,6 +736,10 @@ <h3 class="font-bold text-sm" style="color:var(--text)" id="settingsModalTitle">
                                 <i id="staticHdrAddIcon" class="ph-bold ph-plus text-xs" style="color:var(--blue)"></i>
                                 <span id="staticHdrAddLabel">Entrypoint</span>
                             </button>
+                            <button onclick="openTrustedIpsHelper()" class="btn-secondary text-xs flex items-center gap-1.5" title="Add trusted proxy IPs to an entrypoint" style="height:28px;padding:0 10px">
+                                <i class="ph-bold ph-shield-check text-xs" style="color:var(--green)"></i>
+                                Trusted IPs
+                            </button>
                             <button onclick="openStaticYamlPopout()" class="btn-secondary text-xs flex items-center gap-1.5" style="height:28px;padding:0 10px">
                                 <i class="ph-bold ph-code text-xs"></i>
                                 Raw YAML