Handleiding voor de module Kowal_SecurityScan
Overzicht
De module breidt Magento 2 uit met een beveiligingsmonitoringlaag voor applicatiebestanden, geselecteerde databasetabellen, verdachte URL's en optionele incidentanalyse via OpenAI.
Rapporten worden opgeslagen in de tabel kowal_securityscan_report en kunnen per e-mail worden verzonden.
Belangrijkste functies
- scan van wijzigingen in Magento-bestanden met vergelijking met een snapshot,
- heuristische scan van
php-,phtml-,php5-,inc-,phar-,js-,html-,htm-,svg-,htaccess-bestanden, - analyse van PHP-tokens via
token_get_all(), - scan van geselecteerde databasetabellen op kwaadaardige HTML, JavaScript, SVG,
data:-URI's en verdachte URL's, - integratie met Google Safe Browsing API,
- optionele OpenAI-analyse voor detecties,
- configureerbare allowlists voor domeinen, bestanden, contentpatronen en regels,
- rapporten met kant-en-klare allowlist-suggesties en export van genormaliseerde JSON-configuratie.
Vereisten
- Magento 2,
- beschikbare module
kowal/base, - werkende Magento-cron,
- correct geconfigureerde e-mailverzending,
- optioneel: OpenAI API-sleutel en Google Safe Browsing API-sleutel.
Installatie
1. Pakketrepository toevoegen
Als het pakket niet beschikbaar is in de standaard Composer-repository, voeg dan de bron toe:
composer config repositories.securityscan vcs https://github.com/kowalco/module-securityscan Als de repository autorisatie vereist:
composer config --global --auth github-oauth.github.com 2. Pakket installeren
composer require kowal/module-securityscan 3. Module activeren
php bin/magento module:enable Kowal_SecurityScanphp bin/magento setup:upgradephp bin/magento cache:flush Voer in de productieomgeving de standaard Magento-deploymentstappen uit, conform uw implementatieproces.
Cron en scanschema
De module registreert een eigen cron-groep securityscan.
kowal_securityscan_filecheck- dagelijks om00:00,kowal_securityscan_malwarecheck- dagelijks om01:00,kowal_securityscan_dbcheck- dagelijks om02:00,kowal_securityscan_cleanup_reports- dagelijks om02:30.
Zonder een werkende Magento-cron worden automatische scans niet uitgevoerd.
Scans handmatig uitvoeren
Gebruik voor het handmatig uitvoeren van scans:
php bin/magento kowal_securityscan:filecheckphp bin/magento kowal_securityscan:malwarecheckphp bin/magento kowal_securityscan:dbcheck Dit is de aanbevolen testmethode na installatie en na configuratiewijzigingen.
Configuratie
Configuratiepad:
Stores -> Configuration -> kowal -> kowal_security
Algemene instellingen
Module inschakelenE-mailadres voor rapportenE-mailadres afzenderBewaartermijn van rapporten in dagenGoogle Safe Browsing API KeyAllowlist van domeinenAllowlist van bestandenAllowlist van databasepatronenAllowlist van bestandsregelsAllowlist van databaseregels
Minimale configuratie
- schakel de module in,
- stel het e-mailadres van de rapportontvanger in,
- stel het e-mailadres van de rapportafzender in,
- controleer of Magento-e-mailverzending werkt,
- controleer of Magento-cron werkt.
OpenAI-analyse
De sectie OpenAI-analyse maakt het mogelijk rapporten uit te breiden met een risicobeoordeling en aanbevelingen voor acties.
Beschikbare velden:
AI-analyse inschakelen,OpenAI API Key,OpenAI-model,Maximale context voor AI.
Inschakelen
- schakel
AI-analyse inschakelenin, - vul
OpenAI API Keyin, - sla de configuratie op,
- vernieuw het configuratieformulier,
- selecteer het model.
Standaardgedrag
- standaardmodel:
gpt-4.1-mini, - standaard contextlimiet:
12000, - waarden onder
2000worden verhoogd naar12000, - de maximale contextlimiet is
50000.
Als OpenAI is uitgeschakeld of de sleutel ontbreekt, werkt de module nog steeds en gebruikt deze lokale heuristieken.
Google Safe Browsing
Als u Google Safe Browsing API Key invult, zal de module:
- URL's controleren die in bestanden en de database zijn gedetecteerd,
- het basisadres van de shop controleren.
Het ontbreken van een sleutel blokkeert de basisscans niet, maar schakelt alleen deze stap uit.
Scan van bestandswijzigingen
filecheck werkt op basis van een snapshot die wordt opgeslagen in:
var/security_scan_hashes.json
Bij de eerste uitvoering:
- wordt een snapshot aangemaakt,
- is er nog geen vergelijking van wijzigingen,
- informeert het rapport over het aanmaken van de referentiebasis.
Volgende uitvoeringen rapporteren wijzigingen van het type ADDED, MODIFIED en REMOVED.
Onder meer de volgende paden worden overgeslagen:
var/,generated/,vendor/,pub/static/,node_modules/.
Malwarescan in bestanden
malwarecheck scant applicatiebestanden op basis van:
- regex-regels met
rule_id, - PHP-tokenheuristieken,
- URL-controles via Safe Browsing.
Voorbeelden van detectietypen:
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_handler.
In rapporten worden de redenen gepresenteerd in het formaat:
[file.encoded_payload_blob] Encoded payload blob detected Databasescan
dbcheck analyseert geselecteerde Magento-tabellen:
cms_block,cms_page,core_config_data,email_template,newsletter_template,review_detail,catalog_product_entity_text.
Voorbeeldregels:
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_redirect.
De content wordt vooraf genormaliseerd via:
html_entity_decode,rawurldecode,- normalisatie van whitespace,
- analyse van meerdere varianten van dezelfde content.
Geavanceerde configuratie: allowlists
Allowlists dienen om false positives te beperken zonder de volledige module uit te schakelen.
1. Allowlist van domeinen
Veld: kowal_security/general/allowlisted_domains
Indeling:
- één domein per regel, of
- een door komma's gescheiden lijst.
cdn.example.comstatic.example.org Effect:
- URL's van deze domeinen worden niet als verdacht behandeld,
- Safe Browsing controleert ze niet.
2. Allowlist van bestanden
Veld: kowal_security/general/allowlisted_file_patterns
Indeling:
- relatieve paden,
- ondersteuning voor globs.
app/code/Vendor/Module/Test/*pub/media/custom.js Effect: bestanden die overeenkomen met het patroon worden volledig overgeslagen door de malwarescan. Deze instelling heeft een brede reikwijdte.
3. Allowlist van databasepatronen
Veld: kowal_security/general/allowlisted_db_patterns
Indeling:
- frasen,
- HTML- of JS-fragmenten,
- items gescheiden door een nieuwe regel of komma's.
trusted-inline-widgetdata:image/svg+xml, Effect: een databaserecord dat zo'n fragment bevat, wordt overgeslagen door de DB-scan. Ook deze instelling heeft een brede reikwijdte.
4. Allowlist van bestandsregels
Veld: kowal_security/general/allowlisted_file_rules
Voorkeursindeling:
pad_of_glob | rule_id Voorbeeld:
app/code/Vendor/Module/* | file.encoded_payload_blobpub/media/custom.js | file.javascript_redirect_or_rewrite Achterwaartse compatibiliteit:
- oude items op basis van het volledige regellabel werken nog steeds,
- nieuwe items moeten
rule_idgebruiken.
Effect: alleen de opgegeven regel voor het opgegeven pad wordt stilgezet, terwijl de rest van de scan voor dat bestand actief blijft.
5. Allowlist van databaseregels
Veld: kowal_security/general/allowlisted_db_rules
Voorkeursindeling:
tabel_of_* | rule_id Voorbeeld:
cms_block | db.inline_script_tag* | db.fetch_or_xhr_loader Effect: alleen de opgegeven regel wordt stilgezet, terwijl de overige regels actief blijven voor dat record of die tabel.
Rapporten
Rapporten kunnen bevatten:
- een lijst met detecties,
- een risicobeoordeling,
- indicatoren en aanbevelingen,
- kandidaten voor de allowlist na handmatige verificatie,
- een genormaliseerde allowlist-configuratie in JSON.
Allowlist-suggesties in rapporten
De rapportsectie kan items bevatten zoals:
- cms_block | db.inline_script_tag | zekerheid=MEDIUM | bereik=LOW- app/code/Vendor/Module/* | file.encoded_payload_blob | zekerheid=MEDIUM | bereik=LOW- data:image/svg+xml, Interpretatie:
bereik=LOW- veiligere kandidaat,bereik=HIGH- brede onderdrukking, alleen na grondige verificatie,zekerheid=MEDIUM/HIGH- beter voorspelbare kandidaat voor configuratie,zekerheid=LOW- vereist voorzichtigheid.
JSON-export
Het rapport bevat ook de sectie Genormaliseerde allowlist-configuratie (JSON). Dit is een kant-en-klare, gededupliceerde set waarden om over te nemen in de configuratie.
Aanbevolen gebruikswijze
- voer na installatie handmatig alle drie de scans uit,
- behandel de eerste
filecheckals het opbouwen van de snapshot, - analyseer de rapporten en bevestig welke detecties daadwerkelijk correct zijn,
- gebruik voor false positives eerst
allowlisted_file_rulesenallowlisted_db_rules, - gebruik pas wanneer nodig
allowlisted_domains,allowlisted_file_patternsenallowlisted_db_patterns, - voer na een configuratiewijziging de juiste CLI-scan opnieuw uit en controleer het resultaat.
Operationele opmerkingen
filecheckrapporteert bij de eerste uitvoering wijzigingen nog niet als incident,- de module werkt zonder OpenAI en zonder Safe Browsing, maar met minder analysegang,
allowlisted_file_patternsenallowlisted_db_patternshebben een brede impact en moeten spaarzaam worden gebruikt,- de voorkeursindeling voor allowlists van regels is
rule_id, niet het volledige tekstlabel.
























