Modul Magento 2 – Scanner de securitate și detectare a codului malițios

Instrucțiunea modulului Kowal_SecurityScan

Prezentare generală

Modulul extinde Magento 2 cu un strat de monitorizare a securității pentru fișierele aplicației, tabele selectate ale bazei de date, URL-uri suspecte și analiza opțională a incidentelor prin OpenAI.

Rapoartele sunt salvate în tabelul kowal_securityscan_report și pot fi trimise prin e-mail.

Funcții principale

• scanarea modificărilor din fișierele Magento cu comparație față de snapshot,
• scanare euristică a fișierelor php, phtml, php5, inc, phar, js, html, htm, svg, htaccess,
• analiza tokenurilor PHP prin token_get_all(),
• scanarea tabelelor selectate ale bazei de date pentru HTML malițios, JavaScript, SVG, URI data: și URL-uri suspecte,
• integrare cu Google Safe Browsing API,
• analiză OpenAI opțională pentru detecții,
• allowlist-uri configurabile pentru domenii, fișiere, modele de conținut și reguli,
• rapoarte cu sugestii pregătite pentru allowlist-uri și export al configurației JSON normalizate.

Cerințe

• Magento 2,
• modulul disponibil kowal/base,
• cron Magento funcțional,
• trimitere e-mail configurată corect,
• opțional: cheie OpenAI API și cheie Google Safe Browsing API.

Instalare

1. Adăugarea repository-ului pachetului

Adaugă repository-ul Composer Kowal:

Datele de acces la repository-ul Composer, adresa de e-mail a clientului și tokenul de licență, le vei primi prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificare pe kowal.store. Înlocuiește TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului tău, iar TWOJ_TOKEN cu tokenul primit. Execută comenzile în directorul rădăcină Magento.

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

Dacă repository-ul necesită autorizare:

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

2. Instalarea pachetului

composer require kowal/module-securityscan

3. Activarea modulului

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

În mediul de producție, execută pașii standard de deployment Magento, conform procesului tău de implementare.

Cron și programul scanărilor

Modulul înregistrează propriul grup cron securityscan.

• kowal_securityscan_filecheck - zilnic la 00:00,
• kowal_securityscan_malwarecheck - zilnic la 01:00,
• kowal_securityscan_dbcheck - zilnic la 02:00,
• kowal_securityscan_cleanup_reports - zilnic la 02:30.

Fără un cron Magento funcțional, scanările automate nu vor fi executate.

Rularea manuală a scanărilor

Pentru rularea manuală a scanărilor folosește:

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

Aceasta este metoda recomandată de testare după instalare și după modificările de configurare.

Configurare

Calea de configurare:

Stores -> Configuration -> kowal -> kowal_security

Setări generale

• 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

Configurație minimă

1. activează modulul,
2. setează adresa destinatarului rapoartelor,
3. setează adresa expeditorului rapoartelor,
4. asigură-te că trimiterea e-mailurilor Magento funcționează,
5. asigură-te că cronul Magento funcționează.

Analiza OpenAI

Secțiunea Analiza OpenAI permite extinderea rapoartelor cu evaluarea riscului și recomandări de acțiune.

Câmpuri disponibile:

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

Cum se activează

1. activează Włącz analizę AI,
2. completează OpenAI API Key,
3. salvează configurația,
4. reîmprospătează formularul de configurare,
5. alege modelul.

Comportament implicit

• model implicit: gpt-4.1-mini,
• limită implicită de context: 12000,
• valorile sub 2000 sunt ridicate la 12000,
• limita maximă de context este 50000.

Dacă OpenAI este dezactivat sau lipsește cheia, modulul continuă să funcționeze și folosește euristici locale.

Google Safe Browsing

Dacă completezi Google Safe Browsing API Key, modulul va:

• verifica URL-urile detectate în fișiere și bază,
• verifica adresa de bază a magazinului.

Lipsa cheii nu blochează scanările de bază, ci doar dezactivează această etapă.

Scanarea modificărilor din fișiere

filecheck funcționează pe baza snapshotului salvat în:

var/security_scan_hashes.json

La prima rulare:

• este creat snapshotul,
• încă nu există comparația modificărilor,
• raportul informează despre crearea bazei de referință.

Rulările ulterioare raportează modificări de tip ADDED, MODIFIED și REMOVED.

Sunt omise, printre altele:

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

Scanare malware în fișiere

malwarecheck scanează fișierele aplicației pe baza:

• regulilor regex cu rule_id,
• euristicilor de tokenuri PHP,
• verificărilor URL-urilor prin Safe Browsing.

Exemple de tipuri de detecții:

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

În rapoarte, motivele sunt prezentate în formatul:

[file.encoded_payload_blob] Encoded payload blob detected

Scanarea bazei de date

dbcheck analizează tabele Magento selectate:

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

Exemple de reguli:

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

Conținutul este normalizat anterior prin:

• html_entity_decode,
• rawurldecode,
• normalizarea whitespace,
• analiza mai multor variante ale aceluiași content.

Configurare avansată: allowlist-uri

Allowlist-urile servesc la limitarea false positive fără dezactivarea întregului modul.

1. Allowlist domenii

Câmp: kowal_security/general/allowlisted_domains

Format:

• un domeniu pe linie sau
• listă separată prin virgule.

cdn.example.comstatic.example.org

Efect:

• URL-urile din aceste domenii nu vor fi tratate ca suspecte,
• Safe Browsing nu le va verifica.

2. Allowlist fișiere

Câmp: kowal_security/general/allowlisted_file_patterns

Format:

• căi relative,
• suport pentru globuri.

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

Efect: fișierele potrivite cu modelul sunt omise complet de scanarea malware. Această setare are o acoperire largă.

3. Allowlist modele bază

Câmp: kowal_security/general/allowlisted_db_patterns

Format:

• fraze,
• fragmente HTML sau JS,
• intrări separate prin linie nouă sau virgule.

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

Efect: o înregistrare din bază care conține un astfel de fragment este omisă de scanarea DB. Această setare are, de asemenea, o acoperire largă.

4. Allowlist reguli fișiere

Câmp: kowal_security/general/allowlisted_file_rules

Format preferat:

sciezka_lub_glob | rule_id

Exemplu:

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

Compatibilitate inversă:

• intrările vechi după eticheta completă a regulii continuă să funcționeze,
• intrările noi ar trebui să folosească rule_id.

Efect: este dezactivată doar regula indicată pentru calea indicată, iar restul scanării pentru acel fișier continuă să funcționeze.

5. Allowlist reguli bază

Câmp: kowal_security/general/allowlisted_db_rules

Format preferat:

tabela_lub_* | rule_id

Exemplu:

cms_block | db.inline_script_tag* | db.fetch_or_xhr_loader

Efect: este dezactivată doar regula indicată, iar celelalte continuă să funcționeze pentru această înregistrare sau tabel.

Rapoarte

Rapoartele pot conține:

• lista detecțiilor,
• evaluarea riscului,
• indicatori și recomandări,
• candidați pentru allowlist-uri după verificare manuală,
• configurația allowlist normalizată în JSON.

Sugestii de allowlist în rapoarte

Secțiunea raportului poate conține intrări de tip:

- 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

Interpretare:

• zasieg=LOW - candidat mai sigur,
• zasieg=HIGH - dezactivare amplă, doar după verificare fermă,
• pewnosc=MEDIUM/HIGH - candidat mai previzibil pentru configurare,
• pewnosc=LOW - necesită prudență.

Export JSON

Raportul conține și secțiunea Znormalizowana konfiguracja allowlist (JSON). Este un set de valori gata, deduplicat, pentru copiere în configurație.

Mod recomandat de utilizare

1. rulează manual toate cele trei scanări după instalare,
2. tratează primul filecheck ca pe construirea snapshotului,
3. analizează rapoartele și confirmă care detecții sunt reale,
4. pentru false positive folosește mai întâi allowlisted_file_rules și allowlisted_db_rules,
5. abia când este necesar, folosește allowlisted_domains, allowlisted_file_patterns și allowlisted_db_patterns,
6. după modificarea configurației, rulează din nou scanarea CLI corespunzătoare și verifică rezultatul.

Observații operaționale

• filecheck la prima rulare nu raportează încă modificările ca incident,
• modulul funcționează fără OpenAI și fără Safe Browsing, dar cu o profunzime mai mică a analizei,
• allowlisted_file_patterns și allowlisted_db_patterns au un impact larg și ar trebui folosite cu moderație,
• formatul preferat pentru allowlist-urile de reguli este rule_id, nu eticheta textuală completă.