Synit WAF

Konfiguration

Konfigurationsreferenz für Synit WAF: Domains, Tenants, Regelprofile, Audit Mode, APIs, GraphQL, LLM-Schutz, Logging und sichere Rollout-Werte.

Konfiguration

Synit WAF wird über YAML konfiguriert. Eine Konfiguration beschreibt globale Laufzeitwerte, Logging, Produktzugang, wiederverwendbare Regelprofile, geschützte Domains und die aktiven Sicherheitskontrollen.

Diese Referenz ist bewusst kundenorientiert. Interne Lizenzadministration, Build-Prozesse und Betreiber-Workflows sind nicht Teil der öffentlichen Dokumentation.

Aufbau einer Konfiguration

global_settings:
  log_level: "INFO"
  response_buffer_limit: 1048576
  request_body_oversize_action: "reject"
  security_dependency_failure_mode: "fail_open"
  read_timeout: "15s"
  write_timeout: "15s"
  idle_timeout: "60s"
  trust_forwarded_for: false

license:
  key: "<product-access-key>"
  server_url: "<validation-url-from-handoff>"
  api_token: "<optional-api-token>"

logging:
  access_log:
    enabled: true
    format: "json"

waf_rule_sets:
  "base-protection": |
    SecRule REQUEST_METHOD "@rx (?i:^(trace|track)$)" "id:110001,phase:1,deny,status:403,log,msg:'Blocked unsafe HTTP method'"

tenants:
  "app.example.test":
    upstreams:
      - url: "http://application:8080"
    security:
      waf_enabled: true
      audit_mode: true
      paranoia_level: 1
      include_rule_sets:
        - "base-protection"

Globale Einstellungen

Häufige Werte:

  • log_level: Log-Detailgrad, in Produktion meist INFO.
  • response_buffer_limit: Grenze für Body-Inspection.
  • request_body_oversize_action: Verhalten bei zu großen Request Bodies, typischerweise reject oder allow_uninspected.
  • security_dependency_failure_mode: Verhalten, wenn optionale Sicherheitsdienste nicht erreichbar sind.
  • fail_open schützt Verfügbarkeit, fail_closed schützt Durchsetzung.
  • read_timeout, write_timeout, idle_timeout: robuste HTTP-Timeouts.
  • global_rate_limit: prozessweiter Schutz gegen Traffic-Spitzen.
  • trust_forwarded_for: nur aktivieren, wenn Synit WAF hinter vertrauenswürdigen Proxies oder Load Balancern läuft.
  • ip_sets.allow_list und ip_sets.block_list: globale IP- oder CIDR-Listen vor der Tenant-Prüfung.
  • coordinator: optionale Synchronisierung mehrerer WAF-Replikas, wenn Rate Limits oder Cluster-Verhalten zentral abgestimmt werden müssen.
  • acme: optionale automatische TLS-Zertifikate. Typische Felder sind enabled, email, storage_path, staging, dns_provider und dns_token.

Beispiel für automatische Zertifikate:

global_settings:
  acme:
    enabled: true
    email: "security@example.test"
    storage_path: "/var/lib/waf/acme"
    staging: false
    dns_provider: "cloudflare"
    dns_token: "<dns-api-token>"

Beispiel für mehrere Replikas:

global_settings:
  coordinator:
    enabled: true
    role: "leader"
    address: "waf-leader:8089"
    secret: "<shared-cluster-secret>"

Produktzugang

Der license-Block enthält kundenbezogene Produktzugangsdaten.

license:
  key: "<product-access-key>"
  server_url: "<validation-url-from-handoff>"
  api_token: "<optional-api-token>"

Behandeln Sie diese Werte als Secrets. Speichern Sie sie nicht in öffentlichen Repositories, Tickets, Screenshots oder Chatverläufen.

Logging und Sichtbarkeit

logging:
  access_log:
    enabled: true
    format: "json"
  error_log:
    enabled: true
    format: "json"

Strukturierte Logs erleichtern Suche, Alerting und spätere Tuning-Entscheidungen. Optionales Log Forwarding wird nur genutzt, wenn es Teil Ihres Angebots und Handoff-Pakets ist.

Für Betrieb und Monitoring sind typischerweise relevant:

  • Liveness
  • Readiness
  • Metriken
  • strukturierte Sicherheitsereignisse

Regelprofile

waf_rule_sets definiert wiederverwendbare Profile. Tenants binden diese Profile mit include_rule_sets ein.

Empfohlene Staffelung:

base-protection

Für erste Rollouts, Marketingseiten, Portale und geringe False-Positive-Toleranz.

advanced-protection

Für öffentliche APIs, login-starke Anwendungen und höhere Scanner-Last.

optimized-protection

Für getunte Produktionsumgebungen mit dokumentierten Ausnahmen und klaren Freigaben.

Profile können direkt in YAML gepflegt oder als externe Regeldateien bereitgestellt werden. Externe Profile passen besser, wenn mehrere Tenants dieselben Regeln nutzen oder wenn Änderungen über Review und Versionierung laufen.

Typische Dateien:

Datei Zweck
/etc/waf/rules/crs-setup.conf CRS-Grundeinstellungen, Paranoia-Level, HTTP-Policy und Anomaly-Scoring
/etc/waf/rules/profiles/api-strict.conf strengeres API-Profil mit Methoden- und Content-Type-Regeln
/etc/waf/rules/profiles/wordpress.conf CMS-Profil mit WordPress-spezifischen Ausnahmen und Blocks

Starten Sie externe Profile ebenfalls im Audit Mode. Besonders CRS-Paranoia-Level ab 2 können mehr False Positives erzeugen und sollten zuerst auf Staging oder einzelnen Tenants geprüft werden.

Geschützte Domains, Wildcards und Tenants

Jeder Eintrag unter tenants steht für eine Domain oder ein Host-Muster.

tenants:
  "portal.example.test":
    upstreams:
      - url: "http://portal-service:8080"
      - url: "http://portal-service-2:8080"
    upstreamInsecure: false
    security:
      waf_enabled: true
      audit_mode: true
      paranoia_level: 1
      include_rule_sets:
        - "base-protection"

Wichtige Felder:

  • upstreams: Zielsysteme hinter der WAF.
  • upstreamInsecure: TLS-Prüfung zum Upstream nur deaktivieren, wenn fachlich begründet.
  • waf_enabled: aktiviert die Prüfung.
  • audit_mode: protokolliert auffällige Anfragen ohne Blocking.
  • paranoia_level: Strengegrad, schrittweise erhöhen.
  • include_rule_sets: wiederverwendbare Profile.

Sicherheitskontrollen

Audit Mode

audit_mode: true ist der empfohlene Start. Auffälliger Traffic wird sichtbar, ohne Nutzer direkt zu blockieren.

Aktives Blocking

audit_mode: false erst nach Log-Prüfung, Freigabe und Rollback-Plan aktivieren.

Block-Seiten können zentral gesteuert werden:

security:
  block_page_url: "https://status.example.test/security-blocked"
  block_page_path: "/etc/waf/block.html"

block_page_url leitet blockierte Nutzer weiter. block_page_path liefert eine lokale HTML-Datei aus. Wenn die Datei Platzhalter wie {{EVENT_ID}} oder {{HOST}} enthält, können Support und Security den Vorfall leichter zuordnen.

CrowdSec

CrowdSec kann dynamische Threat-Entscheidungen ergänzen.

crowdsec:
  api_url: "http://crowdsec:8080/"
  api_key: "<crowdsec-bouncer-key>"

tenants:
  "app.example.test":
    security:
      crowdsec_enabled: true

GeoIP

GeoIP-Regeln können Länderbeschränkungen abbilden.

geoip:
  db_path: "/etc/waf/geoip/GeoLite2-Country.mmdb"

tenants:
  "admin.example.test":
    security:
      geoip_enabled: true
      blocked_countries: ["RU", "CN"]

Nutzen Sie Länderblocking nur mit fachlicher Begründung. VPNs, Support-Dienstleister und Mobilfunknetze können betroffen sein.

Rate Limits

security:
  rate_limit:
    requests_per_minute: 600
    burst: 120

Rate Limits helfen gegen Bots, fehlerhafte Clients und Lastspitzen. Stimmen Sie Werte auf reale Nutzung, API-Batching und NAT-/Proxy-Situationen ab.

Methoden und Content-Type für APIs

Für strengere APIs können Methoden und JSON-Content-Type als eigene Regeln geprüft werden.

waf_rule_sets:
  "api-strict": |
    SecRule REQUEST_METHOD "!@rx ^(GET|POST|PUT|DELETE|PATCH|OPTIONS)$" "id:210001,phase:1,deny,status:405,log,msg:'Method not allowed'"
    SecRule REQUEST_METHOD "@rx ^(POST|PUT)$" "id:210002,phase:1,chain,deny,status:415,log,msg:'JSON Content-Type required'"
      SecRule REQUEST_HEADERS:Content-Type "!@contains application/json" "t:none"

Dieses Muster passt für JSON-APIs. Es passt nicht für Uploads, Webhooks oder Form-Posts, wenn diese bewusst andere Content-Types nutzen.

JWT / JWKS-Prüfung

security:
  jwt_validation:
    enabled: true
    jwks_endpoint: "https://auth.example.test/.well-known/jwks.json"
    issuer: "https://auth.example.test/"
    audience: "api.example.test"

So können APIs Anfragen schon am Edge prüfen, bevor sie Backend-Ressourcen belasten.

Basic Auth für geschützte Bereiche

security:
  basic_auth:
    - user: "admin"
      password: "<bcrypt-password-hash>"

Nur gehashte Passwörter verwenden. Keine Klartext-Passwörter in Konfiguration oder Tickets speichern.

CMS- und WordPress-Schutz

CMS-Profile können sensible Dateien blockieren und bekannte Angriffsflächen reduzieren.

waf_rule_sets:
  "cms-protection": |
    SecRule REQUEST_URI "@contains wp-config.php" "id:200002,phase:1,deny,status:403,log,msg:'Blocked access to wp-config.php'"
    SecRule REQUEST_URI "@contains xmlrpc.php" "id:200003,phase:1,deny,status:403,log,msg:'Blocked access to xmlrpc.php'"

WordPress-Adminbereiche können legitime Requests erzeugen, die strengere CRS-Regeln berühren. Ausnahmen sollten deshalb eng auf Pfade, Regel-IDs und Tenants begrenzt werden.

GraphQL-Schutz

security:
  graphql:
    enabled: true
    block_introspection: true
    max_query_depth: 8
    max_batched_queries: 10

Hilft gegen unbeabsichtigte Schema-Offenlegung, zu tiefe Queries und oversized Batch-Anfragen.

LLM-Schutz

security:
  llm_protection:
    enabled: true
    mode: "rules"
    action: "audit"
    inspect_paths:
      - "/v1/chat"
    inspect_json_fields:
      - "prompt"
      - "messages[].content"

LLM-Schutz prüft konfigurierte Pfade und Felder auf Prompt-Injection- und Prompt-Extraction-Muster. Starten Sie mit action: "audit" und wechseln Sie erst nach Prüfung auf deny.

Response Masking

Wenn aktiviert, kann Response Masking sensible Muster in Antworten reduzieren, etwa Tokens, IDs oder andere definierte Textmuster.

security:
  response_masking:
    - pattern: "(?i)(api[_-]?token=)[^&\\s]+"
      replacement: "$1[redacted]"

Regeln sollten eng formuliert und im Audit Mode getestet werden, damit keine fachlich wichtigen Inhalte beschädigt werden.

Header-Transformationen

Header-Transformationen können Upstream-Systeme mit Gateway-Kontext versorgen oder unerwünschte Header entfernen.

header_transform:
  inject_request:
    X-Synit-Tenant: "{{TENANT}}"
    X-Client-IP: "{{CLIENT_IP}}"

Unterstützte Bereiche sind inject_request, strip_request, inject_response und strip_response.

Upstream Circuit Breaker

Ein Circuit Breaker kann fehlerhafte Upstreams temporär aus der Rotation nehmen.

security:
  circuit_breaker:
    enabled: true
    threshold: 5
    cooldown: "30s"
    failure_status_codes: [502, 503, 504]

threshold zählt aufeinanderfolgende Fehler. cooldown legt die Wartezeit bis zum nächsten Versuch fest. failure_status_codes definiert, welche Upstream-Antworten als Fehler zählen.

Test-Bypass

dev_bypass_secret ist nur für eng kontrollierte Test- und Notfallpfade gedacht. Wenn der Header X-Synit-Dev-Bypass exakt passt, werden WAF-Prüfungen übersprungen.

security:
  dev_bypass_secret: "<temporary-secret>"

In Produktion nur mit Ablaufdatum, Audit und Freigabe nutzen. Nicht als dauerhaftes Ausnahme-System einsetzen.

Eigene Geschäftsregeln

Nutzen Sie custom_rules, wenn Standardprofile eine fachliche Besonderheit nicht abbilden.

security:
  custom_rules: |
    SecRule REQUEST_HEADERS:X-Legacy-API "@rx .+" "id:240001,phase:1,deny,status:400,log,msg:'Deprecated header blocked'"

Empfohlener Ablauf:

  • Eine Regel nach der anderen ergänzen.
  • Im Audit Mode starten.
  • False Positives prüfen.
  • Kleine Tenant-Gruppe testen.
  • Grund und Freigabe dokumentieren.

Modulare Tenant-Dateien

Bei vielen Domains kann die Tenant-Konfiguration in separate Dateien ausgelagert werden, wenn dies Teil Ihres Deployment-Modells ist.

Beispiel tenants.d/customer-a.yml:

tenants:
  "customer-a.example.test":
    upstreams:
      - url: "http://customer-a-service:8080"
    security:
      waf_enabled: true
      audit_mode: true
      include_rule_sets:
        - "base-protection"

Dieses Muster passt für:

  • SaaS-Kundendomains
  • Agenturen und Managed-Service-Umgebungen
  • Multi-Domain-Portale
  • automatisiertes Onboarding

Umgebungsvariablen

Container- und Plattformumgebungen können ausgewählte Werte per Environment setzen, zum Beispiel:

WAF_GLOBAL_LOG_LEVEL WAF_GLOBAL_RESPONSE_BUFFER_LIMIT WAF_GLOBAL_REQUEST_BODY_OVERSIZE_ACTION WAF_GLOBAL_SECURITY_DEPENDENCY_FAILURE_MODE WAF_GLOBAL_READ_TIMEOUT WAF_GLOBAL_WRITE_TIMEOUT WAF_GLOBAL_IDLE_TIMEOUT WAF_GLOBAL_TRUST_FORWARDED_FOR WAF_GLOBAL_ACME_ENABLED WAF_GLOBAL_ACME_EMAIL WAF_GLOBAL_ACME_STORAGE_PATH WAF_GLOBAL_ACME_STAGING WAF_COORDINATOR_ENABLED WAF_COORDINATOR_ROLE WAF_COORDINATOR_ADDRESS WAF_COORDINATOR_SECRET WAF_LICENSE_KEY WAF_LICENSE_SERVER_URL WAF_LICENSE_API_TOKEN WAF_CROWDSEC_URL WAF_CROWDSEC_KEY

Produktzugangsdaten gehören in Secret Manager oder geschützte Plattform-Secrets.

Werte, die nicht öffentlich abgelegt werden dürfen

  • Produktzugangsdaten
  • CrowdSec- oder Log-Forwarding-Tokens
  • Passwort-Hashes realer Accounts
  • private Upstream-Hostnamen sensibler Systeme
  • kundenspezifische Domains vor Launch
  • unbereinigte Sicherheitslogs
United in Diversity