Módulo Magento 2 – Scanner de Segurança e Deteção de Código Malicioso

Manual do módulo Kowal_SecurityScan

Visão geral

O módulo expande o Magento 2 com uma camada de monitorização de segurança para ficheiros da aplicação, tabelas selecionadas da base de dados, URLs suspeitos e análise opcional de incidentes através da OpenAI.

Os relatórios são guardados na tabela kowal_securityscan_report e podem ser enviados por e-mail.

Principais funcionalidades

• scan de alterações em ficheiros Magento com comparação ao snapshot,
• scan heurístico de ficheiros php, phtml, php5, inc, phar, js, html, htm, svg, htaccess,
• análise de tokens PHP através de token_get_all(),
• scan de tabelas selecionadas da base de dados em busca de HTML malicioso, JavaScript, SVG, URI data: e URLs suspeitos,
• integração com Google Safe Browsing API,
• análise OpenAI opcional para deteções,
• allowlists configuráveis de domínios, ficheiros, padrões de conteúdo e regras,
• relatórios com sugestões prontas para allowlists e exportação de configuração JSON normalizada.

Requisitos

• Magento 2,
• módulo kowal/base disponível,
• cron Magento funcional,
• envio de e-mail corretamente configurado,
• opcionalmente: chave OpenAI API e chave Google Safe Browsing API.

Instalação

1. Adicionar o repositório do pacote

Adicione o repositório Composer Kowal:

Receberá por e-mail os dados de acesso ao repositório Composer, ou seja, o endereço de e-mail do cliente e o token de licença, após a compra. Também estão disponíveis no painel de cliente após iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do Magento.

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

Se o repositório exigir autorização:

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

2. Instalação do pacote

composer require kowal/module-securityscan

3. Ativação do módulo

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

Em ambiente de produção, execute os passos padrão de deployment do Magento, de acordo com o seu processo de implementação.

Cron e agendamento de scans

O módulo regista o seu próprio grupo cron securityscan.

• kowal_securityscan_filecheck - diariamente às 00:00,
• kowal_securityscan_malwarecheck - diariamente às 01:00,
• kowal_securityscan_dbcheck - diariamente às 02:00,
• kowal_securityscan_cleanup_reports - diariamente às 02:30.

Sem um cron Magento funcional, os scans automáticos não serão executados.

Execução manual de scans

Para executar scans manualmente, utilize:

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

Esta é a forma recomendada de teste após a instalação e depois de alterações de configuração.

Configuração

Caminho de configuração:

Stores -> Configuration -> kowal -> kowal_security

Definições gerais

• 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ção mínima

1. ative o módulo,
2. defina o endereço do destinatário dos relatórios,
3. defina o endereço do remetente dos relatórios,
4. certifique-se de que o envio de e-mail do Magento funciona,
5. certifique-se de que o cron Magento funciona.

Análise OpenAI

A secção Analiza OpenAI permite expandir os relatórios com avaliação de risco e recomendações de ação.

Campos disponíveis:

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

Como ativar

1. ative Włącz analizę AI,
2. preencha OpenAI API Key,
3. guarde a configuração,
4. atualize o formulário de configuração,
5. selecione o modelo.

Comportamento predefinido

• modelo predefinido: gpt-4.1-mini,
• limite de contexto predefinido: 12000,
• valores abaixo de 2000 são elevados para 12000,
• o limite máximo de contexto é 50000.

Se a OpenAI estiver desativada ou faltar a chave, o módulo continua a funcionar e aplica heurísticas locais.

Google Safe Browsing

Se preencher Google Safe Browsing API Key, o módulo irá:

• verificar URLs detetados nos ficheiros e na base de dados,
• verificar o endereço base da loja.

A ausência da chave não bloqueia os scans básicos, apenas desativa esta etapa.

Scan de alterações em ficheiros

filecheck funciona com base no snapshot guardado em:

var/security_scan_hashes.json

Na primeira execução:

• é criado um snapshot,
• ainda não existe comparação de alterações,
• o relatório informa sobre a criação da base de referência.

As execuções seguintes reportam alterações dos tipos ADDED, MODIFIED e REMOVED.

São ignorados, entre outros:

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

Scan de malware em ficheiros

malwarecheck analisa os ficheiros da aplicação com base em:

• regras regex com rule_id,
• heurísticas de tokens PHP,
• verificações de URLs por Safe Browsing.

Exemplos de tipos de deteção:

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

Nos relatórios, os motivos são apresentados no formato:

[file.encoded_payload_blob] Encoded payload blob detected

Scan da base de dados

dbcheck analisa tabelas Magento selecionadas:

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

Exemplos de regras:

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

O conteúdo é previamente normalizado através de:

• html_entity_decode,
• rawurldecode,
• normalização de whitespace,
• análise de várias variantes do mesmo conteúdo.

Configuração avançada: allowlists

As allowlists servem para limitar false positives sem desativar todo o módulo.

1. Allowlist de domínios

Campo: kowal_security/general/allowlisted_domains

Formato:

• um domínio por linha, ou
• lista separada por vírgulas.

cdn.example.comstatic.example.org

Efeito:

• URLs destes domínios não serão tratados como suspeitos,
• o Safe Browsing não os irá verificar.

2. Allowlist de ficheiros

Campo: kowal_security/general/allowlisted_file_patterns

Formato:

• caminhos relativos,
• suporte para globs.

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

Efeito: os ficheiros que correspondem ao padrão são totalmente ignorados pelo scan de malware. Esta definição tem um âmbito amplo.

3. Allowlist de padrões da base de dados

Campo: kowal_security/general/allowlisted_db_patterns

Formato:

• frases,
• fragmentos HTML ou JS,
• entradas separadas por uma nova linha ou por vírgulas.

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

Efeito: o registo da base de dados que contenha esse fragmento é ignorado pelo scan DB. Esta definição também tem um âmbito amplo.

4. Allowlist de regras de ficheiros

Campo: kowal_security/general/allowlisted_file_rules

Formato preferencial:

sciezka_lub_glob | rule_id

Exemplo:

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

Compatibilidade retroativa:

• entradas antigas pela etiqueta completa da regra continuam a funcionar,
• as novas entradas devem utilizar rule_id.

Efeito: apenas a regra indicada é silenciada para o caminho indicado, enquanto o restante scan desse ficheiro continua a funcionar.

5. Allowlist de regras da base de dados

Campo: kowal_security/general/allowlisted_db_rules

Formato preferencial:

tabela_lub_* | rule_id

Exemplo:

cms_block | db.inline_script_tag* | db.fetch_or_xhr_loader

Efeito: apenas a regra indicada é silenciada, e as restantes continuam a funcionar para esse registo ou tabela.

Relatórios

Os relatórios podem incluir:

• lista de deteções,
• avaliação de risco,
• indicadores e recomendações,
• candidatos para allowlists após validação manual,
• configuração normalizada de allowlists em JSON.

Sugestões de allowlist nos relatórios

A secção do relatório pode conter entradas do 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

Interpretação:

• zasieg=LOW - candidato mais seguro,
• zasieg=HIGH - silenciamento amplo, apenas após validação rigorosa,
• pewnosc=MEDIUM/HIGH - candidato de configuração mais previsível,
• pewnosc=LOW - requer prudência.

Exportação JSON

O relatório também inclui a secção Znormalizowana konfiguracja allowlist (JSON). É um conjunto pronto e deduplicado de valores para copiar para a configuração.

Modo de utilização recomendado

1. execute manualmente os três scans após a instalação,
2. trate o primeiro filecheck como a criação do snapshot,
3. analise os relatórios e confirme quais deteções são reais,
4. para false positives, utilize primeiro allowlisted_file_rules e allowlisted_db_rules,
5. só quando for necessário, utilize allowlisted_domains, allowlisted_file_patterns e allowlisted_db_patterns,
6. após alterar a configuração, execute novamente o scan CLI adequado e verifique o resultado.

Notas operacionais

• filecheck na primeira execução ainda não reporta alterações como incidente,
• o módulo funciona sem OpenAI e sem Safe Browsing, mas com menor profundidade de análise,
• allowlisted_file_patterns e allowlisted_db_patterns têm impacto amplo e devem ser utilizados com moderação,
• o formato preferencial para allowlists de regras é rule_id, não a etiqueta textual completa.