From bf211ca27341e6e3fe8ac6a22928c8fe2695c265 Mon Sep 17 00:00:00 2001 From: Debian Date: Sat, 6 Jun 2026 17:34:10 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Feature-Stand=20nachgezogen=20=E2=80=94?= =?UTF-8?q?=20WAF/IDS-IPS/DHCP/RADIUS/OIDC/2FA=20umgesetzt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md + architecture.md spiegelten noch den ursprünglichen v1-Scope (WAF/IDS/IPS/DHCP/RADIUS als Nicht-Ziele) wider. Real umgesetzt: WAF (Coraza+SPOE), IDS/IPS (CrowdSec, managed-wenn-installiert), DHCP (Kea), RADIUS (FreeRADIUS), OIDC-SSO, 2FA, IPv6-FW. Nicht-Ziele bereinigt (verbleibend: Suricata-Network-IDS, Docker, Mail, Multi-Tenant, ISO, Debian-only). Stack-Tabelle + Paket-Tabelle/Depends an control angeglichen; edgeguard-waf als Binary im edgeguard-api-Paket dokumentiert. KeyDB als optional (Recommends) korrigiert; Cluster-Primary-Ermittlung via pg_publication/setup.json statt KeyDB; Doku-Drift internal/proxy (nicht vorhanden) markiert. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 39 +++++++++++++++++++++++++++++++-------- docs/architecture.md | 8 ++++---- 2 files changed, 35 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b011077..ac7700c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,7 +13,9 @@ Vor jeder Entscheidung über Feldwerte, API-Shapes, Dateinamen, Funktions-Signat # EdgeGuard Native (`eg`) -> Native Neufassung des Docker-basierten EdgeGuard-Stacks. Kein Docker, kein WAF in v1. Zielplattform: **Debian 13 (Trixie), amd64 + arm64**. Auslieferung als signiertes `.deb`. +> Native Neufassung des Docker-basierten EdgeGuard-Stacks. Kein Docker — alle Dienste nativ unter systemd. Zielplattform: **Debian 13 (Trixie), amd64 + arm64**. Auslieferung als signiertes `.deb`. +> +> **Hinweis:** Mehrere ursprüngliche v1-Nicht-Ziele (WAF, IDS/IPS, DHCP, RADIUS) sind inzwischen umgesetzt — siehe „Feature-Stand" weiter unten. --- @@ -67,26 +69,47 @@ ac_search_code(query="", project_id=8, session_name="$(printenv ARCH | **API** | Go 1.26, Gin, GORM (Queries), goose (Migrations) | | **UI** | React 19, TypeScript strict, Vite, Ant Design 6, TanStack Query 5 | | **DB** | PostgreSQL 16 (Distro-Paket), goose-Migrations in `migrations/` | -| **State/HA** | KeyDB Active-Active (Redis-kompatibel) | +| **State/HA** | PostgreSQL Logical Replication + Cluster-Agent-Heartbeat (mTLS); KeyDB Active-Active nur optional (`Recommends`, für Lizenz-Leader-Election/Shared-Cache) | | **Proxy/LB** | HAProxy (Distro) — TLS-Termination, L7-Routing, LB | +| **WAF** | Coraza v3 + OWASP CRS, via HAProxy SPOE (`edgeguard-waf`-Agent) | +| **IDS/IPS** | CrowdSec + `crowdsec-firewall-bouncer` (nftables) — managed-wenn-installiert (kein Depends) | | **VPN** | WireGuard (Kernel-Modul ab 5.6, `wireguard-tools`) | | **DNS** | Unbound (Distro) — Forwarder+Cache mit DNSSEC, Cluster-internes Split-Horizon | +| **DHCP** | Kea (`kea-dhcp4-server`) — managed, default-off | +| **AAA/RADIUS** | FreeRADIUS (PAP/CHAP, files-based) — managed, default-off | +| **NTP** | chrony (Distro) | +| **VIP/HA** | keepalived (VRRP) | | **FW** | nftables (Distro) | | **Forward-Proxy** | Squid (Distro) | +| **Auth/SSO** | JWT (lokal) + 2FA/TOTP + OIDC/OAuth2 (Keycloak u. a.) | | **TLS** | certbot + webroot-Plugin | | **Packaging** | dpkg-deb (direkt, wie mail-gateway + netcell-webpanel) | | **Plattform** | Debian 13 Trixie · amd64 + arm64 | --- -## Nicht-Ziele (v1) +## Feature-Stand (Stand 2026-06) + +Über den ursprünglichen v1-Scope hinaus inzwischen **umgesetzt** (waren mal Nicht-Ziele): + +- **WAF** — Coraza v3 + OWASP CRS via HAProxy SPOE (`edgeguard-waf`) +- **IDS/IPS** — CrowdSec + `crowdsec-firewall-bouncer` (nftables-Bouncer); managed-wenn-installiert, kein hartes Depends +- **DHCP** — Kea `kea-dhcp4-server` (managed, default-off) +- **RADIUS** — FreeRADIUS PAP/CHAP, files-based (managed, default-off) +- **SSO** — OIDC/OAuth2 (additiv, Rolle aus DB, lokaler Login bleibt) +- **2FA** — TOTP +- **IPv6** — Firewall-Regeln + NAT familienbewusst +- **HA** — VIP via keepalived (VRRP), PG-Logical-Replication, bidirektionaler Cluster-Heartbeat + +Damit ist die ursprüngliche v2-Roadmap (WAF, 2FA, IPv6-FW, OIDC, DHCP, RADIUS) abgearbeitet. + +## Nicht-Ziele (weiterhin) - **Kein Docker** — alle Dienste nativ unter systemd -- **Kein WAF** (kein Coraza, kein ModSecurity) -- **Kein IDS/IPS** (kein Suricata, kein CrowdSec) -- **Kein DHCP-Server** (kein Kea) -- **Kein RADIUS** (kein FreeRADIUS) +- **Kein Network-IDS Suricata** — Intrusion-Detection läuft über CrowdSec, nicht über Suricata-Paket-Inspektion - **Keine Mail-Verarbeitung** (eigenes Produkt: mail-gateway) +- **Keine Multi-Tenant-GuardZones** +- **Keine ISO-Builds** (kein EdgeGuardOS-Klon — nur APT) - **Nur Debian 13** — kein Ubuntu, kein Debian 12, kein RHEL --- @@ -185,7 +208,7 @@ cd management-ui && bun run dev - **ORM:** GORM für Queries, nicht für Schema-Verwaltung - **Config-Generierung:** Template-Datei in `deploy/*/`, Generator in `internal/*/` - **Config-Reload:** `systemctl reload ` nach Config-Schreiben -- **Cluster-Writes:** immer über `internal/proxy` → Primary-URL aus KeyDB `cluster:pg-primary-url` +- **Cluster-Primary-Ermittlung:** zuverlässig über `pg_publication` (`edgeguard_shared`); Primary-URL aus `setup.json` `PrimaryFQDN` via `clusterjoin.NormalizePrimaryURL`. `edgeguard-ctl promote` aktualisiert KeyDB `cluster:pg-primary-url` nur, wenn KeyDB vorhanden ist. _(Hinweis: das in der Projektstruktur gelistete `internal/proxy` existiert derzeit nicht — Doku-Drift, siehe unten.)_ ### Packaging - `dpkg-deb` direkt (wie mail-gateway) — kein dh_make/debhelper/fpm diff --git a/docs/architecture.md b/docs/architecture.md index bb48c10..5bec290 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -12,10 +12,10 @@ EdgeGuard ist die native Neufassung des bisherigen Docker-basierten Reverse-Prox - **Plattform-Matrix:** Debian 13 (Trixie) **und** Ubuntu 24.04 LTS (Noble Numbat), je amd64 + arm64. Alle vier Targets gleichberechtigt. - **Auslieferung:** signierte `.deb`-Pakete + Meta-Paket via APT. Bootstrap ist der enconf-analoge curl-Onliner `curl -fsSL https://get.edgeguard.netcell-it.de | sudo bash`. - **HA nativ als Cluster:** N symmetrische Peers, **KeyDB Active-Active** für Shared State + **PostgreSQL Streaming Replication** (single writer, transparenter API-Write-Proxy) + **Floating-IP des Hosters** für HTTP/HTTPS-Ingress (nicht VRRP, nicht DNS-RR). -- **Kein WAF, kein IDS, kein DHCP, kein RADIUS, keine Mail-Funktion in v1.** Mail-Gateway ist eigenes Produkt (`nmg`); WAF/CrowdSec/Suricata kommen ggf. in v2. +- **WAF, IDS/IPS, DHCP, RADIUS inzwischen umgesetzt** (Stand 2026-06): WAF via Coraza+SPOE, IDS/IPS via CrowdSec, DHCP via Kea, RADIUS via FreeRADIUS. Mail-Funktion bleibt ausgeschlossen — Mail-Gateway ist eigenes Produkt (`nmg`). - **Migrations:** `goose` (SQL-Dateien), nicht GORM AutoMigrate. -**Nicht-Ziele (ausdrücklich):** kein WAF, kein Network-IDS (Suricata), kein IPS (CrowdSec), kein DHCP-Server (Kea), kein RADIUS, keine Mail-Verarbeitung, keine Multi-Tenant-GuardZones in v1, keine ISO-Builds (kein EdgeGuardOS-Klon — nur APT). +**Nicht-Ziele (weiterhin):** kein Network-IDS via Suricata (IDS/IPS läuft über CrowdSec), keine Mail-Verarbeitung, keine Multi-Tenant-GuardZones, keine ISO-Builds (kein EdgeGuardOS-Klon — nur APT). _(Historisch waren auch WAF/DHCP/RADIUS/IPS Nicht-Ziele — siehe oben, inzwischen umgesetzt.)_ --- @@ -94,11 +94,11 @@ EdgeGuard ist die native Neufassung des bisherigen Docker-basierten Reverse-Prox ## 3. Debian-Pakete -Drei Pakete + Meta — analog nmg, kein WAF-Paket weil kein WAF in v1. +Drei Pakete + Meta — analog nmg. Der WAF-Agent `edgeguard-waf` ist **kein eigenes Paket**, sondern liegt als zusätzliches Binary im `edgeguard-api`-Paket (eigene systemd-Unit). | Paket | Arch | Inhalt | Depends | |---|---|---|---| -| `edgeguard-api` | amd64, arm64 | `/usr/bin/edgeguard-{api,scheduler,ctl}`, Unit-Files, Migrations, Default-Configs | `postgresql-16`, `keydb-server`, `haproxy`, `squid`, `wireguard-tools`, `unbound`, `nftables`, `certbot`, `openssl` | +| `edgeguard-api` | amd64, arm64 | `/usr/bin/edgeguard-{api,scheduler,ctl,waf}`, Unit-Files, Migrations, Default-Configs | `postgresql-16 \| postgresql-17`, `haproxy (>=2.8)`, `squid`, `wireguard-tools`, `unbound`, `chrony`, `kea-dhcp4-server`, `freeradius`, `nftables`, `keepalived`, `certbot`, `openssl`, `sudo`, `adduser`, `systemd`, `ca-certificates`, `ulogd2`, `ulogd2-json` u. a. · _Recommends:_ `edgeguard-keydb`, `apparmor`, `fail2ban` · _CrowdSec: managed-wenn-installiert (kein Depends)_ | | `edgeguard-ui` | all | `/usr/share/edgeguard/ui/` (statische Build-Artefakte) | `edgeguard-api (= ${binary:Version})` | | `edgeguard-meta` | all | keine Dateien, nur `Depends` | `edgeguard-api`, `edgeguard-ui` |