Anleitung für das Modul Kowal_SecurityScan
Überblick
Das Modul erweitert Magento 2 um eine Sicherheitsüberwachungsebene für Anwendungsdateien, ausgewählte Datenbanktabellen, verdächtige URLs und die optionale Analyse von Vorfällen durch OpenAI.
Berichte werden in der Tabelle kowal_securityscan_report gespeichert und können per E-Mail versendet werden.
Hauptfunktionen
- Scan auf Änderungen an Magento-Dateien mit Vergleich zu einem Snapshot,
- heuristischer Scan von Dateien des Typs
php, phtml, php5, inc, phar, js, html, htm, svg, htaccess,
- Analyse von PHP-Tokens über
token_get_all(),
- Scan ausgewählter Datenbanktabellen auf schädliches HTML, JavaScript, SVG,
data: -URIs und verdächtige URLs,
- Integration mit der Google Safe Browsing API,
- optionale OpenAI-Analyse für Erkennungen,
- konfigurierbare Allowlists für Domains, Dateien, Inhaltsmuster und Regeln,
- Berichte mit fertigen Allowlist-Vorschlägen und Export einer normalisierten JSON-Konfiguration.
Anforderungen
- Magento 2,
- verfügbares Modul
kowal/base,
- funktionierender Magento-Cron,
- korrekt konfigurierte E-Mail-Zustellung,
- optional: OpenAI API-Schlüssel und Google Safe Browsing API-Schlüssel.
Installation
1. Paket-Repository hinzufügen
Fügen Sie das Kowal Composer-Repository hinzu:
Die Zugangsdaten für das Composer-Repository, also die E-Mail-Adresse des Kunden und der Lizenz-Token, erhalten Sie nach dem Kauf per E-Mail. Sie sind nach der Anmeldung unter kowal.storeauch im Kundenkonto verfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch den erhaltenen Token. Führen Sie die Befehle im Magento-Stammverzeichnis aus.
composer config repositories.kowal composer https://repo.kowal.store
Falls das Repository eine Authentifizierung erfordert:
composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
2. Paket installieren
composer require kowal/module-securityscan
3. Modul aktivieren
php bin/magento module:enable Kowal_SecurityScan
php bin/magento setup:upgrade
php bin/magento cache:flush
Führen Sie in der Produktionsumgebung die standardmäßigen Magento-Deployment-Schritte entsprechend Ihrem Implementierungsprozess aus.
Cron und Scan-Zeitplan
Das Modul registriert eine eigene Cron-Gruppe securityscanverwendet.
kowal_securityscan_filecheck – täglich um 00:00,kowal_securityscan_malwarecheck – täglich um 01:00,kowal_securityscan_dbcheck – täglich um 02:00,kowal_securityscan_cleanup_reports – täglich um 02:30verwendet.
Ohne einen funktionierenden Magento-Cron werden keine automatischen Scans ausgeführt.
Scans manuell starten
Verwenden Sie zum manuellen Starten der Scans:
php bin/magento kowal_securityscan:filecheck
php bin/magento kowal_securityscan:malwarecheck
php bin/magento kowal_securityscan:dbcheck
Dies ist die empfohlene Testmethode nach der Installation und nach Konfigurationsänderungen.
Konfiguration
Konfigurationspfad:
Stores -> Configuration -> kowal -> kowal_security
Allgemeine Einstellungen
Włącz modułAdres e-mail do raportówAdres e-mail nadawcyRetencja raportow w dniachGoogle Safe Browsing API KeyAllowlista domenAllowlista plikowAllowlista wzorcow bazyAllowlista reguł plikowAllowlista reguł bazy
Minimalkonfiguration
- Aktivieren Sie das Modul,
- legen Sie die Empfängeradresse für Berichte fest,
- legen Sie die Absenderadresse für Berichte fest,
- stellen Sie sicher, dass der Magento-E-Mail-Versand funktioniert,
- stellen Sie sicher, dass der Magento-Cron funktioniert.
OpenAI-Analyse
Im Abschnitt Analiza OpenAI können Sie die Berichte um eine Risikobewertung und Handlungsempfehlungen erweitern.
Verfügbare Felder:
Włącz analizę AI,OpenAI API Key,Model OpenAI,Maksymalny kontekst dla AIverwendet.
Aktivierung
- Aktivieren Sie
Włącz analizę AI,
- tragen Sie den
OpenAI API Key,
- speichern Sie die Konfiguration,
- aktualisieren Sie das Konfigurationsformular,
- wählen Sie ein Modell aus.
Standardverhalten
- Standardmodell:
gpt-4.1-mini,
- Standard-Kontextlimit:
12000,
- Werte unter
2000 werden auf 12000,
- das maximale Kontextlimit beträgt
50000verwendet.
Wenn OpenAI deaktiviert ist oder der Schlüssel fehlt, funktioniert das Modul weiterhin und verwendet lokale Heuristiken.
Google Safe Browsing
Wenn Sie den Google Safe Browsing API Keyeintragen, wird das Modul:
- in Dateien und der Datenbank erkannte URLs prüfen,
- die Basisadresse des Shops prüfen.
Ein fehlender Schlüssel blockiert die grundlegenden Scans nicht, sondern deaktiviert lediglich diesen Schritt.
Scan auf Dateiänderungen
filecheck arbeitet auf Basis eines Snapshots, der unter folgendem Pfad gespeichert wird:
var/security_scan_hashes.json
Beim ersten Start:
- wird ein Snapshot erstellt,
- findet noch kein Änderungsvergleich statt,
- informiert der Bericht über die Erstellung der Referenzbasis.
Nachfolgende Ausführungen melden Änderungen vom Typ ADDED, MODIFIED und REMOVEDverwendet.
Übersprungen werden unter anderem:
var/,generated/,vendor/,pub/static/,node_modules/verwendet.
Malware-Scan in Dateien
malwarecheck scannt Anwendungsdateien auf Basis von:
- Regex-Regeln mit
rule_id,
- PHP-Tokenheuristiken,
- URL-Prüfungen über Safe Browsing.
Beispiele für Erkennungstypen:
file.obfuscated_eval_chain,file.command_execution_from_request,file.encoded_payload_blob,file.token.decode_execute_chain,file.token.include_from_request,file.inline_svg_or_event_handlerverwendet.
In Berichten werden die Gründe in folgendem Format dargestellt:
[file.encoded_payload_blob] Encoded payload blob detected
Datenbankscan
dbcheck analysiert ausgewählte Magento-Tabellen:
cms_block,cms_page,core_config_data,email_template,newsletter_template,review_detail,catalog_product_entity_textverwendet.
Beispiele für Regeln:
db.inline_script_tag,db.html_event_handler,db.external_iframe,db.javascript_uri,db.data_uri_executable,db.embedded_svg_payload,db.javascript_dom_redirectverwendet.
Der Inhalt wird zuvor normalisiert durch:
html_entity_decode,rawurldecode,- Normalisierung von Whitespace,
- Analyse mehrerer Varianten desselben Inhalts.
Erweiterte Konfiguration: Allowlists
Allowlists dienen dazu, Fehlalarme zu reduzieren, ohne das gesamte Modul zu deaktivieren.
1. Domain-Allowlist
Feld: kowal_security/general/allowlisted_domains
Format:
- eine Domain pro Zeile oder
- eine durch Kommas getrennte Liste.
cdn.example.com
static.example.org
Auswirkung:
- URLs aus diesen Domains werden nicht als verdächtig behandelt,
- Safe Browsing prüft sie nicht.
2. Datei-Allowlist
Feld: kowal_security/general/allowlisted_file_patterns
Format:
- relative Pfade,
- Unterstützung von Globs.
app/code/Vendor/Module/Test/*
pub/media/custom.js
Auswirkung: Dateien, die dem Muster entsprechen, werden vom Malware-Scan vollständig übersprungen. Diese Einstellung hat einen breiten Geltungsbereich.
3. Allowlist für Datenbankmuster
Feld: kowal_security/general/allowlisted_db_patterns
Format:
- Phrasen,
- HTML- oder JS-Fragmente,
- durch neue Zeilen oder Kommas getrennte Einträge.
trusted-inline-widget
data:image/svg+xml,<svg
Auswirkung: Ein Datenbankdatensatz, der ein solches Fragment enthält, wird vom Datenbankscan übersprungen. Auch diese Einstellung hat einen breiten Geltungsbereich.
4. Allowlist für Dateiregeln
Feld: kowal_security/general/allowlisted_file_rules
Bevorzugtes Format:
sciezka_lub_glob | rule_id
Beispiel:
app/code/Vendor/Module/* | file.encoded_payload_blob
pub/media/custom.js | file.javascript_redirect_or_rewrite
Abwärtskompatibilität:
- alte Einträge mit der vollständigen Regelbezeichnung funktionieren weiterhin,
- neue Einträge sollten
rule_idverwendet.
Auswirkung: Nur die angegebene Regel wird für den angegebenen Pfad stummgeschaltet. Der restliche Scan für diese Datei wird weiterhin ausgeführt.
5. Allowlist für Datenbankregeln
Feld: kowal_security/general/allowlisted_db_rules
Bevorzugtes Format:
tabela_lub_* | rule_id
Beispiel:
cms_block | db.inline_script_tag
* | db.fetch_or_xhr_loader
Auswirkung: Nur die angegebene Regel wird stummgeschaltet. Die übrigen Regeln bleiben für diesen Datensatz oder diese Tabelle aktiv.
Berichte
Berichte können Folgendes enthalten:
- Liste der Erkennungen,
- Risikobewertung,
- Indikatoren und Empfehlungen,
- Allowlist-Kandidaten nach manueller Überprüfung,
- normalisierte Allowlist-Konfiguration im JSON-Format.
Allowlist-Vorschläge in Berichten
Der Berichtsabschnitt kann Einträge des folgenden Typs enthalten:
- cms_block | db.inline_script_tag | pewnosc=MEDIUM | zasieg=LOW
- app/code/Vendor/Module/* | file.encoded_payload_blob | pewnosc=MEDIUM | zasieg=LOW
- data:image/svg+xml,<svg... | pewnosc=LOW | zasieg=HIGH
Interpretation:
zasieg=LOW – sichererer Kandidat,zasieg=HIGH – weitreichende Stummschaltung, nur nach gründlicher Überprüfung,pewnosc=MEDIUM/HIGH – besser vorhersehbarer Konfigurationskandidat,pewnosc=LOW – erfordert Vorsicht.
JSON-Export
Der Bericht enthält außerdem den Abschnitt Znormalizowana konfiguracja allowlist (JSON). Dabei handelt es sich um einen fertigen, deduplizierten Wertesatz zur Übernahme in die Konfiguration.
Empfohlene Vorgehensweise
- Starten Sie nach der Installation alle drei Scans manuell,
- betrachten Sie den ersten
filecheck als Erstellung des Snapshots,
- analysieren Sie die Berichte und bestätigen Sie, welche Erkennungen tatsächlich zutreffen,
- verwenden Sie bei Fehlalarmen zunächst
allowlisted_file_rules und allowlisted_db_rules,
- verwenden Sie
allowlisted_domains, allowlisted_file_patterns und allowlisted_db_patterns,
- starten Sie nach einer Konfigurationsänderung den entsprechenden CLI-Scan erneut und prüfen Sie das Ergebnis.
Betriebliche Hinweise
filecheck meldet beim ersten Start noch keine Änderungen als Vorfall,- das Modul funktioniert ohne OpenAI und Safe Browsing, allerdings mit geringerer Analysetiefe,
allowlisted_file_patterns und allowlisted_db_patterns haben weitreichende Auswirkungen und sollten sparsam verwendet werden,- das bevorzugte Format für Regel-Allowlists ist
rule_idund nicht die vollständige Textbezeichnung.
