Guide du module Kowal_SecurityScan
Vue d’ensemble
Le module ajoute à Magento 2 une couche de surveillance de sécurité pour les fichiers de l’application, certaines tables de base de données, les URL suspectes et l’analyse optionnelle des incidents via OpenAI.
Les rapports sont enregistrés dans la table kowal_securityscan_report et peuvent être envoyés par e-mail.
Fonctionnalités principales
- analyse des changements dans les fichiers Magento avec comparaison au snapshot,
- analyse heuristique des fichiers
php, phtml, php5, inc, phar, js, html, htm, svg, htaccess, - analyse des tokens PHP via
token_get_all(), - analyse de certaines tables de base de données à la recherche de HTML malveillant, JavaScript, SVG, URI
data: et URL suspectes, - intégration avec Google Safe Browsing API,
- analyse OpenAI optionnelle pour les détections,
- allowlists configurables de domaines, fichiers, modèles de contenu et règles,
- rapports avec suggestions prêtes pour les allowlists et export d’une configuration JSON normalisée.
Prérequis
- Magento 2,
- module
kowal/base disponible, - cron Magento fonctionnel,
- envoi d’e-mails correctement configuré,
- optionnellement : clé OpenAI API et clé Google Safe Browsing API.
Installation
1. Ajout du dépôt du package
Ajoutez le dépôt Composer Kowal :
Les identifiants d’accès au dépôt Composer, c’est-à-dire l’adresse e-mail du client et le token de licence, vous seront envoyés par e-mail après l’achat. Ils sont également disponibles dans l’espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l’adresse e-mail de votre compte et TWOJ_TOKEN par le token reçu. Exécutez les commandes dans le répertoire racine de Magento.
composer config repositories.kowal composer https://repo.kowal.store
Si le dépôt nécessite une autorisation :
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
2. Installation du package
composer require kowal/module-securityscan
3. Activation du module
php bin/magento module:enable Kowal_SecurityScan
php bin/magento setup:upgrade
php bin/magento cache:flush
En environnement de production, effectuez les étapes standard de déploiement Magento, conformément à votre processus de mise en production.
Cron et planning des analyses
Le module enregistre son propre groupe cron securityscan.
kowal_securityscan_filecheck - tous les jours à 00:00,kowal_securityscan_malwarecheck - tous les jours à 01:00,kowal_securityscan_dbcheck - tous les jours à 02:00,kowal_securityscan_cleanup_reports - tous les jours à 02:30.
Sans cron Magento fonctionnel, les analyses automatiques ne seront pas exécutées.
Lancement manuel des analyses
Pour lancer les analyses manuellement, utilisez :
php bin/magento kowal_securityscan:filecheck
php bin/magento kowal_securityscan:malwarecheck
php bin/magento kowal_securityscan:dbcheck
C’est la méthode recommandée pour tester après l’installation et après les changements de configuration.
Configuration
Chemin de configuration :
Stores -> Configuration -> kowal -> kowal_security
Paramètres généraux
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
Configuration minimale
- activez le module,
- définissez l’adresse du destinataire des rapports,
- définissez l’adresse de l’expéditeur des rapports,
- assurez-vous que l’envoi d’e-mails Magento fonctionne,
- assurez-vous que le cron Magento fonctionne.
Analyse OpenAI
La section Analiza OpenAI permet d’enrichir les rapports avec une évaluation du risque et des recommandations d’actions.
Champs disponibles :
Włącz analizę AI,OpenAI API Key,Model OpenAI,Maksymalny kontekst dla AI.
Comment l’activer
- activez
Włącz analizę AI, - renseignez
OpenAI API Key, - enregistrez la configuration,
- actualisez le formulaire de configuration,
- choisissez le modèle.
Comportement par défaut
- modèle par défaut :
gpt-4.1-mini, - limite de contexte par défaut :
12000, - les valeurs inférieures à
2000 sont relevées à 12000, - la limite maximale de contexte est
50000.
Si OpenAI est désactivé ou si la clé est absente, le module continue de fonctionner et applique les heuristiques locales.
Google Safe Browsing
Si vous renseignez Google Safe Browsing API Key, le module :
- contrôlera les URL détectées dans les fichiers et la base,
- contrôlera l’adresse de base de la boutique.
L’absence de clé ne bloque pas les analyses de base, elle désactive seulement cette étape.
Analyse des changements dans les fichiers
filecheck fonctionne à partir d’un snapshot enregistré dans :
var/security_scan_hashes.json
Lors du premier lancement :
- un snapshot est créé,
- il n’y a pas encore de comparaison des changements,
- le rapport informe de la création de la base de référence.
Les lancements suivants signalent les changements de type ADDED, MODIFIED et REMOVED.
Sont notamment ignorés :
var/,generated/,vendor/,pub/static/,node_modules/.
Analyse malware dans les fichiers
malwarecheck analyse les fichiers de l’application sur la base :
- des règles regex avec
rule_id, - des heuristiques de tokens PHP,
- des contrôles d’URL via Safe Browsing.
Exemples de types de détection :
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.
Dans les rapports, les motifs sont présentés au format :
[file.encoded_payload_blob] Encoded payload blob detected
Analyse de la base de données
dbcheck analyse certaines tables Magento :
cms_block,cms_page,core_config_data,email_template,newsletter_template,review_detail,catalog_product_entity_text.
Exemples de règles :
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.
Le contenu est d’abord normalisé par :
html_entity_decode,rawurldecode,- normalisation du whitespace,
- analyse de plusieurs variantes du même contenu.
Configuration avancée : allowlists
Les allowlists servent à limiter les false positives sans désactiver tout le module.
1. Allowlist des domaines
Champ : kowal_security/general/allowlisted_domains
Format :
- un domaine par ligne, ou
- liste séparée par des virgules.
cdn.example.comstatic.example.org
Effet :
- les URL de ces domaines ne seront pas considérées comme suspectes,
- Safe Browsing ne les contrôlera pas.
2. Allowlist des fichiers
Champ : kowal_security/general/allowlisted_file_patterns
Format :
- chemins relatifs,
- prise en charge des globs.
app/code/Vendor/Module/Test/*pub/media/custom.js
Effet : les fichiers correspondant au modèle sont entièrement ignorés par l’analyse malware. Ce paramètre a une portée large.
3. Allowlist des modèles de base
Champ : kowal_security/general/allowlisted_db_patterns
Format :
- phrases,
- fragments HTML ou JS,
- entrées séparées par une nouvelle ligne ou par des virgules.
trusted-inline-widgetdata:image/svg+xml,<svg
Effet : un enregistrement de base contenant ce fragment est ignoré par l’analyse DB. Ce paramètre a également une portée large.
4. Allowlist des règles de fichiers
Champ : kowal_security/general/allowlisted_file_rules
Format recommandé :
sciezka_lub_glob | rule_id
Exemple :
app/code/Vendor/Module/* | file.encoded_payload_blobpub/media/custom.js | file.javascript_redirect_or_rewrite
Compatibilité ascendante :
- les anciennes entrées basées sur l’étiquette complète de la règle continuent de fonctionner,
- les nouvelles entrées doivent utiliser
rule_id.
Effet : seule la règle indiquée est neutralisée pour le chemin indiqué, tandis que le reste de l’analyse de ce fichier continue de fonctionner.
5. Allowlist des règles de base
Champ : kowal_security/general/allowlisted_db_rules
Format recommandé :
tabela_lub_* | rule_id
Exemple :
cms_block | db.inline_script_tag* | db.fetch_or_xhr_loader
Effet : seule la règle indiquée est neutralisée, tandis que les autres continuent de fonctionner pour cet enregistrement ou cette table.
Rapports
Les rapports peuvent contenir :
- la liste des détections,
- l’évaluation du risque,
- des indicateurs et recommandations,
- des candidats pour allowlist après vérification manuelle,
- une configuration d’allowlists normalisée en JSON.
Suggestions d’allowlist dans les rapports
La section du rapport peut contenir des entrées de type :
- 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
Interprétation :
zasieg=LOW - candidat plus sûr,zasieg=HIGH - neutralisation large, uniquement après vérification stricte,pewnosc=MEDIUM/HIGH - candidat à la configuration plus prévisible,pewnosc=LOW - nécessite de la prudence.
Export JSON
Le rapport contient aussi la section Znormalizowana konfiguracja allowlist (JSON). Il s’agit d’un ensemble prêt à l’emploi, dédupliqué, de valeurs à reporter dans la configuration.
Mode d’utilisation recommandé
- lancez manuellement les trois analyses après l’installation,
- considérez le premier
filecheck comme la construction du snapshot, - analysez les rapports et confirmez quelles détections sont réelles,
- pour les false positives, utilisez d’abord
allowlisted_file_rules et allowlisted_db_rules, - n’utilisez
allowlisted_domains, allowlisted_file_patterns et allowlisted_db_patterns que lorsque c’est nécessaire, - après un changement de configuration, relancez l’analyse CLI appropriée et vérifiez le résultat.
Remarques opérationnelles
filecheck ne signale pas encore les changements comme incident lors du premier lancement,- le module fonctionne sans OpenAI et sans Safe Browsing, mais avec une profondeur d’analyse moindre,
allowlisted_file_patterns et allowlisted_db_patterns ont un impact large et doivent être utilisés avec parcimonie,- le format préféré pour les allowlists de règles est
rule_id, et non l’étiquette textuelle complète.
