Módulo Magento 2 – Escáner de seguridad y detección de código malicioso
Kowal Security Scan es un módulo de seguridad avanzado para Magento 2 que ayuda a detectar más rápidamente cambios sospechosos en archivos, código malicioso, URL peligrosas e inyecciones en contenidos de la base de datos. Ha sido diseñado para funcionar de forma ligera, sin agentes adicionales y sin una implementación compleja.
Funciones principales del módulo
- Escaneo de cambios en archivos - detecta archivos nuevos, modificados y eliminados dentro de la aplicación Magento.
- Escaneo heurístico de malware - analiza archivos
php,phtml,js,html,svg,htaccessy otros portadores de payloads. - Análisis de tokens PHP - detecta cadenas
decode -> execute, callbacks dinámicos, variable function calls yinclude/requiresospechosos. - Escaneo de base de datos - comprueba tablas seleccionadas de Magento en busca de HTML malicioso, JavaScript, SVG, URI
data:y enlaces peligrosos. - Integración con Google Safe Browsing - evalúa la reputación de las URL presentes en los contenidos de la tienda.
- Análisis opcional con OpenAI - amplía el informe con evaluación de riesgos y recomendaciones de actuación.
- Allowlists avanzadas - permiten reducir false positives a nivel de dominios, archivos, contenidos y reglas concretas.
- Informes con configuración lista para usar - el módulo sugiere candidatos para la allowlist y genera una exportación JSON normalizada lista para su uso.
¿Qué distingue a este módulo?
- Identificadores de reglas estables - las reglas de archivos y base de datos tienen su propio
rule_id, por lo que la configuración de la allowlist no depende de la descripción textual completa. - Informes que facilitan la gestión de incidentes - el informe muestra no solo las detecciones, sino también el nivel de riesgo, recomendaciones y entradas listas para la configuración.
- Control de false positives sin desactivar el escáner - puede silenciar una regla concreta para la ruta o tabla indicada en lugar de desactivar todo el módulo.
- Automatización completa - el módulo funciona en cron, pero cada escaneo también puede ejecutarse manualmente mediante CLI.
¿Qué amenazas ayuda a detectar?
- código PHP ofuscado basado en
e-val,base-64_decode,gzin-flatey técnicas similares, - inserciones maliciosas de JavaScript en contenidos CMS,
- iframes externos y redirecciones sospechosas,
- payloads SVG y contenido oculto en URI
data:, - enlaces peligrosos que llevan a malware, phishing o software no deseado,
- cambios no autorizados en archivos de la aplicación.
¿Dónde busca amenazas el módulo?
El módulo analiza áreas clave de la tienda en las que los incidentes aparecen con mayor frecuencia:
- archivos de la aplicación Magento y de los módulos,
- bloques CMS,
- páginas CMS,
core_config_data,- plantillas de correo de Magento y newsletter,
- contenidos de producto y reseñas de clientes.
Informes y respuesta operativa
- Los resultados se guardan en una tabla de informes dedicada del módulo.
- El informe puede enviarse por correo electrónico al operador.
- Cada detección puede incluir nivel de riesgo, indicaciones operativas y
rule_idrelacionado. - El informe puede preparar sugerencias listas para la allowlist y una configuración JSON normalizada.
Ejemplos de uso
- detección de código malicioso añadido tras una intrusión en la tienda,
- monitorización de cambios no autorizados en archivos del despliegue,
- detección de bloques CMS o contenidos de la base de datos infectados,
- evaluación de si una URL sospechosa debe incluirse en la allowlist o eliminarse del sistema.
¿Por qué merece la pena?
- Implementación rápida - funciona como módulo de Magento 2 sin infraestructura adicional.
- Informes prácticos - el módulo no termina su trabajo con la detección, sino que ayuda a pasar a una decisión operativa.
- Mejor control de la calidad de las alertas - las allowlists y
rule_idfacilitan mantener una alta eficacia sin una avalancha de falsas alarmas. - Buena adaptación a entornos de producción - los escaneos automáticos, el envío de informes por correo y los comandos CLI manuales respaldan el trabajo diario del equipo técnico.
Compatibilidad
- Magento Open Source 2.3.x - 2.4.x
- Adobe Commerce / Magento Commerce
¿Qué incluye el paquete?
- módulo Magento 2 con tareas cron y comandos CLI,
- configuración administrativa del módulo,
- mecanismo de informes a base de datos y correo electrónico,
- reglas de detección avanzadas y sistema de allowlist.
Documentación y soporte
El módulo incluye documentación de implementación y configuración, y su arquitectura facilita el ajuste posterior de reglas y procesos de seguridad en la tienda Magento 2.
Mejore la detección temprana de incidentes en Magento 2 con Kowal Security Scan.
Manual 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 correo electrónico.
Funciones principales
- escaneo de cambios en archivos de Magento con comparación frente al 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 con OpenAI para las detecciones,
- allowlists configurables de dominios, archivos, patrones de contenido y reglas,
- informes con sugerencias listas para la allowlist y exportación de configuración JSON normalizada.
Requisitos
- Magento 2,
- módulo
kowal/basedisponible, - cron de Magento en funcionamiento,
- 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
Si el paquete no está disponible en el repositorio predeterminado de Composer, añada la fuente:
composer config repositories.securityscan vcs https://github.com/kowalco/module-securityscan Si el repositorio requiere autorización:
composer config --global --auth github-oauth.github.com 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 entorno de producción, ejecute los pasos estándar de despliegue de Magento conforme a su proceso de implementación.
Cron y programación de escaneos
El módulo registra su propio grupo cron securityscan.
kowal_securityscan_filecheck- diariamente a las00:00,kowal_securityscan_malwarecheck- diariamente a las01:00,kowal_securityscan_dbcheck- diariamente a las02:00,kowal_securityscan_cleanup_reports- diariamente a las02:30.
Sin un cron de Magento en funcionamiento, los escaneos automáticos no se ejecutarán.
Ejecución manual de escaneos
Para ejecutar los escaneos manualmente, use:
php bin/magento kowal_securityscan:filecheckphp bin/magento kowal_securityscan:malwarecheckphp bin/magento kowal_securityscan:dbcheck Este es el método recomendado para las pruebas tras la instalación y después de cambios en la configuración.
Configuración
Ruta de configuración:
Stores -> Configuration -> kowal -> kowal_security
Configuración general
Activar móduloDirección de correo para informesDirección de correo del remitenteRetención de informes en díasGoogle Safe Browsing API KeyAllowlist de dominiosAllowlist de archivosAllowlist de patrones de base de datosAllowlist de reglas de archivosAllowlist de reglas de base de datos
Configuración mínima
- active el módulo,
- establezca la dirección del destinatario de los informes,
- establezca la dirección del remitente de los informes,
- asegúrese de que el envío de correo de Magento funciona,
- asegúrese de que el cron de Magento funciona.
Análisis OpenAI
La sección Análisis OpenAI permite ampliar los informes con evaluación de riesgos y recomendaciones de actuación.
Campos disponibles:
Activar análisis AI,OpenAI API Key,Modelo OpenAI,Contexto máximo para AI.
Cómo activarlo
- active
Activar análisis 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
2000se elevan a12000, - 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 la clave no bloquea los escaneos básicos, solo desactiva esta fase.
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 el snapshot,
- todavía no hay comparación de cambios,
- el informe informa de la creación de la referencia base.
Las siguientes ejecuciones 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 espacios en blanco,
- análisis de múltiples variantes del mismo contenido.
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.comstatic.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,
- compatibilidad con glob.
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. Esta configuración 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 salto de línea o comas.
trusted-inline-widgetdata:image/svg+xml, Efecto: el registro de la base de datos que contenga ese fragmento se omite en el escaneo DB. Esta configuración también tiene un alcance amplio.
4. Allowlist de reglas de archivos
Campo: kowal_security/general/allowlisted_file_rules
Formato preferido:
ruta_o_glob | rule_id Ejemplo:
app/code/Vendor/Module/* | file.encoded_payload_blobpub/media/custom.js | file.javascript_redirect_or_rewrite Compatibilidad retroactiva:
- las entradas antiguas por 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:
tabla_o_* | rule_id Ejemplo:
cms_block | db.inline_script_tag* | db.fetch_or_xhr_loader Efecto: solo se silencia la regla indicada y 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 la allowlist tras verificación manual,
- configuración de allowlist normalizada en JSON.
Sugerencias de allowlist en los informes
La sección del informe puede incluir entradas del tipo:
- cms_block | db.inline_script_tag | certeza=MEDIUM | alcance=LOW- app/code/Vendor/Module/* | file.encoded_payload_blob | certeza=MEDIUM | alcance=LOW- data:image/svg+xml, Interpretación:
alcance=LOW- candidato más seguro,alcance=HIGH- silenciamiento amplio, solo tras verificación estricta,certeza=MEDIUM/HIGH- candidato a configuración más predecible,certeza=LOW- requiere precaución.
Exportación JSON
El informe también contiene la sección Configuración normalizada de allowlist (JSON). Es un conjunto de valores listo y sin duplicados para copiar en la configuración.
Forma de uso recomendada
- ejecute manualmente los tres escaneos tras la instalación,
- considere el primer
filecheckcomo la creación del snapshot, - analice los informes y confirme qué detecciones son reales,
- para false positives utilice primero
allowlisted_file_rulesyallowlisted_db_rules, - solo cuando sea necesario utilice
allowlisted_domains,allowlisted_file_patternsyallowlisted_db_patterns, - tras cambiar la configuración, vuelva a ejecutar el escaneo CLI correspondiente y compruebe el resultado.
Notas operativas
filechecken la primera ejecución todavía no informa de cambios como incidente,- el módulo funciona sin OpenAI y sin Safe Browsing, aunque con menor profundidad de análisis,
allowlisted_file_patternsyallowlisted_db_patternstienen 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.
Versión: 1.0.27
31.03.2026
Hemos ampliado el módulo Kowal_SecurityScan con nuevas funciones relacionadas con el análisis de amenazas y la administración de informes.
Novedades
- Se ha añadido integración con OpenAI para analizar archivos modificados y registros sospechosos en la base de datos.
- Los informes y mensajes de correo electrónico incluyen ahora una evaluación de riesgos y acciones recomendadas en las áreas de:
- Magento
- servidor
- firewall
- Se ha añadido la configuración de OpenAI en el panel de Magento, incluyendo:
- activar/desactivar el análisis AI
- clave API
- selección del modelo
- límite de contexto enviado al análisis
Mejoras
- La lista de modelos OpenAI ahora se obtiene dinámicamente desde la API y se muestra en la configuración como un desplegable.
- Se ha ampliado el contenido de los correos electrónicos con la identificación de la tienda Magento:
- dominio de la tienda
- URL de la tienda
- El dominio de la tienda también se añade al asunto del mensaje, lo que facilita la gestión de múltiples instancias.
Automatización y mantenimiento
- Se ha añadido un nuevo cron que limpia las entradas antiguas de la tabla de informes.
- El tiempo de retención de informes es configurable desde system.xml como número de días.
Correcciones técnicas
- Se ha reorganizado la lógica de análisis de archivos y registros sospechosos.
- Se ha mejorado el manejo del contexto de los datos enviados al análisis AI.
- Se ha solucionado el problema de compilación DI relacionado con una implementación anterior del cliente OpenAI.
























