Manual del módulo Kowal_SecurityScan
Resumen
El módulo amplía Magento 2 con una capa de monitorización de seguridad para los 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 correo electrónico.
Funciones principales
- escaneo de cambios en archivos de Magento con comparación frente a un 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 opcional de OpenAI para las detecciones,
- listas de permitidos configurables para dominios, archivos, patrones de contenido y reglas,
- informes con sugerencias listas para listas de permitidos y exportación de configuración JSON normalizada.
Requisitos
- Magento 2,
- módulo
kowal/base disponible, - cron de Magento operativo,
- envío de correo electrónico correctamente configurado,
- opcionalmente: clave de OpenAI API y clave de Google Safe Browsing API.
Instalación
1. Añadir el repositorio del paquete
Añade el repositorio Composer de Kowal:
Recibirás por correo electrónico los datos de acceso al repositorio Composer, la dirección de correo electrónico del cliente y el 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 correo electrónico 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_SecurityScanphp bin/magento setup:upgradephp bin/magento cache:flush
En un entorno de producción, realiza los pasos estándar de deployment de Magento de acuerdo con tu proceso de despliegue.
Cron y programación de escaneos
El módulo registra su propio grupo cron securityscan.
kowal_securityscan_filecheck - diariamente a las 00:00,kowal_securityscan_malwarecheck - diariamente a la 01:00,kowal_securityscan_dbcheck - diariamente a las 02:00,kowal_securityscan_cleanup_reports - diariamente 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, utiliza:
php bin/magento kowal_securityscan:filecheckphp bin/magento kowal_securityscan:malwarecheckphp bin/magento kowal_securityscan:dbcheck
Es la forma recomendada de realizar pruebas después de la instalación y tras 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
- activa el módulo,
- establece la dirección del destinatario de los informes,
- establece la dirección del remitente de los informes,
- asegúrate de que el envío de correo electrónico de Magento funciona,
- asegúrate de que el cron de Magento funciona.
Análisis de OpenAI
La sección Analiza OpenAI permite ampliar los informes con una evaluación de riesgo y recomendaciones de actuación.
Campos disponibles:
Włącz analizę AI,OpenAI API Key,Model OpenAI,Maksymalny kontekst dla AI.
Cómo activarlo
- activa
Włącz analizę AI, - completa
OpenAI API Key, - guarda la configuración,
- actualiza el formulario de configuración,
- selecciona 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 utiliza heurísticas locales.
Google Safe Browsing
Si completas Google Safe Browsing API Key, el módulo:
- comprobará las URL detectadas en archivos y en la base de datos,
- comprobará la dirección base de la tienda.
La ausencia de la clave no bloquea los escaneos básicos, solo desactiva esta etapa.
Escaneo de cambios en archivos
filecheck funciona a partir 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 informa de 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 los archivos de la aplicación a partir de:
- 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 contenido.
Configuración avanzada: listas de permitidos
Las listas de permitidos sirven para reducir los falsos positivos sin desactivar todo el módulo.
1. Lista de dominios permitidos
Campo: kowal_security/general/allowlisted_domains
Formato:
- un dominio por línea, o
- lista separada por comas.
cdn.example.comstatic.example.org
Efecto:
- las URL de estos dominios no se tratarán como sospechosas,
- Safe Browsing no las comprobará.
2. Lista de archivos permitidos
Campo: kowal_security/general/allowlisted_file_patterns
Formato:
- rutas relativas,
- soporte para globs.
app/code/Vendor/Module/Test/*pub/media/custom.js
Efecto: los archivos que coincidan con el patrón se omiten por completo en el escaneo de malware. Este ajuste tiene un alcance amplio.
3. Lista de patrones permitidos 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-widgetdata:image/svg+xml,
Efecto: el registro de la base de datos que contenga dicho fragmento se omite en el escaneo DB. Este ajuste también tiene un alcance amplio.
4. Lista de reglas de archivos permitidas
Campo: kowal_security/general/allowlisted_file_rules
Formato preferido:
sciezka_lub_glob | rule_id
Ejemplo:
app/code/Vendor/Module/* | file.encoded_payload_blobpub/media/custom.js | file.javascript_redirect_or_rewrite
Compatibilidad con versiones anteriores:
- las entradas antiguas con la etiqueta completa de la regla siguen funcionando,
- las entradas nuevas deben usar
rule_id.
Efecto: solo se silencia la regla indicada para la ruta indicada, mientras que el resto del escaneo para ese archivo sigue funcionando.
5. Lista de reglas de base de datos permitidas
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 que las demás siguen funcionando para ese registro o tabla.
Informes
Los informes pueden contener:
- lista de detecciones,
- evaluación de riesgo,
- indicadores y recomendaciones,
- candidatos para listas de permitidos tras verificación manual,
- configuración normalizada de listas de permitidos en JSON.
Sugerencias de listas de permitidos 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,
Interpretación:
zasieg=LOW - candidato más seguro,zasieg=HIGH - silenciamiento amplio, solo tras una verificación firme,pewnosc=MEDIUM/HIGH - candidato más predecible para la configuración,pewnosc=LOW - requiere precaución.
Exportación JSON
El informe también incluye la sección Znormalizowana konfiguracja allowlist (JSON). Es un conjunto de valores listo, deduplicado, para copiar a la configuración.
Modo de uso recomendado
- ejecuta manualmente los tres escaneos después de la instalación,
- trata el primer
filecheck como la creación del snapshot, - analiza los informes y confirma qué detecciones son reales,
- para falsos positivos, utiliza primero
allowlisted_file_rules y allowlisted_db_rules, - solo cuando sea necesario, utiliza
allowlisted_domains, allowlisted_file_patterns y allowlisted_db_patterns, - después de cambiar la configuración, vuelve a ejecutar el escaneo CLI correspondiente y comprueba 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 utilizarse con moderación,- el formato preferido para las listas de reglas permitidas es
rule_id, no la etiqueta de texto completa.
