Installation für Agenturen

Diese Anleitung richtet sich ausschließlich an Agenturen und technische Shop-Administratoren mit Datei-, Composer- und Konsolenzugriff. Die tägliche Konfiguration im OXID-Admin ist unter Bedienung für Shop-Betreiber beschrieben.

Paket passend zur OXID-Hauptversion wählen

Verwenden Sie ausschließlich das zur Shop-Hauptversion gehörende Paket:

Paketauswahl
Shop	Ausgabe	Ziel
OXID eShop 7 ab 7.1	Twig	`vendor/ecs/botprotection`
OXID eShop 6 ab 6.1	Smarty	`source/modules/ecs/BotProtection`

Warnung

Die OXID-6- und OXID-7-Pakete sind nicht austauschbar. Sichern Sie vor Installation und Update mindestens die Projekt-composer.json, die OXID-Konfiguration und das vollständige Logverzeichnis. Bei einem Update zusätzlich den vorhandenen Modulordner und log/botprotection sichern.

Voraussetzungen

Prüfen Sie vor dem Kopieren des Moduls:

Schreibzugriff des Webserver-Benutzers auf das von OXID konfigurierte Logverzeichnis. Dort wird botprotection/ angelegt.
PHP-Erweiterung pdo_sqlite für Webserver beziehungsweise PHP-FPM. Unter Debian/Ubuntu wird sie üblicherweise über das zur PHP-Version passende Paket php-sqlite3 bereitgestellt. Starten Sie PHP-FPM oder den Webserver nach der Aktivierung der Erweiterung neu.
pdo_sqlite auch für das CLI-PHP, wenn die Analyse- und Bereinigungsskripte verwendet werden sollen.
PHP-cURL und ausgehenden HTTPS-Zugriff auf GitHub, wenn die lokale GeoIP-Datenbank im Dashboard aktualisiert werden soll. Der Storefront-Betrieb selbst benötigt diesen Netzwerkzugriff nicht.
Eine funktionierende PHP-Mailkonfiguration, falls E-Mail-Alarme gewünscht sind. Das Modul verwendet die PHP-Funktion mail() und keine eigene SMTP-Konfiguration.
Ausreichend freien Speicher für SQLite-Datenbank, WAL-Datei und temporäre GeoIP-Downloads. Der Standardwert der Modulbegrenzung beträgt 200 MB; ein GeoIP-Update lädt zusätzlich IPv4- und IPv6-Quelldaten temporär herunter.

Achtung

Das Modul wertet REMOTE_ADDR aus. Hinter CDN, Loadbalancer oder Reverse Proxy muss die Serverkonfiguration diese Variable bereits sicher auf die tatsächliche Besucher-IP setzen. Andernfalls zählt und sperrt das Modul die Proxy-Adresse. Vertrauen Sie weitergereichten Headern nur von bekannten Proxys und testen Sie die Konfiguration vor der Aktivierung.

OXID 7 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Twig-Paket nach:

vendor/ecs/botprotection

Prüfen Sie danach insbesondere metadata.php, composer.json, src und die Twig-, Admin- beziehungsweise View-Verzeichnisse des ausgelieferten OXID-7-Pakets. Verwenden Sie keine Dateien aus dem Smarty-Paket.

2. Namespace in der Projekt-composer.json registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\BotProtection\\": "vendor/ecs/botprotection/src/"

Vollständiges Beispiel mit einem vorhandenen Namespace:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "vendor/vorhandener/anbieter/modul/src/",
            "Ecs\\BotProtection\\": "vendor/ecs/botprotection/src/"
        }
    }
}

Der Eintrag gehört in die Projekt-composer.json, nicht in die Datei des Moduls. Vorhandene Einträge bleiben erhalten. Bei dieser manuellen Installation ist kein zusätzlicher require-Eintrag notwendig.

3. Autoloader und Modul installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/botprotection
vendor/bin/oe-console oe:module:activate ecs_botprotection
vendor/bin/oe-console oe:cache:clear

Alternativ kann die Aktivierung nach oe:module:install im Admin unter Erweiterungen ‣ Module erfolgen.

4. OXID-7-Installation kontrollieren

Prüfen Sie mindestens:

Das Modul ist sichtbar und aktiv; alle Einstellungsgruppen sind vorhanden.
eComStyle.de ‣ BotProtection öffnet das Dashboard ohne Template- oder Controllerfehler.
Das Dashboard meldet einen aktiven SQLite-Speicher und zeigt den Pfad botprotection.sqlite an.
Der mitgelieferte lokale IPv4-/IPv6-Datenstand wird angezeigt.
Storefront, Anmeldung, Warenkorb, Checkout und Admin öffnen fehlerfrei.
Ein kontrollierter Test im passiven Modus erzeugt einen Dashboard-Eintrag.
Der OXID-Cache wurde geleert.

OXID 6 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Smarty-Paket nach:

source/modules/ecs/BotProtection

Beachten Sie die Groß- und Kleinschreibung von BotProtection. Prüfen Sie mindestens metadata.php, composer.json, Controller, Core, data und views.

2. Namespace in der Projekt-composer.json registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\BotProtection\\": "./source/modules/ecs/BotProtection/"

Vollständiges Beispiel:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "./source/modules/vorhandenes/modul/",
            "Ecs\\BotProtection\\": "./source/modules/ecs/BotProtection/"
        }
    }
}

Alle vorhandenen Namespaces bleiben erhalten. Ein zusätzlicher Eintrag unter require ist für die manuelle Installation nicht notwendig.

3. Autoloader und Modulkonfiguration installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/BotProtection
vendor/bin/oe-console oe:module:activate ecs_botprotection

Leeren Sie anschließend die temporären Shopdateien beziehungsweise den OXID-Cache mit dem in der jeweiligen OXID-6-Umgebung vorgesehenen Verfahren.

4. OXID-6-Installation kontrollieren

Prüfen Sie mindestens:

Modul und alle Einstellungsgruppen sind im Admin sichtbar.
Das Smarty-Dashboard unter eComStyle.de ‣ BotProtection öffnet fehlerfrei.
SQLite-Speicher und lokale GeoIP-Datenbank werden als aktiv angezeigt.
Storefront und Admin öffnen ohne Templatefehler.
Ein Test im passiven Modus wird protokolliert.
Die temporären Shopdateien wurden geleert.

Datenbanken und Aktivierungsereignis

SQLite-Laufzeitdatenbank

BotProtection ändert die OXID-Shopdatenbank nicht. Bei der Aktivierung wird im von OXID konfigurierten Logverzeichnis folgende moduleigene Datei angelegt:

botprotection/botprotection.sqlite

Das Schema wird automatisch initialisiert und über die SQLite- user_version verwaltet. Es enthält:

runtime_state für Request-Zähler, Rate-Limits, Subnetz-Limits, temporäre Sperren, Verhaltens-, Force-SID- und Force-SID-Wiederverwendungszustände, Searchbot-Cache, Benachrichtigungsstatus und Wartungsstatus,
activity_log für Zeitpunkt, IP-Adresse, Erkennungsgrund, URL, User-Agent, ermitteltes Land und Referer. Ein Eintrag ist ein Erkennungsereignis und nicht zwingend eine tatsächlich ausgelieferte 403-Sperre.

SQLite arbeitet im WAL-Modus. Die Dateien botprotection.sqlite-wal und botprotection.sqlite-shm sind deshalb während des Betriebs normal und gehören bei Sicherung oder vollständiger Entfernung zur Datenbank.

Warnung

Führen Sie keine manuellen CREATE, ALTER oder DELETE-Befehle in der OXID-Shopdatenbank aus. Bei einem Modulaustausch wird das aktuelle SQLite-Schema beim nächsten Öffnen automatisch geprüft. Sichern Sie die SQLite-Dateien vor manuellen Eingriffen und bearbeiten Sie eine aktive WAL-Datenbank nicht mit ungeeigneten Dateikopien.

Datei-Fallback

Ist pdo_sqlite nicht verfügbar oder kann die Datenbank nicht geöffnet werden, verwendet das Modul Unterverzeichnisse wie logs, ratelimit, subnetlimit, behavior, blocked, forcesid und cache. Das Dashboard zeigt in diesem Fall eine rote Warnung. Dieser Fallback erhält den Grundbetrieb, ist bei vielen wechselnden IPs aber deutlich weniger geeignet.

Aktivieren Sie pdo_sqlite möglichst vor dem Live-Betrieb. Vorhandene Fallback-Dateien werden nicht in SQLite importiert. Nach erfolgreicher Umstellung können sie mit dem Bereinigungsskript entfernt werden.

Lokale GeoIP-Datenbank aktualisieren

Die Länderermittlung liest ausschließlich fertige lokale Binärindizes. Das Modul liefert einen IPv4- und einen IPv6-Index mit und verwendet zusätzlich eine neuere oder gleich alte gültige Laufzeitkopie unter:

botprotection/geoip/

Für ein Kundenupdate öffnen Sie eComStyle.de ‣ BotProtection und wählen GeoIP-Datenbank jetzt aktualisieren. Der Vorgang:

lädt die aktuellen user-country-CSV-Dateien und deren SHA-256-Prüfsummen per HTTPS vom Projekt sapics/ip-location-db,
begrenzt die erlaubte Downloadgröße,
prüft Dateiname und SHA-256-Prüfsumme,
validiert und konvertiert sämtliche IPv4- und IPv6-Bereiche,
veröffentlicht erst den vollständigen neuen Satz im Laufzeitverzeichnis.

Eine Sperrdatei verhindert parallele Updates. Temporäre Dateien werden nach Erfolg oder Fehler entfernt. Schlägt die Veröffentlichung fehl, wird die vorherige Laufzeitfassung wiederhergestellt; fehlt sie, bleibt der mitgelieferte Index die Rückfalloption.

Bemerkung

update_country_database.sh im Modulordner ist ein Werkzeug zur Pflege der mit einem künftigen Modulpaket ausgelieferten Daten. Für die laufende Kundeninstallation ist die Schaltfläche im Dashboard vorgesehen.

Modul aktualisieren

OXID 7 aktualisieren

Deaktivieren Sie das Modul für den Dateiaustausch. Ersetzen Sie den vollständigen Ordner vendor/ecs/botprotection durch das aktuelle OXID-7-/Twig-Paket. Führen Sie danach aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/botprotection
vendor/bin/oe-console oe:module:activate ecs_botprotection
vendor/bin/oe-console oe:cache:clear

OXID 6 aktualisieren

Deaktivieren Sie das Modul und ersetzen Sie source/modules/ecs/BotProtection vollständig durch das aktuelle OXID-6-/Smarty-Paket. Führen Sie danach aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/BotProtection
vendor/bin/oe-console oe:module:activate ecs_botprotection

Leeren Sie anschließend die temporären Shopdateien.

Nach jedem Update

Kontrollieren Sie den SQLite-Status und den angezeigten GeoIP-Datenstand.
Prüfen Sie neue oder geänderte Einstellungen; Modulupdates überschreiben vorhandene Betreiberwerte nicht ohne Weiteres. Kontrollieren Sie insbesondere die Länder-Whitelist mit den beiden Länder-Checkboxen sowie Force-SID-Reuse- und Verhaltensschwellen.
Prüfen Sie, ob der Abschnitt Schutzempfehlungen ohne Fehler angezeigt wird. Empfehlungen ändern keine Moduleinstellungen.
Beginnen Sie bei geänderten Erkennungsregeln im passiven Modus und prüfen Sie Dashboard und geschäftskritische Integrationen.
Bereinigen Sie nach einer früheren Datei-Fallback-Installation einmalig die Altdateien.

Honeypot-Link im Storefront-Template einbauen

Das Modul prüft nur, ob ein Request den GET- oder POST-Parameter ref_id enthält. Es fügt keinen Honeypot-Link selbst in die Ausgabe ein. Damit die Einstellung Honeypot aktivieren eine Falle wird, muss das Theme in einem für Besucher nicht sichtbaren Bereich einen Link mit ref_id=… ausgeben.

Achtung

Aktivieren Sie den Honeypot nicht, wenn Ihr Shop oder eine Erweiterung den Parameter ref_id bereits verwendet. Prüfen Sie Zahlungs-Plugins, Tracking-Module, Affiliate-Systeme oder Newsletter-Anmeldungen, bevor Sie den Link einbauen.

Gängige Platzierungen sind der Fußbereich, eine unauffällige Zeile unterhalb aller sichtbaren Links oder ein für Crawler sichtbares, aber nicht interaktives Element. Der Link sollte für Tastatur und Screenreader nicht erreichbar sein, damit er nicht von Menschen ausgelöst wird.

OXID 6 (Smarty) im Child-Theme

Überschreiben Sie beispielsweise tpl/layout/footer.tpl des verwendeten Themes und ergänzen den Block dd_footer_copyright oder einen eigenen Footer-Block:

[{block name="dd_footer_copyright"}]
    [{$oCont->oxcontents__oxcontent->value}]
    <a href="[{$oViewConf->getSelfLink()|cat:'ref_id=1'}]"
       style="display:none;" aria-hidden="true" tabindex="-1">&nbsp;</a>
[{/block}]

Der Link zeigt auf index.php und übergibt ref_id=1. Jeder Crawler, der ihm folgt, triggert die Falle; bekannte Searchbots werden weiterhin durch die User-Agent-Whitelist und DNS-Verifikation ausgenommen.

OXID 7 (Twig) im Child-Theme

Überschreiben Sie beispielsweise tpl/layout/footer.html.twig oder views/twig/extensions/themes/<meintheme>/layout/footer.html.twig und ergänzen den Block dd_footer_copyright:

{% block dd_footer_copyright %}
    {{ include(template_from_string(oCont.oxcontents__oxcontent.value)) }}
    <a href="{{ oViewConf.getSelfLink()|raw }}ref_id=1"
       style="display:none;" aria-hidden="true" tabindex="-1">&nbsp;</a>
{% endblock %}

getSelfLink() endet in OXID je nach Einstellung mit ? oder &; das direkte Anhängen von ref_id=1 ist deshalb sicher. Verwenden Sie |raw, damit Twig ein bereits enthaltenes & nicht nochmals escaped.

Alternativen und Abschaltung

Möchten Sie keinen Template-Eingriff vornehmen, lassen Sie Honeypot aktivieren ausgeschaltet. Die Prüfung nach ref_id bringt dann keinen Schutz und birgt nur das Risiko, aus Versehen echte Besucher zu sperren.

Daten bereinigen

Automatische Pflege

Wenn Temporäre Daten automatisch bereinigen aktiv ist, stößt ein Storefront-Request nach Ablauf des konfigurierten Intervalls eine begrenzte Bereinigung an. In SQLite werden abgelaufene Laufzeitzustände und ältere Aktivitätsprotokolle entfernt. Die Größenbegrenzung kann zusätzlich die ältesten Aktivitäten löschen und die Datenbank verkleinern. Im Datei-Fallback werden abgelaufene Zustandsdateien gelöscht und bei Überschreitung der Größengrenze die ältesten Dateien entfernt.

Bereinigung im Dashboard

Unter eComStyle.de ‣ BotProtection ‣ Daten aufräumen wird eine Aufbewahrungsdauer von 1 bis 365 Tagen gewählt. Bei SQLite löscht die Aktion alte activity_log-Zeilen sowie bereits abgelaufene runtime_state-Zeilen. Im Datei-Fallback löscht sie alte tägliche Aktivitätslogs und temporäre Dateien, die älter als einen Tag sind.

Ein Dashboard-Aufruf bearbeitet bei SQLite höchstens 100.000 alte Aktivitätszeilen und 100.000 abgelaufene Laufzeitzustände. Zeigt das Ergebnis diese Obergrenze, wiederholen Sie die Aktion, bis kein entsprechender Altbestand mehr gemeldet wird.

Die Aktion löscht keine aktuelle, noch nicht abgelaufene Sperre, keine Moduleinstellung und keine GeoIP-Datenbank.

Bereinigung über die Konsole

Wechseln Sie in den Modulordner des passenden Pakets und übergeben Sie die gewünschte Zahl voller Tage, mindestens 1:

./cleanup_bot_data.sh 7

Bei SQLite entfernt das Skript alle abgelaufenen Laufzeitzustände und alle Aktivitätszeilen vor dem Stichtag; anschließend wird die WAL-Datei per Checkpoint gekürzt. Zusätzlich räumt es vorhandene Legacy-Aktivitätslogs und ältere Legacy-Dateien für IP-Limits, Verhalten, Sperren, Force-SID und Cache auf. Prüfen Sie die ausgegebene Pfadangabe, bevor Sie das Ergebnis abnehmen.

Das Skript benötigt für SQLite die Erweiterung pdo_sqlite in der CLI-PHP-Version. Ein Aufruf ohne Zahl verwendet sieben Tage.

Detaillierte Analyse über die Konsole

Das mitgelieferte Skript liest die Modulablage nur und verändert keine Daten:

./analyze_bot_attacks.sh

Im SQLite-Betrieb zeigt es Gesamtzahl, Gründe, die 20 häufigsten IP-Adressen, die zehn häufigsten URLs, Herkunftsländer und aktive Zustände nach Namespace. Im Datei-Fallback ergänzt es unter anderem eine 24-Stunden-Verteilung, User-Agent- und Force-SID-Auswertung. Die Werte umfassen den noch vorhandenen Datenbestand und können deshalb weiter zurückreichen als die heutigen Dashboard-Detailtabellen.

Führen Sie das Skript im Modulordner des passenden Pakets aus. Für SQLite muss pdo_sqlite auch im CLI-PHP aktiv sein; im Datei-Fallback werden zusätzlich übliche Unix-Werkzeuge wie grep, sort und wc benötigt.

Alle BotProtection-Laufzeitdaten vollständig zurücksetzen

Warnung

Dieser Vorgang entfernt Statistiken, Aktivitätsprotokolle, temporäre Sperren, Rate- und Subnetz-Zähler, Verhaltensdaten, Suchmaschinen-Cache, Benachrichtigungsstatus und eine im Dashboard aktualisierte GeoIP-Fassung. Er ist nicht rückgängig zu machen, wenn keine Sicherung vorhanden ist.

Für einen vollständigen, kontrollierten Reset:

Deaktivieren Sie ecs_botprotection, damit keine neuen Schreibzugriffe erfolgen.
Lesen Sie den tatsächlichen SQLite-Pfad im Dashboard oder aus dem von OXID konfigurierten Logpfad ab. Arbeiten Sie ausschließlich am Unterordner botprotection.
Verschieben Sie diesen Unterordner zunächst in ein eindeutig benanntes Sicherungsverzeichnis außerhalb des aktiven Logpfads.
Aktivieren Sie das Modul wieder. Es erzeugt beim nächsten Zugriff eine leere SQLite-Datenbank; ohne Laufzeit-GeoIP wird automatisch der gültige mitgelieferte Index verwendet.
Prüfen Sie Storefront und Dashboard. Löschen Sie die Sicherung erst danach, wenn die Daten wirklich dauerhaft entfernt werden sollen.

Die in OXID gespeicherten Moduleinstellungen werden dadurch nicht zurückgesetzt. Leeren oder ändern Sie Whitelists, Blacklists, E-Mail-Adresse und sonstige Einstellungen bei Bedarf separat im Admin.

Datenaufbewahrung bei Deaktivierung

onDeactivate löscht bewusst keine Daten. SQLite-Datei, WAL-/SHM-Dateien, Legacy-Verzeichnisse, Laufzeit-GeoIP und Protokolle bleiben für eine spätere Reaktivierung oder Auswertung erhalten. Auch eine erneute Aktivierung leert diese Daten nicht automatisch.