Instrucciones del módulo Kowal_SecurityScan
Resumen
El módulo amplía Magento 2 con una capa de monitorización de seguridad para archivos de la aplicación, tablas seleccionadas de la base de datos, URL sospechosas y análisis opcional de incidentes mediante OpenAI.
Los informes se guardan en la tabla kowal_securityscan_report y pueden enviarse por e-mail.
Funciones principales
- escaneo de cambios en archivos Magento con comparación frente a snapshot,
- escaneo heurístico de archivos
php, phtml, php5, inc, phar, js, html, htm, svg, htaccess,
- análisis de tokens PHP mediante
token_get_all(),
- escaneo de tablas seleccionadas de la base de datos en busca de HTML malicioso, JavaScript, SVG, URI
data: y URL sospechosas,
- integración con Google Safe Browsing API,
- análisis OpenAI opcional para detecciones,
- allowlists configurables de dominios, archivos, patrones de contenido y reglas,
- informes con sugerencias listas para allowlists y exportación de configuración JSON normalizada.
Requisitos
- Magento 2,
- módulo
kowal/base,
- cron de Magento operativo,
- envío de e-mail correctamente configurado,
- opcionalmente: clave OpenAI API y clave Google Safe Browsing API.
Instalación
1. Añadir el repositorio del paquete
Añada el repositorio Composer de Kowal:
Recibirás por correo electrónico los datos de acceso al repositorio Composer (dirección de e-mail del cliente y token de licencia) después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.
composer config repositories.kowal composer https://repo.kowal.store
Si el repositorio requiere autorización:
composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
2. Instalación del paquete
composer require kowal/module-securityscan
3. Activación del módulo
php bin/magento module:enable Kowal_SecurityScan
php bin/magento setup:upgrade
php bin/magento cache:flush
En un entorno de producción, ejecute los pasos estándar de deployment de Magento conforme a su proceso de implantación.
Cron y programación de escaneos
El módulo registra su propio grupo cron securityscan.
kowal_securityscan_filecheck - todos los días a las 00:00,kowal_securityscan_malwarecheck - todos los días a las 01:00,kowal_securityscan_dbcheck - todos los días a las 02:00,kowal_securityscan_cleanup_reports - todos los días a las 02:30.
Sin un cron de Magento operativo, los escaneos automáticos no se ejecutarán.
Ejecución manual de escaneos
Para ejecutar escaneos manualmente, utilice:
php bin/magento kowal_securityscan:filecheck
php bin/magento kowal_securityscan:malwarecheck
php bin/magento kowal_securityscan:dbcheck
Es el método recomendado de prueba tras la instalación y después de cambios de configuración.
Configuración
Ruta de configuración:
Stores -> Configuration -> kowal -> kowal_security
Ajustes generales
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
Configuración mínima
- active el módulo,
- configure la dirección del destinatario de los informes,
- configure la dirección del remitente de los informes,
- asegúrese de que el envío de e-mail de Magento funciona,
- asegúrese de que el cron de Magento funciona.
Análisis OpenAI
La sección Analiza OpenAI permite ampliar los informes con evaluación de riesgos y recomendaciones de actuación.
Campos disponibles:
Włącz analizę AI,OpenAI API Key,Model OpenAI,Maksymalny kontekst dla AI.
Cómo activarlo
- active
Włącz analizę AI,
- complete
OpenAI API Key,
- guarde la configuración,
- actualice el formulario de configuración,
- seleccione el modelo.
Comportamiento predeterminado
- modelo predeterminado:
gpt-4.1-mini,
- límite de contexto predeterminado:
12000,
- los valores inferiores a
2000 se elevan a 12000,
- el límite máximo de contexto es
50000.
Si OpenAI está desactivado o falta la clave, el módulo sigue funcionando y aplica heurísticas locales.
Google Safe Browsing
Si completa Google Safe Browsing API Key, el módulo:
- comprobará las URL detectadas en archivos y base de datos,
- comprobará la dirección base de la tienda.
La ausencia de clave no bloquea los escaneos básicos, solo desactiva esta etapa.
Escaneo de cambios en archivos
filecheck funciona sobre la base de un snapshot guardado en:
var/security_scan_hashes.json
En la primera ejecución:
- se crea un snapshot,
- todavía no hay comparación de cambios,
- el informe indica la creación de la base de referencia.
Las ejecuciones posteriores informan de cambios de tipo ADDED, MODIFIED y REMOVED.
Se omiten, entre otros:
var/,generated/,vendor/,pub/static/,node_modules/.
Escaneo de malware en archivos
malwarecheck escanea archivos de la aplicación basándose en:
- reglas regex con
rule_id,
- heurísticas de tokens PHP,
- comprobaciones de URL mediante Safe Browsing.
Ejemplos de tipos de detección:
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.
En los informes, los motivos se presentan en el formato:
[file.encoded_payload_blob] Encoded payload blob detected
Escaneo de base de datos
dbcheck analiza tablas seleccionadas de Magento:
cms_block,cms_page,core_config_data,email_template,newsletter_template,review_detail,catalog_product_entity_text.
Ejemplos de reglas:
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.
El contenido se normaliza previamente mediante:
html_entity_decode,rawurldecode,- normalización de whitespace,
- análisis de múltiples variantes del mismo content.
Configuración avanzada: allowlists
Las allowlists sirven para reducir false positives sin desactivar todo el módulo.
1. Allowlist de dominios
Campo: kowal_security/general/allowlisted_domains
Formato:
- un dominio por línea, o
- lista separada por comas.
cdn.example.com
static.example.org
Efecto:
- las URL de estos dominios no se tratarán como sospechosas,
- Safe Browsing no las comprobará.
2. Allowlist de archivos
Campo: kowal_security/general/allowlisted_file_patterns
Formato:
- rutas relativas,
- soporte de globs.
app/code/Vendor/Module/Test/*
pub/media/custom.js
Efecto: los archivos que coinciden con el patrón se omiten por completo en el escaneo de malware. Este ajuste tiene un alcance amplio.
3. Allowlist de patrones de base de datos
Campo: kowal_security/general/allowlisted_db_patterns
Formato:
- frases,
- fragmentos HTML o JS,
- entradas separadas por una nueva línea o por comas.
trusted-inline-widget
data:image/svg+xml,<svg
Efecto: un registro de base de datos que contiene ese fragmento se omite en el escaneo DB. Este ajuste también tiene un alcance amplio.
4. Allowlist de reglas de archivos
Campo: kowal_security/general/allowlisted_file_rules
Formato preferido:
sciezka_lub_glob | rule_id
Ejemplo:
app/code/Vendor/Module/* | file.encoded_payload_blob
pub/media/custom.js | file.javascript_redirect_or_rewrite
Compatibilidad hacia atrás:
- las entradas antiguas basadas en la etiqueta completa de la regla siguen funcionando,
- las nuevas entradas deben usar
rule_id.
Efecto: solo se silencia la regla indicada para la ruta indicada, y el resto del escaneo para ese archivo sigue funcionando.
5. Allowlist de reglas de base de datos
Campo: kowal_security/general/allowlisted_db_rules
Formato preferido:
tabela_lub_* | rule_id
Ejemplo:
cms_block | db.inline_script_tag
* | db.fetch_or_xhr_loader
Efecto: solo se silencia la regla indicada, mientras las demás siguen funcionando para ese registro o tabla.
Informes
Los informes pueden contener:
- lista de detecciones,
- evaluación de riesgos,
- indicadores y recomendaciones,
- candidatos para allowlists tras verificación manual,
- configuración de allowlists normalizada en JSON.
Sugerencias de allowlist en los informes
La sección del informe puede contener entradas de 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
Interpretación:
zasieg=LOW - candidato más seguro,zasieg=HIGH - silenciamiento amplio, solo tras una verificación firme,pewnosc=MEDIUM/HIGH - candidato de configuración más predecible,pewnosc=LOW - requiere precaución.
Exportación JSON
El informe también contiene la sección Znormalizowana konfiguracja allowlist (JSON). Es un conjunto listo y deduplicado de valores para trasladar a la configuración.
Forma de uso recomendada
- ejecute manualmente los tres escaneos tras la instalación,
- trate el primer
filecheck como la construcción del snapshot,
- analice los informes y confirme qué detecciones son reales,
- para false positives, utilice primero
allowlisted_file_rules y allowlisted_db_rules,
- solo cuando sea necesario, utilice
allowlisted_domains, allowlisted_file_patterns y allowlisted_db_patterns,
- después de cambiar la configuración, ejecute de nuevo el escaneo CLI correspondiente y compruebe el resultado.
Notas operativas
filecheck en la primera ejecución todavía no informa de cambios como incidente,- el módulo funciona sin OpenAI y sin Safe Browsing, pero con menor profundidad de análisis,
allowlisted_file_patterns y allowlisted_db_patterns tienen un impacto amplio y deben usarse con moderación,- el formato preferido para las allowlists de reglas es
rule_id, no la etiqueta textual completa.
