Firewall for sgcWebSockets Servers

· Components

Sicherheit ist nicht mehr optional. Jeder WebSocket-Server, der im Internet erreichbar ist, ist Ziel von Brute-Force-Angriffen, Injection-Versuchen, Verbindungsfluten und automatisiertem Missbrauch. Sich gegen diese Bedrohungen zu verteidigen, erfordert üblicherweise externe Middleware, eigene Filterlogik oder ein separates Reverse-Proxy — all das erhöht die Komplexität und bremst die Entwicklung.

Mit sgcWebSockets 2026.4.0 kommt TsgcWSFirewall — eine dedizierte Firewall-Komponente, die direkt in deinen WebSocket-Server eingebunden wird, nun mit 15 Schutzmodulen, darunter GeoIP-Länderfilterung, adaptive Bedrohungs-Bewertung, progressive Bann-Eskalation und eine eigene Regel-Engine. Komponente ablegen, gewünschte Schutzmodule konfigurieren, an den Server zuweisen, fertig. Keine externen Abhängigkeiten. Keine Middleware. Kein eigener Code für die üblichen Fälle.

Dieser Artikel zeigt den vollständigen Funktionsumfang und wie du jedes Schutzmodul in Delphi konfigurierst.

Fünfzehn Schutzmodule, eine Komponente

Die Firewall bietet fünfzehn unabhängige Schutzmodule. Aktiviere nur das, was du brauchst — jedes Modul funktioniert für sich oder in Kombination mit den anderen.

IP-Blacklist
Sperre bestimmte IP-Adressen oder ganze Bereiche per CIDR-Notation. Verbindungen aus geblacklisteten IPs werden abgelehnt, bevor sie deinen Anwendungscode erreichen. 		IP-Whitelist
Definiere eine Liste vertrauenswürdiger IPs. Aktiviert, umgehen Whitelist-Adressen alle anderen Sicherheitsprüfungen — ideal für interne Dienste und Monitoring-Tools. 		Brute-Force-Schutz
Verfolge fehlgeschlagene Authentifizierungsversuche pro IP. Sperre Angreifer automatisch, sobald eine konfigurierbare Schwelle innerhalb eines gleitenden Zeitfensters überschritten wird.
SQL-Injection-Erkennung
Untersuche eingehende Nachrichten auf gängige SQL-Injection-Muster. Eingebaute Erkennung für Boolean-Injection, UNION SELECT, Statement-Injection und mehr. 		XSS-Erkennung
Erkenne Cross-Site-Scripting-Payloads in Nachrichten. Fängt Script-Tags, Event-Handler, JavaScript-Protokoll-URIs, iframe-Injection und CSS-Expressions ab. 		Verbindungs-Rate-Limiting
Begrenze die Anzahl gleichzeitiger Verbindungen pro IP. Verhindere, dass ein einzelner Client die Server-Ressourcen ausschöpft.
Schutz vor Nachrichten-Flood
Drossle die Anzahl der Nachrichten, die eine einzelne IP pro Sekunde senden darf. Schützt vor Nachrichten-Flooding und Denial-of-Service-Mustern. 		Payload-Größenlimit
Weise Nachrichten ab, die ein Maximalgrößen-Limit überschreiten. Verhindert Speicher-Erschöpfung durch übergroße Payloads. 		Path-Traversal-Erkennung
Erkenne Directory-Traversal-Sequenzen in Nachrichten. Blockt Versuche, auf Dateien außerhalb des vorgesehenen Bereichs zuzugreifen.
Command-Injection-Erkennung
Erkenne OS-Command-Injection-Muster in Nachrichten. Blockt Shell-Metazeichen und gängige Befehls-Sequenzen. 		GeoIP-Länderfilterung
Erlaube oder blockiere Verbindungen anhand der geografischen Herkunft. Unterstützt Block- und Allowlist-Modi mit CSV-Datenbank-Lookup. 		Threat-Score-System
Sammle gewichtete Scores pro IP über alle Verstoßarten hinweg. Auto-Bann beim Erreichen einer Schwelle, mit automatischem Abbau über die Zeit.
Progressive Bann-Eskalation
Verlängere die Bann-Dauer mit jedem erneuten Verstoß. Steigere dich von kurzen Banns bis zu dauerhaften Sperren für hartnäckige Wiederholungstäter. 		WebSocket-Schutz
Validiere WebSocket-Origins, erzwinge Frame-Größenlimits und filtere Subprotokolle. Schutz auf Protokollebene jenseits des Nachrichteninhalts. 		Eigene Regel-Engine
Definiere eigene Firewall-Regeln mit Bedingungen und Aktionen. Lege Verstoß-Schwellen, Zeitfenster und automatisierte Reaktionen fest.

Schnellstart

Die Firewall in Betrieb zu nehmen, dauert nur drei Schritte: erstellen, konfigurieren, zuweisen.

var
  oFirewall: TsgcWSFirewall;
  oServer: TsgcWebSocketHTTPServer;
begin
  oFirewall := TsgcWSFirewall.Create(nil);
  oFirewall.Enabled := True;
  // Enable the modules you need
  oFirewall.Blacklist.Enabled := True;
  oFirewall.Blacklist.IPs.Add('10.0.0.0/8');
  oFirewall.RateLimit.Enabled := True;
  oFirewall.RateLimit.MaxConnectionsPerIP := 5;
  oFirewall.SQLInjection.Enabled := True;
  oFirewall.XSS.Enabled := True;
  // Assign to any server component
  oServer.Firewall := oFirewall;
  oServer.Active := True;
end;

Einmal zugewiesen, integriert sich die Firewall automatisch: Verbindungen werden geprüft, bevor sie deine Event-Handler erreichen, Nachrichten werden in Echtzeit gescannt, und getrennte Clients werden aus dem Tracking entfernt — alles ohne eine einzige Zeile Event-Handling-Code.

IP-Blacklist & -Whitelist

Die Blacklist weist Verbindungen von bestimmten IPs oder Bereichen ab. Die Whitelist macht das Gegenteil — sie definiert ein Set vertrauenswürdiger Adressen, die alle anderen Prüfungen, einschließlich der Nachrichtenfilterung, umgehen.

Beide unterstützen exakte IP-Adressen und CIDR-Notation für bereichsbasierte Filterung:

// Blacklist: block entire subnets and specific IPs
oFirewall.Blacklist.Enabled := True;
oFirewall.Blacklist.IPs.Add('10.0.0.0/8');        // All 10.x.x.x
oFirewall.Blacklist.IPs.Add('172.16.0.0/16');     // All 172.16.x.x
oFirewall.Blacklist.IPs.Add('192.168.1.100');     // Single IP
// Whitelist: trusted IPs bypass everything
oFirewall.Whitelist.Enabled := True;
oFirewall.Whitelist.IPs.Add('192.168.1.1');       // Admin machine
oFirewall.Whitelist.IPs.Add('192.168.1.0/24');    // Internal network

Priority. When the whitelist is enabled, it is checked first. If the IP matches, the connection is allowed immediately — blacklist, bans, rate limits, and message filters are all skipped.

Brute Force Protection

The brute force module tracks failed authentication attempts per IP using a sliding time window. When an IP exceeds the maximum number of attempts within the window, it is automatically banned for a configurable duration.

Eigenschaft Standard Beschreibung
MaxAttempts 5 Failed attempts before ban
TimeWindowSec 60 Sliding window in seconds for counting attempts
BanDurationSec 300 Ban duration in seconds (0 = permanent) 
// Ban after 3 failed logins within 60 seconds, for 10 minutes
oFirewall.BruteForce.Enabled := True;
oFirewall.BruteForce.MaxAttempts := 3;
oFirewall.BruteForce.TimeWindowSec := 60;
oFirewall.BruteForce.BanDurationSec := 600;
// Register failed attempts from your authentication handler
procedure TForm1.ServerAuthentication(Connection: TsgcWSConnection;
  aUser, aPassword: String; var Authenticated: Boolean);
begin
  Authenticated := ValidateCredentials(aUser, aPassword);
  if not Authenticated then
    oFirewall.RegisterFailedAttempt(Connection.IP);
end;

The firewall automatically handles the rest: it counts attempts, checks the time window, and bans the IP when the threshold is reached. Banned IPs are rejected at the connection level before any further processing.

Manual Ban Management

Beyond automatic bans, you can manage bans programmatically at any time:

// Ban an IP for 1 hour
oFirewall.BanIP('203.0.113.50', 3600);
// Permanent ban (duration = 0)
oFirewall.BanIP('198.51.100.10');
// Check ban status
if oFirewall.IsBanned('203.0.113.50') then
  WriteLn('IP is banned');
// Remove a specific ban
oFirewall.UnbanIP('203.0.113.50');
// Clear all bans
oFirewall.ClearBans;

SQL Injection Detection

The SQL injection module scans every incoming text message for common attack patterns. When a match is detected, the configurable action determines the response: block the client, log the event, or allow it through.

oFirewall.SQLInjection.Enabled := True;
oFirewall.SQLInjection.Action := faDeny;  // faDeny, faLog, or faAllow
// Add custom patterns beyond the built-in set
oFirewall.SQLInjection.CustomPatterns.Add('WAITFOR DELAY');
oFirewall.SQLInjection.CustomPatterns.Add('BENCHMARK(');

Built-in Patterns

The detector includes case-insensitive checks for the most common SQL injection techniques:

XSS Detection

The XSS module detects cross-site scripting payloads in WebSocket messages before they can reach your application logic or be relayed to other clients.

oFirewall.XSS.Enabled := True;
oFirewall.XSS.Action := faDeny;

Built-in detection covers:

Connection Rate Limiting

Limit the number of concurrent connections a single IP address can hold. This prevents resource exhaustion from clients that open excessive connections — whether malicious or misconfigured.

// Allow up to 5 concurrent connections per IP
oFirewall.RateLimit.Enabled := True;
oFirewall.RateLimit.MaxConnectionsPerIP := 5;
oFirewall.RateLimit.TimeWindowSec := 60;

Connection tracking is fully automatic: the firewall increments the counter on connect and decrements it on disconnect. When a new connection would exceed the limit, it is rejected before the server's OnConnect event fires.

Message Flood Protection

Throttle the number of messages a single IP can send per second. This protects against denial-of-service patterns where a client rapidly sends messages to overwhelm the server or other connected clients.

// Limit to 50 messages per second per IP
oFirewall.FloodProtection.Enabled := True;
oFirewall.FloodProtection.MaxMessagesPerSec := 50;
oFirewall.FloodProtection.Action := faDeny;  // Disconnect offender

Payload Size Limiting

Enforce a maximum message size to prevent clients from sending oversized payloads that could exhaust server memory. Messages exceeding the threshold are rejected before processing.

oFirewall.PayloadLimit.Enabled := True;
oFirewall.PayloadLimit.MaxSizeBytes := 65536;  // 64 KB max
oFirewall.PayloadLimit.Action := faDeny;

Path Traversal Detection

The path traversal module scans incoming messages for directory traversal sequences that attempt to access files outside the intended scope. This is critical for applications that process file paths or resource identifiers from client messages.

Built-in detection covers:

oFirewall.PathTraversal.Enabled := True;
oFirewall.PathTraversal.Action := faDeny;

Command Injection Detection

The command injection module detects OS command injection patterns in messages. It catches shell metacharacters and common command sequences used to execute arbitrary system commands.

Built-in detection covers:

oFirewall.CommandInjection.Enabled := True;
oFirewall.CommandInjection.Action := faDeny;

GeoIP Country Filtering

Filter connections based on their geographic origin using IP-to-country resolution. The GeoIP module supports two modes: BlockList (block specific countries, allow everything else) and AllowList (allow only specific countries, block everything else).

Eigenschaft Beschreibung
Mode gmBlockList or gmAllowList
Countries ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE)
DatabaseFile Path to CSV file for IP-to-country resolution

Block Specific Countries

oFirewall.GeoIP.Enabled := True;
oFirewall.GeoIP.Mode := gmBlockList;
oFirewall.GeoIP.Countries.Add('CN');
oFirewall.GeoIP.Countries.Add('RU');
oFirewall.LoadGeoIPDatabase('geoip.csv');

Allow Only Specific Countries

// Only allow connections from US, UK, and Germany
oFirewall.GeoIP.Enabled := True;
oFirewall.GeoIP.Mode := gmAllowList;
oFirewall.GeoIP.Countries.Add('US');
oFirewall.GeoIP.Countries.Add('GB');
oFirewall.GeoIP.Countries.Add('DE');
oFirewall.LoadGeoIPDatabase('geoip.csv');

GeoIP databases. Free IP-to-country CSV databases are available from providers like DB-IP and IP2Location. Alternatively, implement the OnResolveCountry event to use your own resolution logic.

Threat Score System

The threat score system assigns weighted points to each violation type and accumulates a score per IP address. When the score exceeds the auto-ban threshold, the IP is automatically banned. Scores decay over time, so one-off incidents do not result in permanent penalties.

Eigenschaft Standard Beschreibung
AutoBanThreshold 100 Score at which the IP is automatically banned
DecayPerHour 10 Points subtracted per hour of inactivity 
oFirewall.ThreatScore.Enabled := True;
oFirewall.ThreatScore.AutoBanThreshold := 80;
oFirewall.ThreatScore.DecayPerHour := 5;

Monitoring Score Changes

Use the OnThreatScoreChanged event to monitor scores in real time and take custom action before the auto-ban threshold is reached.

procedure TForm1.FirewallThreatScoreChanged(Sender: TObject;
  const aIP: string; const aOldScore, aNewScore: Integer);
begin
  if aNewScore >= 50 then
    LogToFile(Format('[%s] Threat score elevated: %d -> %d',
      [aIP, aOldScore, aNewScore]));
end;

Progressive Ban Escalation

Instead of a fixed ban duration, the escalation module increases the ban length with each repeated offense. First-time offenders get a short ban; persistent offenders are escalated up to a permanent block.

oFirewall.BanEscalation.Enabled := True;
oFirewall.BanEscalation.Levels.Add('300');    // 5 minutes
oFirewall.BanEscalation.Levels.Add('1800');   // 30 minutes
oFirewall.BanEscalation.Levels.Add('7200');   // 2 hours
oFirewall.BanEscalation.Levels.Add('86400');  // 24 hours
oFirewall.BanEscalation.Levels.Add('0');      // permanent

Tipp. Combine progressive escalation with the threat score system for maximum effectiveness. The threat score identifies bad actors across multiple violation types, and the escalation ensures repeat offenders face increasingly severe consequences.

WebSocket-Specific Protection

Beyond message-level scanning, the firewall provides protocol-level protections specific to WebSocket connections: origin validation, frame size enforcement, and subprotocol filtering.

// Validate the Origin header to prevent cross-site hijacking
oFirewall.WebSocket.Enabled := True;
oFirewall.WebSocket.AllowedOrigins.Add('https://www.example.com');
oFirewall.WebSocket.AllowedOrigins.Add('https://app.example.com');
// Enforce maximum frame size (bytes)
oFirewall.WebSocket.MaxFrameSize := 131072;  // 128 KB
// Only allow specific subprotocols
oFirewall.WebSocket.AllowedSubProtocols.Add('graphql-ws');
oFirewall.WebSocket.AllowedSubProtocols.Add('mqtt');

Custom Rules Engine

The custom rules engine lets you define your own firewall rules with conditions and automated actions. Each rule specifies a violation threshold within a time window, and the action to take when the threshold is exceeded.

Eigenschaft Beschreibung
Name Descriptive name for the rule
MinViolations Number of violations required to trigger the rule
TimeWindowSec Sliding window in seconds for counting violations
ActionType Action to take: raDeny, raAllow, raBan, or raLog
BanDurationSec Ban duration when ActionType is raBan

Action types:

Aktion Behavior
raDeny Disconnect the client immediately
raAllow No action (rule is tracked but not enforced)
raBan Ban the IP for the specified duration
raLog Fire the OnViolation event only 
var
  vRule: TsgcFirewallRuleItem;
begin
  oFirewall.CustomRules.Enabled := True;
  vRule := TsgcFirewallRuleItem(oFirewall.CustomRules.Rules.Add);
  vRule.Name := 'Block high-risk IPs';
  vRule.MinViolations := 5;
  vRule.TimeWindowSec := 300;
  vRule.ActionType := raBan;
  vRule.BanDurationSec := 3600;
end;

Real-time Statistics

The firewall exposes a Stats object with real-time counters for active connections, total blocked attempts, and per-violation-type counts. Use it to build monitoring dashboards or log periodic summaries.

WriteLn('Active: ', oFirewall.Stats.ActiveConnections);
WriteLn('Blocked: ', oFirewall.Stats.TotalBlocked);
WriteLn('SQL Injection: ', oFirewall.Stats.GetViolationCount(fvSQLInjection));

Persistent Bans

By default, bans are stored in memory and cleared on restart. Use SaveBansToFile and LoadBansFromFile to persist bans across server restarts.

// Save bans before shutdown
oFirewall.SaveBansToFile('bans.dat');
// Restore bans on startup
oFirewall.LoadBansFromFile('bans.dat');

Action Modes

The SQL injection, XSS, and flood protection modules support three configurable actions when a violation is detected:

Aktion Behavior Use Case
faDeny Block and disconnect the client Production servers
faLog Fire the OnViolation event but allow the connection Monitoring, testing, gradual rollout
faAllow No action Temporarily disable a module without removing config

Tipp. Start with faLog in production to observe how the firewall reacts to your real traffic before switching to faDeny. This avoids blocking legitimate users during the initial deployment.

Events — Logging & Overrides

Events give you full visibility into firewall decisions and the ability to override them when needed.

OnViolation — Security Logging

Fired on every detected violation. Use it to write security logs, send alerts, or feed a monitoring dashboard.

procedure TForm1.FirewallViolation(Sender: TObject;
  const aIP: string;
  const aViolationType: TsgcFirewallViolationType;
  const aDetails: string);
begin
  LogToFile(Format('[%s] Firewall: %s - %s',
    [aIP, ViolationTypeToStr(aViolationType), aDetails]));
end;

Violation types include:

Typ Triggered When
fvBlacklist IP is in the blacklist
fvBruteForce Failed attempt threshold exceeded
fvRateLimit Connection rate limit exceeded
fvFlood Message flood detected
fvSQLInjection SQL injection pattern detected
fvXSS XSS pattern detected
fvGeoIP Connection blocked by country filter
fvPathTraversal Path traversal pattern detected
fvCommandInjection Command injection pattern detected
fvPayloadSize Message exceeds maximum payload size
fvOrigin WebSocket origin not in allowed list
fvFrameSize WebSocket frame exceeds maximum size
fvThreatScore Threat score exceeded auto-ban threshold
fvCustomRule Custom rule threshold exceeded

OnFiltered — Override Decisions

Fired when a connection or message is about to be blocked. The Allow parameter lets you override the firewall's decision at runtime.

procedure TForm1.FirewallFiltered(Sender: TObject;
  const aIP: string; const aReason: string;
  var Allow: Boolean);
begin
  // Override: always allow the office IP even if rate-limited
  if aIP = '203.0.113.10' then
    Allow := True;
end;

OnResolveCountry — Custom GeoIP Resolution

Fired when the GeoIP module needs to resolve an IP address to a country code. Use this to implement your own resolution logic instead of (or in addition to) the built-in CSV database.

procedure TForm1.FirewallResolveCountry(Sender: TObject;
  const aIP: string; var aCountryCode: string);
begin
  aCountryCode := MyGeoIPLookup(aIP);
end;

OnThreatScoreChanged — Score Monitoring

Fired whenever an IP's threat score changes. Use this to implement custom thresholds, alerts, or graduated responses before the auto-ban threshold is reached.

procedure TForm1.FirewallThreatScoreChanged(Sender: TObject;
  const aIP: string; const aOldScore, aNewScore: Integer);
begin
  if aNewScore >= 50 then
    SendAlert(Format('IP %s threat score: %d', [aIP, aNewScore]));
end;

Server Integration

The firewall works with all three server components. A single firewall instance can even be shared across multiple servers.

Component Beschreibung
TsgcWebSocketHTTPServer WebSocket + HTTP server (Indy-based)
TsgcWebSocketServer Pure WebSocket server (Indy TCP)
TsgcWebSocketServer_HTTPAPI WebSocket server using HTTP.SYS kernel driver

Integration is automatic once assigned. The firewall intercepts at three points:

Complete Example

A fully configured WebSocket server with core protection modules and the new advanced features enabled.

uses
  sgcWebSocket_Server, sgcWebSocket_Server_Firewall;
var
  oFirewall: TsgcWSFirewall;
  oServer: TsgcWebSocketHTTPServer;
begin
  oFirewall := TsgcWSFirewall.Create(nil);
  oServer := TsgcWebSocketHTTPServer.Create(nil);
  Try
    // IP filtering
    oFirewall.Blacklist.Enabled := True;
    oFirewall.Blacklist.IPs.Add('10.0.0.0/8');
    oFirewall.Whitelist.Enabled := True;
    oFirewall.Whitelist.IPs.Add('192.168.1.0/24');
    // Brute force: ban after 3 failures in 60s, for 10 minutes
    oFirewall.BruteForce.Enabled := True;
    oFirewall.BruteForce.MaxAttempts := 3;
    oFirewall.BruteForce.BanDurationSec := 600;
    // Message security
    oFirewall.SQLInjection.Enabled := True;
    oFirewall.XSS.Enabled := True;
    // Rate limiting and flood protection
    oFirewall.RateLimit.Enabled := True;
    oFirewall.RateLimit.MaxConnectionsPerIP := 5;
    oFirewall.FloodProtection.Enabled := True;
    oFirewall.FloodProtection.MaxMessagesPerSec := 50;
    // Payload size limit
    oFirewall.PayloadLimit.Enabled := True;
    oFirewall.PayloadLimit.MaxSizeBytes := 65536;
    // GeoIP: block specific countries
    oFirewall.GeoIP.Enabled := True;
    oFirewall.GeoIP.Mode := gmBlockList;
    oFirewall.GeoIP.Countries.Add('CN');
    oFirewall.GeoIP.Countries.Add('RU');
    oFirewall.LoadGeoIPDatabase('geoip.csv');
    // Threat scoring with auto-ban
    oFirewall.ThreatScore.Enabled := True;
    oFirewall.ThreatScore.AutoBanThreshold := 80;
    oFirewall.ThreatScore.DecayPerHour := 5;
    // Progressive ban escalation
    oFirewall.BanEscalation.Enabled := True;
    oFirewall.BanEscalation.Levels.Add('300');
    oFirewall.BanEscalation.Levels.Add('3600');
    oFirewall.BanEscalation.Levels.Add('86400');
    oFirewall.BanEscalation.Levels.Add('0');
    // Restore persistent bans
    oFirewall.LoadBansFromFile('bans.dat');
    // Events
    oFirewall.OnViolation := FirewallViolation;
    oFirewall.OnFiltered := FirewallFiltered;
    oFirewall.OnThreatScoreChanged := FirewallThreatScoreChanged;
    // Assign to server and start
    oServer.Port := 443;
    oServer.Firewall := oFirewall;
    oServer.Active := True;
    WriteLn('Server running with firewall protection.');
    ReadLn;
    // Save bans before shutdown
    oFirewall.SaveBansToFile('bans.dat');
  Finally
    oServer.Active := False;
    oServer.Free;
    oFirewall.Free;
  End;
end;

Thread Safety

The firewall component is fully thread-safe. All public methods use internal critical sections to protect concurrent access to tracking data. It has been stress-tested with 20 concurrent threads performing 100,000 operations with zero errors and zero memory leaks.

The component can safely be shared across multiple server instances and accessed from any thread — server event handlers, timer threads, background workers — without external synchronization.

Important Notes