Instrukcja modułu Kowal_SecurityScan

Przegląd

Moduł rozszerza Magento 2 o warstwę monitoringu bezpieczeństwa dla plików aplikacji, wybranych tabel bazy danych, podejrzanych URL-i oraz opcjonalnej analizy incydentów przez OpenAI.

Raporty są zapisywane w tabeli kowal_securityscan_report i mogą być wysyłane e-mailem.

Główne funkcje

• skan zmian w plikach Magento z porównaniem do snapshotu,
• heurystyczny skan plików php, phtml, php5, inc, phar, js, html, htm, svg, htaccess,
• analiza tokenów PHP przez token_get_all(),
• skan wybranych tabel bazy danych pod kątem złośliwego HTML, JavaScript, SVG, data: URI i podejrzanych URL-i,
• integracja z Google Safe Browsing API,
• opcjonalna analiza OpenAI dla wykryć,
• konfiguracyjne allowlisty domen, plików, wzorców treści i reguł,
• raporty z gotowymi sugestiami do allowlist oraz eksportem znormalizowanej konfiguracji JSON.

Wymagania

• Magento 2,
• dostępny moduł kowal/base,
• działający cron Magento,
• poprawnie skonfigurowana wysyłka e-mail,
• opcjonalnie: klucz OpenAI API oraz klucz Google Safe Browsing API.

Instalacja

1. Dodanie repozytorium pakietu

Jeżeli pakiet nie jest dostępny w domyślnym repozytorium Composer, dodaj źródło:

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

Jeżeli repozytorium wymaga autoryzacji:

composer config http-basic.repo.kowal.store <YOUR E-MAIL> <YOUR-TOKEN>

2. Instalacja pakietu

composer require kowal/module-securityscan

3. Aktywacja modułu

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

W środowisku produkcyjnym wykonaj standardowe kroki deploymentu Magento, zgodne z Twoim procesem wdrożeniowym.

Cron i harmonogram skanów

Moduł rejestruje własną grupę cron securityscan.

• kowal_securityscan_filecheck - codziennie o 00:00,
• kowal_securityscan_malwarecheck - codziennie o 01:00,
• kowal_securityscan_dbcheck - codziennie o 02:00,
• kowal_securityscan_cleanup_reports - codziennie o 02:30.

Bez działającego crona Magento skany automatyczne nie będą wykonywane.

Ręczne uruchamianie skanów

Do ręcznego uruchamiania skanów użyj:

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

To zalecany sposób testu po instalacji i po zmianach konfiguracji.

Konfiguracja

Ścieżka konfiguracji:

Stores -> Configuration -> kowal -> kowal_security

Ustawienia ogólne

• 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

Minimalna konfiguracja

1. włącz moduł,
2. ustaw adres odbiorcy raportów,
3. ustaw adres nadawcy raportów,
4. upewnij się, że działa wysyłka e-mail Magento,
5. upewnij się, że działa cron Magento.

Analiza OpenAI

Sekcja Analiza OpenAI pozwala rozszerzyć raporty o ocenę ryzyka i rekomendacje działań.

Dostępne pola:

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

Jak włączyć

1. włącz Włącz analizę AI,
2. uzupełnij OpenAI API Key,
3. zapisz konfigurację,
4. odśwież formularz konfiguracji,
5. wybierz model.

Domyślne zachowanie

• domyślny model: gpt-4.1-mini,
• domyślny limit kontekstu: 12000,
• wartości poniżej 2000 są podnoszone do 12000,
• maksymalny limit kontekstu to 50000.

Jeżeli OpenAI jest wyłączone albo brakuje klucza, moduł nadal działa i stosuje heurystyki lokalne.

Google Safe Browsing

Jeżeli uzupełnisz Google Safe Browsing API Key, moduł będzie:

• sprawdzał URL-e wykryte w plikach i bazie,
• sprawdzał adres bazowy sklepu.

Brak klucza nie blokuje podstawowych skanów, tylko wyłącza ten etap.

Skan zmian w plikach

filecheck działa na podstawie snapshotu zapisywanego do:

var/security_scan_hashes.json

Przy pierwszym uruchomieniu:

• tworzony jest snapshot,
• nie ma jeszcze porównania zmian,
• raport informuje o utworzeniu bazy odniesienia.

Kolejne uruchomienia raportują zmiany typu ADDED, MODIFIED i REMOVED.

Pomijane są m.in.:

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

Skan malware w plikach

malwarecheck skanuje pliki aplikacji na podstawie:

• regexowych reguł z rule_id,
• heurystyk tokenowych PHP,
• sprawdzeń URL-i przez Safe Browsing.

Przykładowe typy wykryć:

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

W raportach powody są prezentowane w formacie:

[file.encoded_payload_blob] Encoded payload blob detected

Skan bazy danych

dbcheck analizuje wybrane tabele Magento:

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

Przykładowe reguły:

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

Treść jest wcześniej normalizowana przez:

• html_entity_decode,
• rawurldecode,
• normalizację whitespace,
• analizę wielu wariantów tego samego contentu.

Zaawansowana konfiguracja: allowlisty

Allowlisty służą do ograniczania false positive bez wyłączania całego modułu.

1. Allowlista domen

Pole: kowal_security/general/allowlisted_domains

Format:

• jedna domena na linię, albo
• lista rozdzielona przecinkami.

cdn.example.com
static.example.org

Efekt:

• URL-e z tych domen nie będą traktowane jako podejrzane,
• Safe Browsing nie będzie ich sprawdzał.

2. Allowlista plików

Pole: kowal_security/general/allowlisted_file_patterns

Format:

• ścieżki względne,
• obsługa globów.

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

Efekt: pliki dopasowane do wzorca są całkowicie pomijane przez skan malware. To ustawienie ma szeroki zasięg.

3. Allowlista wzorców bazy

Pole: kowal_security/general/allowlisted_db_patterns

Format:

• frazy,
• fragmenty HTML lub JS,
• wpisy rozdzielone nową linią albo przecinkami.

trusted-inline-widget
data:image/svg+xml,<svg

Efekt: rekord bazy zawierający taki fragment jest pomijany przez skan DB. To ustawienie również ma szeroki zasięg.

4. Allowlista reguł plików

Pole: kowal_security/general/allowlisted_file_rules

Preferowany format:

sciezka_lub_glob | rule_id

Przykład:

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

Kompatybilność wsteczna:

• stare wpisy po pełnej etykiecie reguły nadal działają,
• nowe wpisy powinny używać rule_id.

Efekt: wyciszana jest tylko wskazana reguła dla wskazanej ścieżki, a reszta skanu dla tego pliku nadal działa.

5. Allowlista reguł bazy

Pole: kowal_security/general/allowlisted_db_rules

Preferowany format:

tabela_lub_* | rule_id

Przykład:

cms_block | db.inline_script_tag
* | db.fetch_or_xhr_loader

Efekt: wyciszana jest tylko wskazana reguła, a pozostałe nadal działają dla tego rekordu lub tabeli.

Raporty

Raporty mogą zawierać:

• listę wykryć,
• ocenę ryzyka,
• wskaźniki i rekomendacje,
• kandydatów do allowlist po ręcznej weryfikacji,
• znormalizowaną konfigurację allowlist w JSON.

Sugestie allowlist w raportach

Sekcja raportu może zawierać wpisy typu:

- 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

Interpretacja:

• zasieg=LOW - bezpieczniejszy kandydat,
• zasieg=HIGH - szerokie wyciszenie, tylko po twardej weryfikacji,
• pewnosc=MEDIUM/HIGH - bardziej przewidywalny kandydat do konfiguracji,
• pewnosc=LOW - wymaga ostrożności.

Eksport JSON

Raport zawiera też sekcję Znormalizowana konfiguracja allowlist (JSON). To gotowy, zdeduplikowany zestaw wartości do przepisania do konfiguracji.

Zalecany sposób użycia

1. uruchom ręcznie wszystkie trzy skany po instalacji,
2. pierwszy filecheck potraktuj jako budowę snapshotu,
3. przeanalizuj raporty i potwierdź, które wykrycia są prawdziwe,
4. dla false positive najpierw używaj allowlisted_file_rules i allowlisted_db_rules,
5. dopiero gdy to konieczne, używaj allowlisted_domains, allowlisted_file_patterns i allowlisted_db_patterns,
6. po zmianie konfiguracji uruchom ponownie odpowiedni skan CLI i sprawdź wynik.

Uwagi operacyjne

• filecheck przy pierwszym uruchomieniu nie raportuje jeszcze zmian jako incydentu,
• moduł działa bez OpenAI i bez Safe Browsing, ale z mniejszą głębią analizy,
• allowlisted_file_patterns i allowlisted_db_patterns mają szeroki wpływ i powinny być używane oszczędnie,
• preferowany format dla allowlist reguł to rule_id, nie pełna etykieta tekstowa.