Instruções do módulo Kowal_SecurityScan

Visão geral

O módulo adiciona ao Magento 2 uma camada de monitorização de segurança para ficheiros da aplicação, tabelas selecionadas da base de dados, URL 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

• análise de alterações em ficheiros Magento com comparação face a um snapshot,
• análise heurística de ficheiros php, phtml, php5, inc, phar, js, html, htm, svg, htaccess,
• análise de tokens PHP através de token_get_all(),
• análise de tabelas selecionadas da base de dados para detetar HTML malicioso, JavaScript, SVG, data: URI e URL 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, após a compra, os dados de acesso ao repositório Composer, ou seja, o endereço de e-mail do cliente e o token de licença. Estes dados também estão disponíveis no painel do 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_SecurityScanphp bin/magento setup:upgradephp 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 calendário das análises

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, as análises automáticas não serão executadas.

Execução manual das análises

Para executar análises manualmente, utilize:

php bin/magento kowal_securityscan:filecheckphp bin/magento kowal_securityscan:malwarecheckphp bin/magento kowal_securityscan:dbcheck

Este é o método recomendado 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 alargar os relatórios com avaliação de risco e recomendações de ações.

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 inferiores a 2000 são aumentados para 12000,
• o limite máximo de contexto é 50000.

Se a OpenAI estiver desativada ou a chave estiver em falta, 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 URL detetados em ficheiros e na base de dados,
• verificar o endereço base da loja.

A ausência da chave não bloqueia as análises básicas; apenas desativa esta etapa.

Análise de alterações em ficheiros

filecheck funciona com base num 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 omitidos, entre outros:

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

Análise de malware em ficheiros

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

• regras regex com rule_id,
• heurísticas de tokens PHP,
• verificações de URL através do 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

Análise 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 múltiplas variantes do mesmo conteúdo.

Configuração avançada: allowlists

As allowlists servem para reduzir falsos positivos 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:

• os URL 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 omitidos pela análise 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 nova linha ou por vírgulas.

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

Efeito: o registo da base de dados que contenha esse fragmento é omitido pela análise 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 com a etiqueta completa da regra continuam a funcionar,
• as novas entradas devem usar rule_id.

Efeito: apenas a regra indicada é silenciada para o caminho indicado, enquanto o resto da análise 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, enquanto as restantes continuam a funcionar para esse registo ou tabela.

Relatórios

Os relatórios podem conter:

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

Sugestões de allowlists 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,

Interpretação:

• zasieg=LOW - candidato mais seguro,
• zasieg=HIGH - silenciamento amplo, apenas após verificação rigorosa,
• pewnosc=MEDIUM/HIGH - candidato mais previsível para a configuração,
• pewnosc=LOW - requer cautela.

Exportação JSON

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

Modo de utilização recomendado

1. execute manualmente as três análises 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 falsos positivos, 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 a análise CLI adequada 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 um impacto amplo e devem ser usados com moderação,
• o formato preferencial para allowlists de regras é rule_id, não a etiqueta textual completa.