abuse-guard: Automatisches Sperren missbräuchlicher Clients basierend auf der Fehlerantwortquote (404/403/5xx)

Erfordert den Pro-Plan (oder höher) des GetPageSpeed NGINX Extras-Abonnements.

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

• RedHat Enterprise Linux 7, 8, 9 und 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 und Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 und Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-abuse-guard

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-abuse-guard

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_abuse_guard_module.so;

Dieses Dokument beschreibt nginx-module-abuse-guard v1.1.0, veröffentlicht am 09. Juli 2026.

---

Ihr Fehlerprotokoll ist ein Geständnis. Abuse Guard liest es in Echtzeit und schließt Missbrauchstäter aus.

Jeder Scanner, Fuzzer und Credential-Stuffing-Bot hinterlässt denselben Fingerabdruck: ein Spray von 404s, das nach versteckten Pfaden sucht, 403s, die an verschlossenen Türen rütteln, fehlgeschlagene Anfragen nach fehlgeschlagenen Anfragen. Abuse Guard überwacht die Statuscodes, die Ihr Server tatsächlich zurückgibt, identifiziert die Clients, deren Verkehr hauptsächlich aus Fehlern besteht, und sperrt sie — entschieden innerhalb des NGINX-Workers, bei der Anfrage selbst, in wenigen Mikrosekunden. Kein Sidecar. Kein Log-Ship. Keine Skriptschicht. Nur kompiliertes C, das eine Aufgabe außergewöhnlich gut erledigt.

Spezifikationsblatt

Auslöser	Per-Client-Rate der Fehlerantworten, die Sie wählen (403/404 standardmäßig)
Aktion	Zeitlich begrenzte Sperre — ein harter Bann für ein festes Zeitfenster, kein Drosseln
Entscheidungspunkt	NGINX-Vorzugangsphase, bevor ein Handler oder Upstream ausgeführt wird
Speichermodell	Feste Bytes pro Client, unabhängig von der Schwelle → botnet-skalierbar
Flottenmodus	Optionale Bann-Replikation über Knoten hinweg via Redis / Valkey
Haltbarkeit	Optionale On-Disk-Bann-Snapshots, die Reloads und Neustarts überstehen
Fußabdruck	Ein eigenständiges Modul; standardmäßig null Laufzeitabhängigkeiten
Plattformen	RHEL / AlmaLinux / Rocky / CentOS Stream / Oracle / Amazon Linux

Das Problem, das es löst

Legitime Besucher erzeugen fast nie einen Ausbruch von Fehlern. Missbrauchstäter erzeugen kaum etwas anderes — diese Asymmetrie ist das ganze Spiel. Ein Schwachstellenscanner, der Ihren Baum durchläuft, ist eine Wand aus 404s. Ein Bot, der Admin-Endpunkte ansticht, ist eine Wand aus 403s. Ein Brute-Force-Angriff ist eine Wand aus Fehlern.

Ratenbegrenzer behandeln diesen Verkehr wie jeden anderen: Sie verlangsamen alle nach Anfragevolumen und lassen den Täter sofort wieder rein, sobald es nachlässt. Abuse Guard macht das Gegenteil. Es ignoriert gutartigem Verkehr vollständig und reserviert seine eine Antwort — einen echten, zeitlich begrenzten Bann — für Clients, die durch ihre Fehler definiert sind.

Verwenden Sie einen Ratenbegrenzer, um die Last zu steuern. Verwenden Sie Abuse Guard, um Missbrauch zu vertreiben.

Wie ein Bann entschieden wird

Drei bewegliche Teile, alle innerhalb des Workers:

1 · Ein undichter Score, pro Client. Jede Client-Identität trägt eine einzige kleine Zahl im gemeinsamen Speicher. Jeder übereinstimmende Fehler erhöht ihn; der Score sinkt kontinuierlich mit threshold ÷ interval pro Sekunde. Ein kurzer, scharfer Ausbruch bringt ihn über die Linie; ein langsames Rinnsal tut dies nie. Entscheidend ist, dass dieser Score ein festes Datensatzformat hat, egal wie hoch Sie die Schwelle setzen — sodass eine einzige Zone bequem die Zehntausenden von unterschiedlichen Quelladressen verfolgt, die ein Botnetz auf Sie wirft.

2 · Eine harte Frist. In dem Moment, in dem der Score Ihre Schwelle überschreitet, erhält der Client einen blocked_until Zeitstempel. Bis dahin ist er einfach verschwunden — jede Anfrage wird in der Vorzugangsphase abgelehnt, bevor NGINX einen Zyklus für Routing, Dateien oder Upstreams aufwendet. Die Ablehnung ist das kostengünstigste Ergebnis.

3 · Eine datenschutzkonforme Ablehnung. Gesperrte Clients erhalten 429 Too Many Requests (Ihr gewählter Code), so dass kein gemeinsamer Cache jemals speichern kann, und die Bestrafung eines Clients einem anderen serviert wird, mit einem Retry-After, der ehrlichen Clients sagt, wann sie zurückkehren sollen.

Identitäten werden in einen festgelegten Digest gefaltet, sodass das Keying auf etwas Großes wie $request_uri oder einen Header genau so viel Speicher kostet wie das Keying auf eine IP.

In weniger als einer Minute einsatzbereit

Abuse Guard wird als vorcompiliertes, signiertes Modul aus dem GetPageSpeed-Repository geliefert — einfach einfügen, kein Build-Toolchain erforderlich.

sudo yum -y install https://extras.getpagespeed.com/release-latest.rpm
sudo yum -y install nginx-module-abuse-guard

Verbinden Sie es:

load_module modules/ngx_http_abuse_guard_module.so;

http {
    abuse_guard_zone zone=clients:10m;     # eine gemeinsame Speicherzone

    server {
        location / {
            abuse_guard zone=clients;      # hier durchsetzen
        }
    }
}

sudo nginx -t && sudo systemctl reload nginx

Diese Standardeinstellungen sperren jede IP, die 100 403/404 Antworten innerhalb eines 5-Minuten-Fensters zurückgibt, für eine Stunde. Straffen oder lockern Sie jede Zahl unten.

Konfiguration

Abuse Guard besteht aus vier Direktiven. Die erste erklärt eine Richtlinie; die restlichen wenden sie an, befreien Personen davon und (optional) teilen sie über Maschinen hinweg.

Eine Richtlinie erklären — abuse_guard_zone

Eine http-Ebene Direktive. Sie schneidet eine gemeinsame Speicherzone aus und legt die Richtlinie fest, die sie regiert. Stellen Sie so viele oder so wenige Regler ein, wie Sie möchten — der Name und die Größe der Zone sind das einzige, was Sie angeben müssen; sinnvolle Standardwerte füllen den Rest aus (die unten gezeigten Werte sind genau diese Standardwerte).

abuse_guard_zone  zone=clients:10m            ← Name + Größe (das einzige Muss)
                  key=$binary_remote_addr     ← wer ist "ein Client"
                  statuses=403,404            ← welche Antworten als Fehler zählen
                  interval=300s               ← das Bewertungsfenster
                  threshold=100               ← Fehler in diesem Fenster → Bann
                  block=60m;                  ← wie lange der Bann hält

zone=clients:10m ist die Identität und das Budget der Richtlinie: ein Name, den Sie von abuse_guard referenzieren, und die Größe des gemeinsamen Speichers. Etwa 10 MB verfolgen in der Größenordnung von hunderttausend aktiven Clients.

Alles andere ist optionale Feinabstimmung:

• key — der Ausdruck, der einen einzelnen Client definiert. Jede NGINX-Variable; der Standard $binary_remote_addr schlüsselt auf die Quell-IP. Eine Anfrage, deren Schlüssel leer herauskommt, wird vollständig übersprungen (praktisch mit einer map, siehe unten).
• statuses — die Antwortcodes, die als Fehler zählen: einzelne Codes, Bereiche oder eine Mischung, z.B. statuses=401,403,404,500-599. Standardmäßig 403,404.
• interval — das Fenster, über das der Score abnimmt (Standard 300s). Ein Ausbruch innerhalb dieses Fensters löst einen Bann aus; ein langsames Rinnsal, das sich weiter ausbreitet, sammelt nie.
• threshold — wie viele Fehler innerhalb dieses Fensters die Linie überschreiten, bis zu 1024 (Standard 100).
• block — wie lange ein gesperrter Client ausgesperrt bleibt (Standard 60m).
• inactive — wie lange ein inaktiver Client im Speicher verweilt, bevor er zurückgefordert wird (Standard max(1h, interval, block); jeder explizite Wert muss mindestens so groß sein wie sowohl interval als auch block).
• redis — on, um die Banns dieser Zone über eine Flotte zu replizieren (siehe unten); standardmäßig off.
• persist — ein Dateipfad, um Banns zu snapshotten, damit sie einen Neustart überstehen.
• persist_interval — wie oft dieser Snapshot neu geschrieben wird (Standard 5s).
• persist_secret — ein hexadezimaler Schlüssel, der den Snapshot mit HMAC-SHA256 signiert, sodass eine manipulierte Datei abgelehnt wird, anstatt geladen zu werden.

Warum 5xx standardmäßig ausgeschlossen ist: Ein Serverfehler ist normalerweise Ihr Fehler, und ihn zu zählen würde es einem fehlerhaften Backend ermöglichen, unschuldige Besucher zu sperren. Fügen Sie statuses=403,404,500-599 nur hinzu, wenn Sie absichtlich auf Clients reagieren möchten, die Serverfehler auslösen.

Anwenden — abuse_guard

Gültig in http, server und location Blöcken, sodass Sie eine gesamte Website oder nur die Endpunkte schützen können, die Missbrauch anziehen. Nennen Sie die Zone, um sie zu aktivieren; schreiben Sie abuse_guard off; in einem verschachtelten Bereich, um sie wieder auszuschalten.

location /wp-login.php {
    abuse_guard zone=clients status=429 log_level=warn;
}

• zone — die Zone (oben erklärt), deren Richtlinie hier gilt.
• status — der Code, den ein gesperrter Client erhält, irgendwo in 400–599 (Standard 429).
• dry_run — on, um zu beobachten, ohne durchzusetzen: das Urteil wird protokolliert, aber kein Bann wird geschrieben. Standardmäßig aus.
• log_level — wie laut jede Entscheidung protokolliert wird: info, notice (Standard), warn oder error.

Führen Sie ohne Angst mit dry_run=on ein. Es protokolliert jeden Bann, den es ausgeben würde, ohne den Status zu berühren, sodass Sie Schwellenwerte gegen den Live-Verkehr kalibrieren können — sogar neben einem durchsetzenden Standort in derselben Zone — und dann live umschalten.

Die Guten ausnehmen — abuse_guard_allow

Kontext: http · server · location · wiederholbar, nach unten vererbt.

abuse_guard_allow 127.0.0.0/8;
abuse_guard_allow 10.0.0.0/8 192.168.0.0/16;

Aufgelistete Clients werden niemals gezählt und niemals gesperrt. Die Übereinstimmung erfolgt anhand der tatsächlichen Verbindungsadresse, sodass sie mit realip kooperiert. So schützen Sie auch verifizierte Suchcrawler: Erlauben Sie die veröffentlichten Googlebot / Bingbot-Bereiche, sodass ein Bot, der durch veraltete URLs mahlt (und 404s anhäuft), niemals erwischt wird.

Banns über die Flotte teilen — abuse_guard_redis

Kontext: http

abuse_guard_redis host=10.0.0.5 password=… ;   # tls://host für TLS
abuse_guard_zone  zone=clients:10m redis=on;

Richten Sie jeden Knoten auf einen Redis oder Valkey aus, aktivieren Sie redis=on, und ein Bann, der auf einer Maschine verdient wurde, wird auf alle propagiert. Standardwerte: port=6379, db=0, prefix=ag_, timeout=100ms. Wie es schnell bleibt, ist der nächste Abschnitt.

SELinux: Auf durchsetzenden Systemen (RHEL, Rocky, AlmaLinux) verhindert der Kernel, dass NGINX die Verbindung zu Redis öffnet, bis Sie es einmal erlauben — setsebool -P httpd_can_network_connect 1. Überspringen Sie dies und die Replikation tut stillschweigend nichts, während die lokale Durchsetzung normal weitergeht.

Ein Bann, jeder Knoten — ohne eine einzige Anfrage zu verlangsamen

Hinter einem Lastenausgleich ist ein serverbasierter Bann Theater: Der Angreifer landet einfach auf einem anderen Knoten. Abuse Guard schließt diese Lücke ohne Redis jemals in den Anfragepfad zu bringen.

Jeder Knoten entscheidet lokal und zählt lokal. In dem Moment, in dem er einen Bann ausgibt, sendet er diese eine Tatsache an den Cluster und zeichnet eine dauerhafte Kopie auf. Jeder andere Knoten importiert sie innerhalb von Millisekunden, und jeder Knoten, der offline war, gleicht den Moment aus, in dem er sich wieder verbindet. Da die Durchsetzung immer aus dem eigenen In-Memory-Zustand jedes Knotens erfolgt, wartet die Anfrage eines Besuchers niemals auf eine Netzwerk-Round-Trip — die einzige Kostenstelle der Clusterbildung ist, dass ein frisch gesperrter Angreifer flächendeckend einen Herzschlag später ausgesperrt wird, anstatt sofort.

Redis ist hier eine einseitige Alarmglocke, kein gemeinsames Hauptbuch, das pro Anfrage konsultiert wird — sodass ein langsamer oder fehlender Redis niemals Latenz zu Ihrem Verkehr hinzufügen kann. Führen Sie es in einem privaten Netzwerk aus und behandeln Sie es als privilegiert: Alles, was darauf schreiben kann, kann Banns ausgeben.

Banns, die einen Neustart überstehen

Richten Sie eine Zone auf eine Datei aus, und aktive Banns werden in einem Intervall snapshotiert und beim Start wiederhergestellt, sodass ein Reload oder ein Neustart jedem Angreifer kein frisches Blatt übergibt.

abuse_guard_zone zone=clients:10m
                 persist=/var/lib/nginx/abuse_guard/clients.state
                 persist_secret=00112233445566778899aabbccddeeff;

Der Snapshot wird auf Integrität überprüft, so geschrieben, dass ein Absturz niemals eine beschädigte Datei hinterlässt, und — mit persist_secret — kryptografisch signiert, sodass eine manipulierte Datei abgelehnt wird, anstatt vertraut zu werden. Halten Sie das Verzeichnis nur für den Worker-Benutzer lesbar.

Sehen Sie alles, was es entscheidet

Drei Variablen geben das Urteil von Abuse Guard in Ihre Protokolle und Konfigurationen aus:

Variable	Wert
$abuse_guard_status	BYPASSED · PASSED · COUNTED · BLOCKED · DRY_RUN
$abuse_guard_count	Fehler, die derzeit diesem Client zugeordnet sind.
$abuse_guard_blocked_until	Unix-Zeit, zu der der Bann aufgehoben wird, oder 0.

log_format guard '$remote_addr "$request" $status '
                 'guard=$abuse_guard_status count=$abuse_guard_count';

Hinter einem CDN oder Proxy keyen? Vertrauen Sie niemals einem rohen X-Forwarded-For. Lassen Sie realip zuerst den echten Client auflösen, und keyen Sie dann auf $binary_remote_addr:

set_real_ip_from 10.0.0.0/8;
real_ip_header   X-Forwarded-For;
real_ip_recursive on;

Benötigen Sie eine Logik zur Ausnahmeregelung pro Anfrage? Jede Anfrage, deren key auf eine leere Zeichenfolge aufgelöst wird, wird ignoriert — sodass eine map es Ihnen ermöglicht, beispielsweise anonyme Besucher nach IP zu verfolgen, während authentifizierte Benutzer unberührt bleiben.

Für den Einsatz in der Produktion vertrauenswürdig gestaltet

Abuse Guard wird an einen Standard gehalten, der weit über "es kompiliert" hinausgeht. Jede Änderung durchläuft die Prüfung von AddressSanitizer, UndefinedBehaviorSanitizer, Valgrind, statischer Analyse und kontinuierlichem Fuzzing seiner Parser und des On-Disk-Formats. Seine optionalen Abhängigkeiten — Clustering und signierte Snapshots — sind absichtlich nach bestem Bemühen: Wenn Redis oder die Festplatte fehlerhaft sind, wird die Durchsetzung stillschweigend aus dem lokalen Speicher fortgesetzt. Ihr Verkehr wird niemals von einer Abhängigkeit als Geisel gehalten.

Holen Sie sich Abuse Guard

Abuse Guard ist ein kommerzielles NGINX-Modul von GetPageSpeed LLC, das mit fortlaufenden Updates und Support über ein GetPageSpeed-Abonnement geliefert wird.

• Durchsuchen Sie den vollständigen NGINX-Modulkatalog → https://nginx-extras.getpagespeed.com/modules/
• Lizenzierung, Volumeneinsätze oder Unterstützung bei der Einrichtung → getpagespeed.com/contact-us

© GetPageSpeed LLC. Alle Rechte vorbehalten.