Harden Dynu/Traefik DNS correlation and validation

2026-04-21 14:11:25 +10:00
parent 872038d0c9
commit fae5e119d1
3 changed files with 389 additions and 194 deletions
@@ -18,9 +18,74 @@ This repository includes a **read-only** Dynu DNS inventory workflow for `lan.dd
 - No Ansible Dynu mutation tasks are introduced.
 - API secrets are read from environment variables and are never logged.

+## Correlation logic
+
+`scripts/dynu/correlate_dynu_with_traefik.py` uses compose files as the source of truth and parses them as YAML.
+
+It supports both common label formats:
+
+- list style:
+
+```yaml
+labels:
+  - "traefik.http.routers.app.rule=Host(`app.lan.ddnsgeek.com`)"
+```
+
+- map style:
+
+```yaml
+labels:
+  traefik.http.routers.app.rule: "Host(`app.lan.ddnsgeek.com`)"
+```
+
+The parser extracts hostnames from router rules such as:
+
+- `Host(`a`)`
+- `Host("a")`
+- `Host('a')`
+- multi-host rules (comma-delimited)
+- combined expressions such as `Host(...) && PathPrefix(...)`
+
+## Route metadata in inventory
+
+Each discovered hostname mapping includes:
+
+- fqdn
+- compose service name
+- compose file path
+- stack area (`apps`, `monitoring`, `core`)
+- router label key(s)
+- raw router rule
+- `uses_tls`
+- `tls_options`
+- `middlewares`
+- `uses_mtls`
+- `uses_authelia`
+
+mTLS is metadata only and **never blocks mapping**.
+
+## Validation model
+
+The generated JSON/Markdown include a top-level `validation` section with:
+
+- `allowed_unmapped_hostnames`
+- `unexpected_unmapped_hostnames`
+- `duplicate_hostnames`
+- `ambiguous_hostnames`
+- `validation_ok`
+
+Current policy:
+
+- `edge.lan.ddnsgeek.com` is the only allowed unmapped DNS hostname.
+- every other `*.lan.ddnsgeek.com` DNS hostname should map to a compose/Traefik-discovered service.
+
+Optional strict mode:
+
+- Set `DYNU_ENFORCE_VALIDATION=true` to make the correlate script exit non-zero when unexpected unmapped hostnames exist.
+
 ## Required Environment Variables

- `DYNU_API_KEY` (required)
+- `DYNU_API_KEY` (required for fetch)
 - `DYNU_BASE_URL` (optional, defaults to `https://api.dynu.com`)
 - `DYNU_READ_ONLY` (**must** be `true`)

@@ -33,6 +98,7 @@ DYNU_BASE_URL=https://api.dynu.com
 ```

 Notes:
+
 - Keep values unquoted unless required by your shell.
 - `scripts/dynu/build_dns_inventory.sh` will auto-load `secrets/dynu.env` when present.