---
title: CrispyCMS Ray
description: Bot-Schutz und Zugangskontrolle für Ihre Website — ohne technisches Vorwissen.
navIcon: "🛡️"
---

import { Badge } from "@/components/ui/badge"
import { Icon } from "@/components/ui/icon"

CrispyCMS Ray ist der integrierte Schutzschild Ihrer Website. Er erkennt automatisierte Anfragen, blockiert unerwünschten Traffic und entscheidet, wer Ihre Inhalte sehen darf — bevor eine Seite überhaupt geladen wird.

Stellen Sie sich Ray wie einen Türsteher vor: Er prüft jeden Besucher anhand Ihrer Regeln, lässt bekannte Gäste ohne Wartezeit durch, schickt unbekannte Besucher zum kurzen Check und verweigert ungebetenen Gästen den Zutritt komplett.

---

## Voraussetzungen

Bevor Sie Ray aktivieren können, müssen folgende Bedingungen erfüllt sein:

- **Professional Edition oder höher** — Ray ist ausschließlich in der Professional Edition verfügbar. In kleineren Editionen ist die Funktion nicht sichtbar.
- **CAPTCHA-HMAC-Schlüssel hinterlegt** — Ray nutzt das Altcha-Captcha-System für die Besucherprüfung. Ohne einen konfigurierten HMAC-Schlüssel bleibt Ray deaktiviert, auch wenn es eingeschaltet ist. Den Schlüssel tragen Sie unter **Einstellungen → Sicherheit → Captcha-Einstellungen** ein. Weitere Informationen dazu finden Sie im Kapitel [Captcha-Sicherheit](/docs/verwaltung/captcha).
- **HTTPS** — Die Captcha-Prüfung funktioniert nur auf HTTPS-gesicherten Seiten. Stellen Sie sicher, dass Ihre Website über ein gültiges SSL-Zertifikat erreichbar ist.

> ⚠️ **Lizenzlimit beachten:** Jede erfolgreich abgeschlossene Captcha-Prüfung zählt zum Captcha-Kontingent Ihrer Lizenz. Beobachten Sie den Verbrauch im Administrationsbereich unter **Lizenzen**, um ein unerwartetes Deaktivieren zu vermeiden. Details zu Limits finden Sie im Kapitel [Lizenzierung & Kontingente](/docs/verwaltung/lizenzen).

---

## Aktivierung und Grundkonfiguration

Die Ray-Einstellungen finden Sie unter **Einstellungen → Ray**.

| Einstellung | Beschreibung |
| :--- | :--- |
| **CrispyCMS Ray aktivieren** | Schaltet den Schutzschild ein oder aus. |
| **Token-Laufzeit (Sekunden)** | Wie lange ein Besucher nach bestandener Prüfung ungestört surfen darf, bevor er erneut geprüft wird. Standard: 86.400 Sekunden (24 Stunden). |
| **Standard-Aktion** | Was passiert, wenn keine Ihrer Regeln auf einen Besucher zutrifft. Siehe [Standard-Aktion](#standard-aktion). |

---

## Wichtig: Der Admin-Bereich ist nicht geschützt

> ⚠️ **Kritischer Hinweis:** CrispyCMS Ray schützt **ausschließlich den öffentlichen Bereich** Ihrer Website. Der Administrationsbereich unter `/admin` ist von Ray **ausgenommen** und wird nie blockiert oder mit einer Captcha-Prüfung versehen — unabhängig von Ihren Regeleinstellungen.

Dies ist gewollt: Würde Ray den Admin-Bereich sperren, könnten Sie sich selbst ausperren. Es bedeutet aber auch, dass `/admin` durch andere Maßnahmen abgesichert werden sollte, wenn Sie hohe Sicherheitsanforderungen haben:

- **Webserver-Ebene:** IP-Beschränkungen über nginx, Apache oder Ihren Loadbalancer
- **Cloudflare / CDN:** Zugangsbeschränkungen per WAF-Regel oder Zero Trust Tunnel
- **VPN:** Zugriff auf `/admin` nur aus dem Unternehmensnetzwerk erlauben
- **HTTP Basic Auth:** Zusätzliche Passwortabfrage auf Webserver-Ebene

---

## Standard-Aktion

Die Standard-Aktion bestimmt, was mit Besuchern passiert, die auf **keine** Ihrer aktiven Regeln zutreffen. Sie können zwischen drei Verhaltensweisen wählen:

| Aktion | Symbol | Bedeutung |
| :--- | :---: | :--- |
| **Erlauben** | ✅ | Alle Besucher ohne passende Regel dürfen die Seite frei aufrufen. Regeln werden nur genutzt, um gezielt Traffic zu blockieren oder zu prüfen. |
| **Challenge** | 🛡️ | Alle Besucher ohne passende Regel müssen die Captcha-Prüfung bestehen. Wer besteht, erhält ein Token und wird für die konfigurierte Laufzeit nicht erneut geprüft. |
| **Verweigern** | 🚫 | Alle Besucher ohne passende Regel werden mit einem Fehler 403 abgewiesen. Nur Besucher, auf die eine **Erlauben**-Regel zutrifft, kommen durch. |

**Empfehlungen je nach Anwendungsfall:**

- **Öffentliche Website mit Spam-Problem:** Standard-Aktion „Challenge" — alle Besucher werden kurz geprüft, echte Nutzer merken davon kaum etwas.
- **Interne Seite / geschützter Bereich:** Standard-Aktion „Verweigern" — nur explizit freigegebene IPs oder Netzwerke (via Erlauben-Regeln) kommen durch.
- **Leichte Absicherung ohne Unterbrechung:** Standard-Aktion „Erlauben" — Ray greift nur bei Regeln ein, der Rest läuft ungehindert.

![Standard-Aktion Einstellungen in der Regel-Engine](../assets/img/ray/1.png)

---

## Firewall-Regeln

Regeln sind das Herzstück von Ray. Jede Regel definiert, **wen** Sie erkennen und **was** dann passiert. Regeln werden unter **Einstellungen → Ray → Regeln verwalten** konfiguriert.

![Firewall-Regeln Einstellungen](../assets/img/ray/2.png)

### Regelauswertung und Priorität

Regeln werden in der festgelegten **Priorität** von oben nach unten geprüft — die erste passende Regel gewinnt, weitere werden nicht mehr ausgewertet. Die Priorität können Sie beim Anlegen einer Regel festlegen: niedrigere Zahl = höhere Priorität.

**Beispiel:** Priorität 1 (Erlauben, Ihre Büro-IP) + Priorität 10 (Verweigern, bekannte Scan-IPs) → Ihr Büro kommt immer durch, Bots werden blockiert.


![Regelauswertung und Priorität](../assets/img/ray/3.png)

### Regelaktionen

Jede Regel hat genau eine Aktion:

| Aktion | Was passiert bei einem Treffer |
| :--- | :--- |
| **Erlauben** | Besucher wird sofort durchgelassen. Keine weiteren Regeln werden geprüft. Ideal für Whitelists (eigene IPs, bekannte Dienste). |
| **Challenge** | Besucher bekommt die Captcha-Seite angezeigt. Wer besteht, erhält ein Token. |
| **Verweigern** | Besucher wird mit HTTP 403 blockiert. Kein Captcha, kein Zugriff. |


![Regelaktionen](../assets/img/ray/4.png)

### Regeltypen

Jede Regel prüft ein bestimmtes Merkmal des Besuchers:

| Typ | Was wird geprüft | Beispielwerte |
| :--- | :--- | :--- |
| **IP-Adresse** | Die IP-Adresse des Besuchers | `1.2.3.4`, `192.168.1.0/24` |
| **User-Agent** | Kennung des Browsers oder Programms | `curl/8`, `Googlebot` |
| **Pfad** | Die aufgerufene URL-Adresse | `/wp-login.php`, `/admin` |
| **HTTP-Header** | Beliebiger HTTP-Header-Wert | `X-Forwarded-For`, `Referer` |
| **HTTP-Methode** | Anfragemethode | `GET`, `POST`, `DELETE` |
| **GeoIP Land** | Herkunftsland (ISO-Code) | `DE`, `US`, `RU` |
| **GeoIP Kontinent** | Herkunftskontinent (Code) | `EU`, `NA`, `AS` |
| **GeoIP ASN** | Autonomes System / Anbieter | `AS15169` (Google), `AS32934` (Meta) |


![Regeltypen](../assets/img/ray/5.png)

### Vergleichsoperatoren

Mit dem Operator legen Sie fest, wie der Wert verglichen wird:

| Operator | Bedeutung |
| :--- | :--- |
| **Gleich** | Exakte Übereinstimmung |
| **Ungleich** | Trifft zu, wenn der Wert *nicht* übereinstimmt |
| **Enthält** | Wert muss im Text vorkommen |
| **Enthält nicht** | Wert darf nicht im Text vorkommen |
| **Beginnt mit** | Text beginnt mit diesem Wert |
| **Endet mit** | Text endet mit diesem Wert |
| **Regex** | Regulärer Ausdruck (für Fortgeschrittene) |
| **In Liste** | Wert muss in einer kommaseparierten Liste vorkommen |


![Vergleichsoperatoren](../assets/img/ray/7.png)

### IP-Bereiche und Listen

Beim Regeltyp **IP-Adresse** haben Sie zusätzliche Möglichkeiten:

- **Einzelne IP:** `1.2.3.4`
- **IP-Bereich (CIDR-Notation):** `192.168.0.0/24` — deckt alle Adressen von `192.168.0.0` bis `192.168.0.255` ab. Der Operator wird in diesem Fall ignoriert, der Bereichsabgleich erfolgt automatisch.
- **Kommaliste:** `1.2.3.4, 5.6.7.8, 10.0.0.0/8` — mehrere Adressen oder Bereiche, getrennt durch Komma. Der Besucher trifft die Regel, wenn er mit **einem** der Einträge übereinstimmt.
- **„Ungleich" mit Liste/Bereich:** Kehrt das Ergebnis um — der Besucher trifft die Regel, wenn er in **keinem** der Einträge enthalten ist.

---

## Regelbibliothek

Unter **Regeln verwalten → Regelbibliothek** finden Sie vorgefertigte Regelsets, die Sie mit einem Klick importieren können. Die Bibliothek enthält unter anderem:

- **Bekannte Bad Bots** — KI-Crawler, die Ihre Inhalte ohne Erlaubnis verwenden, sowie aggressive SEO-Bots
- **Sicherheits-Scanner** — Automatisierte Schwachstellenscanner und Pentesting-Tools
- **Angriffspfade** — Häufig angefragte Pfade, die auf WordPress-, Admin- oder Konfigurationsdateien zielen

Beim Import werden bestehende Regeln mit gleichem Namen automatisch aktualisiert, keine Duplikate entstehen.


![Vergleichsoperatoren](../assets/img/ray/6.png)
---

## Token und Wiedererkennungszeit

Hat ein Besucher die Captcha-Prüfung einmal bestanden, erhält er ein **Token** in Form eines Cookies. Für die in den Einstellungen festgelegte Laufzeit (Standard: 24 Stunden) wird er nicht erneut geprüft — auch wenn er die Seite mehrfach aufruft oder verschiedene Unterseiten besucht.

Das Token ist an den Browser gebunden. Ein Besucher, der die Seite in einem anderen Browser oder auf einem anderen Gerät aufruft, muss die Prüfung erneut absolvieren.

---

## Typische Konfigurationen

### Öffentliche Website absichern

Geeignet für Blogs, Unternehmenswebseiten und Shops, die Spam und Bot-Crawling reduzieren möchten:

1. Standard-Aktion: **Challenge**
2. Regelbibliothek „Bad Bots" importieren → bekannte KI-Crawler werden direkt **verweigert**
3. Eigene Büro-IP (oder IP-Bereich des Unternehmens) als **Erlauben**-Regel mit Priorität 1 anlegen → Mitarbeiter werden nie gestört

### Internen Bereich schützen

Geeignet für Staging-Umgebungen, Kundenbereiche oder interne Tools:

1. Standard-Aktion: **Verweigern**
2. Erlauben-Regeln für bekannte IP-Adressen oder Netzwerke mit Priorität 1–5 anlegen
3. Alle anderen Besucher erhalten automatisch einen 403-Fehler

### Nur Angreifer blockieren, Besucher nicht stören

Geeignet, wenn Sie nur gezielt bekannte Bedrohungen stoppen möchten:

1. Standard-Aktion: **Erlauben**
2. Regelbibliothek „Angriffspfade" importieren → Angriffs-URLs werden **verweigert**
3. Regelbibliothek „Sicherheits-Scanner" importieren → Scanner werden **verweigert**
4. Normaler Besucher-Traffic läuft ungehindert durch

---

## Hinweise und häufige Fragen

**Sieht der normale Besucher das Captcha?**
Bei der Standard-Aktion „Challenge" erscheint eine kurze Prüfseite beim ersten Besuch. Die Altcha-Prüfung läuft im Hintergrund ab und ist für echte Besucher in der Regel innerhalb von Sekunden abgeschlossen — ohne Bilderrätsel oder manuelle Eingabe. Danach ist der Besucher für die Token-Laufzeit nicht mehr gestört.

**Was passiert, wenn das Captcha-Kontingent aufgebraucht ist?**
Ray deaktiviert sich automatisch und alle Besucher kommen ohne Prüfung durch, bis das Kontingent zurückgesetzt wird. Beobachten Sie den Verbrauch regelmäßig unter **Lizenzen**.

**Kann ich Ray testen, ohne mich selbst zu sperren?**
Ja — legen Sie vor dem Aktivieren einer restriktiven Standard-Aktion zunächst eine **Erlauben**-Regel mit Ihrer eigenen IP-Adresse und Priorität 1 an. So kommen Sie immer durch, egal was andere Regeln sagen.

**Was ist ein ASN?**
Ein ASN (Autonomous System Number) ist eine eindeutige Nummer, die einem Internet-Anbieter oder einer Organisation zugewiesen ist. Cloudflare hat z.B. ASN `AS13335`, Google `AS15169`. Damit können Sie ganze Anbieternetze in einer einzigen Regel blockieren oder freigeben.

**Werden assets wie Bilder, CSS oder JavaScript von Ray geschützt?**
Nein — Ray prüft nur Anfragen, die auf CMS Seiten zielen. Das bedeutet, dass Bots zwar die Seite nicht sehen, aber trotzdem die Ressourcen laden können. Um auch diese Anfragen zu schützen, müssten Sie zusätzliche Regeln auf Webserver-Ebene oder über Ihr CDN konfigurieren.