Modulo Magento 2 – Scanner di sicurezza e rilevamento di codice malevolo

Istruzioni del modulo Kowal_SecurityScan

Panoramica

Il modulo estende Magento 2 con un livello di monitoraggio della sicurezza per i file dell’applicazione, tabelle selezionate del database, URL sospetti e analisi opzionale degli incidenti tramite OpenAI.

I report vengono salvati nella tabella kowal_securityscan_report e possono essere inviati via e-mail.

Funzioni principali

• scansione delle modifiche nei file Magento con confronto rispetto allo snapshot,
• scansione euristica dei file php, phtml, php5, inc, phar, js, html, htm, svg, htaccess,
• analisi dei token PHP tramite token_get_all(),
• scansione di tabelle selezionate del database alla ricerca di HTML malevolo, JavaScript, SVG, URI data: e URL sospetti,
• integrazione con Google Safe Browsing API,
• analisi OpenAI opzionale per i rilevamenti,
• allowlist configurabili per domini, file, pattern di contenuto e regole,
• report con suggerimenti pronti per le allowlist ed export della configurazione JSON normalizzata.

Requisiti

• Magento 2,
• modulo disponibile kowal/base,
• cron Magento funzionante,
• invio e-mail configurato correttamente,
• opzionalmente: chiave OpenAI API e chiave Google Safe Browsing API.

Installazione

1. Aggiunta del repository del pacchetto

Aggiungi il repository Composer Kowal:

Riceverai via e-mail dopo l’acquisto i dati di accesso al repository Composer, ovvero indirizzo e-mail del cliente e token di licenza. Sono disponibili anche nel pannello cliente dopo il login su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l’indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

composer config repositories.kowal composer https://repo.kowal.store

Se il repository richiede autorizzazione:

composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

2. Installazione del pacchetto

composer require kowal/module-securityscan

3. Attivazione del modulo

php bin/magento module:enable Kowal_SecurityScan
php bin/magento setup:upgrade
php bin/magento cache:flush

In ambiente di produzione esegui i passaggi standard di deployment Magento, in conformità al tuo processo di rilascio.

Cron e pianificazione delle scansioni

Il modulo registra un proprio gruppo cron securityscan.

• kowal_securityscan_filecheck - ogni giorno alle 00:00,
• kowal_securityscan_malwarecheck - ogni giorno alle 01:00,
• kowal_securityscan_dbcheck - ogni giorno alle 02:00,
• kowal_securityscan_cleanup_reports - ogni giorno alle 02:30.

Senza il cron Magento funzionante, le scansioni automatiche non verranno eseguite.

Avvio manuale delle scansioni

Per avviare manualmente le scansioni usa:

php bin/magento kowal_securityscan:filecheck
php bin/magento kowal_securityscan:malwarecheck
php bin/magento kowal_securityscan:dbcheck

È il metodo consigliato per il test dopo l’installazione e dopo modifiche alla configurazione.

Configurazione

Percorso di configurazione:

Stores -> Configuration -> kowal -> kowal_security

Impostazioni generali

• Włącz moduł
• Adres e-mail do raportów
• Adres e-mail nadawcy
• Retencja raportow w dniach
• Google Safe Browsing API Key
• Allowlista domen
• Allowlista plikow
• Allowlista wzorcow bazy
• Allowlista reguł plikow
• Allowlista reguł bazy

Configurazione minima

1. attiva il modulo,
2. imposta l’indirizzo del destinatario dei report,
3. imposta l’indirizzo del mittente dei report,
4. assicurati che l’invio e-mail Magento funzioni,
5. assicurati che il cron Magento funzioni.

Analisi OpenAI

La sezione Analiza OpenAI consente di arricchire i report con valutazione del rischio e raccomandazioni operative.

Campi disponibili:

• Włącz analizę AI,
• OpenAI API Key,
• Model OpenAI,
• Maksymalny kontekst dla AI.

Come attivare

1. attiva Włącz analizę AI,
2. compila OpenAI API Key,
3. salva la configurazione,
4. aggiorna il form di configurazione,
5. seleziona il modello.

Comportamento predefinito

• modello predefinito: gpt-4.1-mini,
• limite di contesto predefinito: 12000,
• valori inferiori a 2000 vengono aumentati a 12000,
• il limite massimo di contesto è 50000.

Se OpenAI è disattivato o manca la chiave, il modulo continua a funzionare e applica euristiche locali.

Google Safe Browsing

Se compili Google Safe Browsing API Key, il modulo:

• controllerà gli URL rilevati nei file e nel database,
• controllerà l’indirizzo base del negozio.

L’assenza della chiave non blocca le scansioni di base, ma disattiva solo questa fase.

Scansione delle modifiche nei file

filecheck funziona sulla base dello snapshot salvato in:

var/security_scan_hashes.json

Al primo avvio:

• viene creato uno snapshot,
• non esiste ancora un confronto delle modifiche,
• il report informa della creazione della base di riferimento.

Gli avvii successivi segnalano modifiche di tipo ADDED, MODIFIED e REMOVED.

Vengono esclusi, tra gli altri:

• var/,
• generated/,
• vendor/,
• pub/static/,
• node_modules/.

Scansione malware nei file

malwarecheck esegue la scansione dei file dell’applicazione sulla base di:

• regole regex con rule_id,
• euristiche dei token PHP,
• controlli degli URL tramite Safe Browsing.

Esempi di tipi di rilevamento:

• 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.

Nei report, i motivi sono presentati nel formato:

[file.encoded_payload_blob] Encoded payload blob detected

Scansione del database

dbcheck analizza tabelle Magento selezionate:

• cms_block,
• cms_page,
• core_config_data,
• email_template,
• newsletter_template,
• review_detail,
• catalog_product_entity_text.

Esempi di regole:

• 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.

Il contenuto viene prima normalizzato tramite:

• html_entity_decode,
• rawurldecode,
• normalizzazione whitespace,
• analisi di più varianti dello stesso content.

Configurazione avanzata: allowlist

Le allowlist servono a ridurre i false positive senza disattivare l’intero modulo.

1. Allowlist domini

Campo: kowal_security/general/allowlisted_domains

Formato:

• un dominio per riga, oppure
• elenco separato da virgole.

cdn.example.comstatic.example.org

Effetto:

• gli URL di questi domini non verranno trattati come sospetti,
• Safe Browsing non li controllerà.

2. Allowlist file

Campo: kowal_security/general/allowlisted_file_patterns

Formato:

• percorsi relativi,
• supporto dei glob.

app/code/Vendor/Module/Test/*pub/media/custom.js

Effetto: i file corrispondenti al pattern vengono completamente esclusi dalla scansione malware. Questa impostazione ha un ambito ampio.

3. Allowlist pattern database

Campo: kowal_security/general/allowlisted_db_patterns

Formato:

• frasi,
• frammenti HTML o JS,
• voci separate da nuova riga oppure da virgole.

trusted-inline-widgetdata:image/svg+xml,<svg

Effetto: un record del database che contiene tale frammento viene escluso dalla scansione DB. Anche questa impostazione ha un ambito ampio.

4. Allowlist regole file

Campo: kowal_security/general/allowlisted_file_rules

Formato preferito:

sciezka_lub_glob | rule_id

Esempio:

app/code/Vendor/Module/* | file.encoded_payload_blobpub/media/custom.js | file.javascript_redirect_or_rewrite

Compatibilità retroattiva:

• le vecchie voci basate sull’etichetta completa della regola continuano a funzionare,
• le nuove voci dovrebbero usare rule_id.

Effetto: viene silenziata solo la regola indicata per il percorso indicato, mentre il resto della scansione per quel file continua a funzionare.

5. Allowlist regole database

Campo: kowal_security/general/allowlisted_db_rules

Formato preferito:

tabela_lub_* | rule_id

Esempio:

cms_block | db.inline_script_tag* | db.fetch_or_xhr_loader

Effetto: viene silenziata solo la regola indicata, mentre le altre continuano a funzionare per quel record o quella tabella.

Report

I report possono contenere:

• elenco dei rilevamenti,
• valutazione del rischio,
• indicatori e raccomandazioni,
• candidati per le allowlist dopo verifica manuale,
• configurazione allowlist normalizzata in JSON.

Suggerimenti allowlist nei report

La sezione del report può contenere voci del tipo:

- 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

Interpretazione:

• zasieg=LOW - candidato più sicuro,
• zasieg=HIGH - silenziamento ampio, solo dopo verifica rigorosa,
• pewnosc=MEDIUM/HIGH - candidato più prevedibile per la configurazione,
• pewnosc=LOW - richiede cautela.

Export JSON

Il report contiene anche la sezione Znormalizowana konfiguracja allowlist (JSON). È un set di valori pronto e deduplicato da riportare nella configurazione.

Modalità d’uso consigliata

1. avvia manualmente tutte e tre le scansioni dopo l’installazione,
2. considera il primo filecheck come creazione dello snapshot,
3. analizza i report e conferma quali rilevamenti sono reali,
4. per i false positive usa prima allowlisted_file_rules e allowlisted_db_rules,
5. solo quando necessario, usa allowlisted_domains, allowlisted_file_patterns e allowlisted_db_patterns,
6. dopo una modifica della configurazione, avvia nuovamente la scansione CLI appropriata e controlla il risultato.

Note operative

• filecheck al primo avvio non segnala ancora le modifiche come incidente,
• il modulo funziona senza OpenAI e senza Safe Browsing, ma con una profondità di analisi inferiore,
• allowlisted_file_patterns e allowlisted_db_patterns hanno un impatto ampio e dovrebbero essere usati con parsimonia,
• il formato preferito per le allowlist delle regole è rule_id, non l’etichetta testuale completa.