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 un’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 dannoso, 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 esportazione della configurazione JSON normalizzata.

Requisiti

• Magento 2,
• modulo kowal/base disponibile,
• 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 l’indirizzo e-mail del cliente e il token di licenza. Sono disponibili anche nel pannello cliente dopo l’accesso 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 l’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_SecurityScanphp bin/magento setup:upgradephp bin/magento cache:flush

In ambiente di produzione, esegui i passaggi standard di deployment Magento, in linea con il tuo processo di rilascio.

Cron e pianificazione delle scansioni

Il modulo registra il 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 un cron Magento funzionante, le scansioni automatiche non verranno eseguite.

Esecuzione manuale delle scansioni

Per avviare manualmente le scansioni, usa:

php bin/magento kowal_securityscan:filecheckphp bin/magento kowal_securityscan:malwarecheckphp bin/magento kowal_securityscan:dbcheck

È il metodo consigliato per eseguire un test dopo l’installazione e dopo le 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. abilita 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 di Magento funzioni,
5. assicurati che il cron Magento funzioni.

Analisi OpenAI

La sezione Analiza OpenAI consente di arricchire i report con una valutazione del rischio e raccomandazioni sulle azioni da intraprendere.

Campi disponibili:

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

Come abilitare

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

Comportamento predefinito

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

Se OpenAI è disabilitato o manca la chiave, il modulo continua a funzionare e utilizza 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 è ancora disponibile il confronto delle modifiche,
• il report informa della creazione della base di riferimento.

Le esecuzioni successive 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 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 vengono 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 degli spazi,
• analisi di più varianti dello stesso contenuto.

Configurazione avanzata: allowlist

Le allowlist servono a ridurre i falsi positivi senza disattivare l’intero modulo.

1. Allowlist dei 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 saranno trattati come sospetti,
• Safe Browsing non li controllerà.

2. Allowlist dei file

Campo: kowal_security/general/allowlisted_file_patterns

Formato:

• percorsi relativi,
• supporto per 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 dei pattern del database

Campo: kowal_security/general/allowlisted_db_patterns

Formato:

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

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

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

4. Allowlist delle regole dei 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 devono usare rule_id.

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

5. Allowlist delle regole del 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 di 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,

Interpretazione:

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

Esportazione JSON

Il report contiene anche la sezione Znormalizowana konfiguracja allowlist (JSON). È un set pronto e deduplicato di valori 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 falsi positivi, 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 verifica 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 devono essere usati con parsimonia,
• il formato preferito per le allowlist delle regole è rule_id, non l’etichetta testuale completa.