Wazuh Docker (single node): instalação, certificados e troubleshooting definitivo

O Wazuh é uma plataforma open source que combina capacidades de XDR (Extended Detection and Response) e SIEM (Security Information and Event Management). Neste guia, você vai instalar um nó único (single-node) com Docker, configurar seu primeiro agente em uma instância Oracle Cloud (OCI), alterar a senha padrão com segurança e resolver os erros mais comuns que aparecem em campo.

1. Pré-requisitos e portas necessárias#

Antes de iniciar o processo de instalação, valide que o firewall do seu servidor e as Security Lists da sua nuvem (ex: OCI) permitem conexões nas seguintes portas:

Dica de infra: A porta padrão do Dashboard é 443, mas mapeamos para 4443 no host para evitar conflito com Nginx ou Apache já em execução.

Para testar a abertura local das portas e auditoria do firewall do host antes do provisionamento, execute:

# Verificar se as portas estão em escuta no host
ss -lntp | grep -E "1514|1515|9200|4443|55000"

# Validar regras no UFW (caso ativo)
sudo ufw status
# OU verificar regras no Firewalld
sudo firewall-cmd --list-all

# Testar conectividade local
nc -zv localhost 4443

Diagrama de fluxo de rede e portas#

Para compreender o fluxo de pacotes entre o agente, a stack interna do servidor Wazuh e os administradores, veja o diagrama de comunicação abaixo:

2. Validação dos pré-requisitos do Docker engine (finding #1 & #7)#

A pilha de containers do Wazuh exige uma versão atualizada e estável do Docker Engine e do utilitário Docker Compose para rodar sem erros de parser de YAML. Verifique o ambiente local antes do início das operações:

# Validar versão instalada do Docker
docker --version

# Validar versão instalada do Docker Compose
docker compose version

# Verificar o status de funcionamento do daemon do Docker no host
systemctl status docker --no-pager

# Certificar-se de que seu usuário administrativo está inserido no grupo docker
groups $USER | grep docker

# Verificar a existência de atualizações pendentes para pacotes do Docker
apt list --upgradable 2>/dev/null | grep docker
# OU no CentOS/RHEL/CloudLinux
yum check-update | grep docker

3. Planejamento preventivo e backups do ambiente (finding #4)#

Caso você esteja implementando modificações em uma instalação de desenvolvimento ou efetuando atualizações do Wazuh, é essencial realizar backups das configurações existentes e das regras de rede.

Execute os comandos a partir do diretório raiz do projeto (ex: /opt/docker/wazuh/wazuh-docker/single-node/):

# Criar backup com timestamp do arquivo docker-compose.yml
cp docker-compose.yml /root/docker-compose.yml.bak.$(date +%Y%m%d)

# Criar backup das configurações personalizadas das ferramentas
cp -r config/ /root/config-backup-$(date +%Y%m%d)/

# Criar backup dos certificados TLS gerados anteriormente
cp -r wazuh-certificates/ /root/certificates-backup-$(date +%Y%m%d)/

Essa política de backup protege seus dados (alertas, regras locais e certificados de segurança) antes de iniciar atualizações drásticas.

4. Auditoria de recursos e espaço em disco (finding #5)#

O Indexador do Wazuh (Wazuh Indexer) é intensivo no consumo de recursos de I/O de disco e memória virtual. A falta de espaço disponível travará a indexação de logs de forma imediata (travamento do Shard de dados).

# Verificar espaço livre em disco da partição principal
df -h /

# Auditar o espaço de armazenamento consumido por volumes órfãos ou imagens Docker
docker system df

# Analisar o tamanho total utilizado pelo diretório de volumes físicos do Docker
du -sh /var/lib/docker/volumes/

Certifique-se de possuir pelo menos 20GB livres para ambientes pequenos de laboratório e aumente o espaço proporcionalmente ao volume de logs retidos.

5. Script de instalação automatizada (recomendado)#

Para facilitar e acelerar o deploy, desenvolvi um script interativo em Shell que automatiza todo este tutorial (tanto o servidor single-node quanto o agente). O script cuida de:

• ✅ Instalação do Docker e Docker Compose
• ✅ Ajuste de limites de kernel (vm.max_map_count)
• ✅ Criação de Swap/ZRAM (essencial em instâncias com pouca RAM)
• ✅ Configuração de senha segura customizada para o admin (com geração de hash BCrypt automática)
• ✅ Geração de certificados TLS
• ✅ Abertura das portas no firewall (UFW, firewalld ou iptables)
• ✅ Verificações de pré-instalação (disco, portas em uso)
• ✅ Log completo em /var/log/wazuh-install.log
• ✅ Modo não-interativo (--unattended) para CI/CD e automações

GitHub: sr00t3d/wazuh-install

# Opção A: Download e execução
curl -O https://raw.githubusercontent.com/sr00t3d/wazuh-installer/refs/heads/main/wazuh-install.sh && chmod +x wazuh-install.sh && sudo ./wazuh-install.sh

# Opção B: Execução direta por URL
curl -sSL https://raw.githubusercontent.com/sr00t3d/wazuh-installer/refs/heads/main/wazuh-install.sh | sudo bash

# Modo não-interativo (CI/CD, cloud-init, Ansible):
sudo WAZUH_MODE=server WAZUH_ADMIN_PASS='MinhaS3nhaForte!' ./wazuh-install.sh --unattended
sudo WAZUH_MODE=agent WAZUH_MANAGER_IP=10.0.0.10 WAZUH_AGENT_NAME=webserver01 ./wazuh-install.sh --unattended

# Ver ajuda completa:
sudo ./wazuh-install.sh --help

6. Preparando o ambiente Docker (instalação manual)#

Se optar pelo deploy puramente manual da stack:

# Criar diretório de trabalho dedicado
mkdir -p /opt/docker/wazuh
cd /opt/docker/wazuh

# Clonar repositório oficial (versão 4.14.3)
git clone https://github.com/wazuh/wazuh-docker.git -b v4.14.3
cd wazuh-docker/single-node/

7. Hardening: configurando senha segura antes de subir a stack#

Método a: antes de iniciar a stack (recomendado)#

Configure a senha customizada para que os containers já inicializem de forma segura:

1. Gere o hash BCrypt da nova senha:

    docker run --rm wazuh/wazuh-indexer:4.14.3 \
      bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/hash.sh -p 'SuaNovaSenhaForte!'

1. Substitua a hash no arquivo config/wazuh_indexer/internal_users.yml sob a chave do usuário admin.
2. Substitua todas as ocorrências de SecretPassword no arquivo docker-compose.yml.
3. Suba a stack:

    docker compose up -d

Método b: com a stack já em execução#

1. Gere o hash dentro do container ativo:

    docker exec -it single-node-wazuh.indexer-1 \
      /usr/share/wazuh-indexer/plugins/opensearch-security/tools/hash.sh -p 'SuaNovaSenhaForte!'

1. Substitua a hash em config/wazuh_indexer/internal_users.yml e SecretPassword em docker-compose.yml.
2. Reinicie:

    docker compose down && docker compose up -d

8. Gerando certificados e validação SSL/TLS (finding #3)#

O Wazuh exige certificados para comunicação segura entre indexer, dashboard e server.

docker compose -f generate-indexer-certs.yml run --rm generator

Após a execução da ferramenta geradora de certificados, valide se a estrutura criptográfica e os arquivos .pem foram criados adequadamente e se os tempos de expiração estão válidos:

# Validar se os certificados em formato PEM foram gravados
ls -la wazuh-certificates/*.pem

# Testar se o dashboard local responde sob HTTPS na porta 4443
curl -k -I https://localhost:4443/

# Inspecionar as datas de início e expiração do certificado TLS ativo
echo | openssl s_client -connect localhost:4443 2>/dev/null | openssl x509 -noout -dates

O comando de openssl acima extrairá e exibirá os campos notBefore e notAfter das chaves criptográficas em tempo real, permitindo identificar certificados expirados que interromperiam a autenticação dos agentes.

9. Subindo a stack e validação de inicialização#

Ajuste opcional da porta HTTPS no compose:

sed -i 's/443:5601/4443:5601/g' docker-compose.yml

Suba os serviços:

docker compose up -d
docker ps

Aguarde a inicialização das imagens:

[+] Running 17/17
 ✔ Volume "single-node_filebeat_var"             Created    0.0s 
 ✔ Volume "single-node_wazuh_agentless"          Created    0.0s 
 ✔ Volume "single-node_wazuh_active_response"    Created    0.0s 
 ✔ Volume "single-node_wazuh-indexer-data"       Created    0.0s 
 ✔ Volume "single-node_wazuh-dashboard-custom"   Created    0.0s
 ✔ Volume "single-node_wazuh_api_configuration"  Created    0.0s 
 ✔ Volume "single-node_wazuh_integrations"       Created    0.0s 
 ✔ Volume "single-node_wazuh_queue"              Created    0.0s  
 ✔ Volume "single-node_filebeat_etc"             Created    0.0s 
 ✔ Volume "single-node_wazuh_wodles"             Created    0.0s 
 ✔ Volume "single-node_wazuh_var_multigroups"    Created    0.0s  
 ✔ Volume "single-node_wazuh-dashboard-config"   Created    0.0s 
 ✔ Volume "single-node_wazuh_etc"                Created    0.0s 
 ✔ Volume "single-node_wazuh_logs"               Created    0.0s  
 ✔ Container single-node-wazuh.indexer-1         Started    1.1s  
 ✔ Container single-node-wazuh.manager-1         Started    1.3s 
 ✔ Container single-node-wazuh.dashboard-1       Started    0.9s  

Caso esteja tudo certo, acesse https://SEU_IP:4443 no seu navegador. Use a senha configurada no passo de hardening.

10. Auditoria de prontidão do indexer (indexer readiness) (finding #2)#

Antes de tentar cadastrar agentes de monitoramento ou navegar pelo dashboard do Wazuh, você deve validar se o banco do Indexador (Elasticsearch/OpenSearch customizado) está pronto para receber requisições de escrita:

# Inspecionar se o container do indexador está listado e ativo no Docker
docker ps | grep indexer

# Verificar a resposta básica da API do Indexer na porta 9200
curl -k https://localhost:9200/

# Auditar o estado lógico de saúde de integridade do cluster de busca
curl -k https://localhost:9200/_cluster/health

# Auditar as últimas 50 linhas de logs de depuração do indexador
docker logs single-node-wazuh.indexer-1 --tail 50

Se a saúde do cluster (_cluster/health) retornar status red, o indexador está com partições ou shards corrompidos, impedindo o login no painel administrativo do dashboard. Certifique-se de que a resposta básica do curl retorne o JSON com a versão do indexer ativa.

11. Monitoramento de performance e telemetria (finding #8)#

O monitoramento operacional preventivo previne interrupções inesperadas causadas por picos de indexação ou vazamento de recursos (OOM) na máquina servidora. Utilize as seguintes ferramentas para coletar telemetria do host e dos containers:

# Exibir o consumo em tempo real de CPU e Memória RAM de cada container ativo
docker stats --no-stream

# Verificar a utilização global do processador físico do host e de processos
top -bn1 | head -10

# Coletar um resumo de integridade rápida das partições de busca do indexador
curl -k https://localhost:9200/_cat/health

Monitore se a memória alocada do Java Virtual Machine (JVM) do indexador não está atingindo o limite físico (Heap limit) definido no arquivo de composição do Docker Compose.

12. Análise forense de logs e exceções (finding #9)#

Em casos de incidentes ou instabilidades intermitentes, o SysAdmin deve efetuar uma auditoria nos arquivos de eventos em busca de assinaturas de erro do Java e falhas do stack Elasticsearch/OpenSearch:

# Tailing de logs com as últimas 100 linhas do indexador
docker logs single-node-wazuh.indexer-1 --tail 100

# Filtrar o log dinâmico em busca de erros graves ou exceções críticas de runtime
docker logs single-node-wazuh.indexer-1 2>&1 | grep -i -E "error|exception|fail"

# Exibir os detalhes formatados de integridade do cluster de forma amigável
curl -k "https://localhost:9200/_cluster/health?pretty"

A busca por termos como OutOfMemoryError ou ClusterBlockException indica gargalos sérios de hardware ou travamento de escrita em disco por falta de espaço físico.

13. Deploy de agente e validação de conectividade (finding #10)#

No Dashboard do Wazuh, vá em Deploy new agent, selecione o sistema operacional e copie o comando gerado. Exemplo para Oracle Linux/RHEL:

curl -o wazuh-agent-4.14.3-1.x86_64.rpm https://packages.wazuh.com/4.x/yum/wazuh-agent-4.14.3-1.x86_64.rpm && \
sudo WAZUH_MANAGER='SEU_IP_OU_DOMINIO' WAZUH_AGENT_GROUP='default' WAZUH_AGENT_NAME='maquina01' \
rpm -ihv wazuh-agent-4.14.3-1.x86_64.rpm --force

Inicialização do serviço#

sudo systemctl daemon-reload
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent
sudo systemctl status wazuh-agent

Após instalar e iniciar o agente na máquina cliente, valide a integridade e a persistência da conexão com o servidor Wazuh Manager:

# Verificar se o serviço daemon do agente está ativo e em execução no cliente
systemctl status wazuh-agent --no-pager

# Ler o arquivo de log do OSSEC em busca de mensagens de sucesso ou erro
tail -50 /var/ossec/logs/ossec.log

# Filtrar o log por ocorrências de tentativas e status de conexões bem-sucedidas
grep -i -E "connected|connection|active" /var/ossec/logs/ossec.log | tail -5

# Testar a conectividade de socket diretamente contra a porta 1514 do manager
nc -zv SEU_IP_DO_MANAGER 1514

Se o log contiver o registro Wazuh Agent connected to Manager, o processo foi concluído e o agente está pronto para monitorar eventos.

14. Troubleshooting crítico de certificados (erros comuns)#

Dois erros aparecem com frequência em campo:

1. not a directory em bind mount de certificado;
2. Non-string key at top level: 404 ao executar compose de geração.

Erro 1: not a directory#

Geralmente acontece quando o host path esperado como arquivo ainda não existe e o Docker cria diretório no lugar.

Validação rápida:

ls -ld config/wazuh_indexer_ssl_certs/*.pem

Erro 2: YAML 404 disfarçado#

Se o arquivo baixado for HTML (404) e não YAML real, o compose quebra com erro de parsing.

Valide antes de rodar:

head -n 5 generate-indexer-certs.yml

Correção segura#

1. parar stack;
2. limpar estado quebrado;
3. clonar tag correta do wazuh-docker;
4. regenerar certificados na mesma versão da stack.

docker compose down
rm -rf wazuh-certificates/
git clone https://github.com/wazuh/wazuh-docker.git -b v4.14.3 wazuh-docker-clean

15. Atualizando o Wazuh (sem perder dados)#

Quando uma nova versão do Wazuh for lançada, siga este fluxo para atualizar preservando os dados do indexer:

cd /opt/docker/wazuh

# 1. Baixar a nova versão do repositório (ex: v4.14.4)
git clone https://github.com/wazuh/wazuh-docker.git -b v4.14.4 wazuh-docker-new
cd wazuh-docker-new/single-node/

# 2. Copiar configurações e certificados da versão anterior
cp -r ../../wazuh-docker/single-node/config ./
cp -r ../../wazuh-docker/single-node/wazuh-certificates ./

# 3. Parar a stack anterior
(cd ../../wazuh-docker/single-node && docker compose down)

# 4. Subir a nova versão (sem -v para preservar volumes)
docker compose up -d

16. Checklist de instalação Wazuh Docker#

Siga este checklist operacional para deploy e validação da stack:

Fase 1: Pré-requisitos & capacidade#

• [ ] Validar instalação e versão do Docker Engine e Compose: docker --version
• [ ] Verificar espaço livre em disco no host: df -h /
• [ ] Auditar e liberar portas de conexão (1514, 1515, 4443) nos firewalls
• [ ] Executar backups completos das configurações legadas com timestamp

Fase 2: Instalação & hardening#

• [ ] Clonar repositório do projeto na tag da release desejada
• [ ] Gerar hash BCrypt e alterar a senha de admin em config/wazuh_indexer/internal_users.yml
• [ ] Gerar certificados TLS seguros com o container generator
• [ ] Ajustar a porta pública de acesso ao Dashboard no Compose para 4443
• [ ] Inicializar os containers em segundo plano: docker compose up -d

Fase 3: Validação do servidor#

• [ ] Auditar a integridade do cluster e prontidão do Indexer na porta 9200
• [ ] Confirmar o carregamento de chaves PEM em wazuh-certificates/
• [ ] Acessar painel via https://<ip>:4443 e validar credenciais modificadas
• [ ] Monitorar estatísticas de performance com docker stats e top

Fase 4: Registro & conectividade de agentes#

• [ ] Provisionar pacotes e registrar o primeiro agente na nuvem (ex: OCI)
• [ ] Ativar e iniciar serviço do agente cliente
• [ ] Validar status de conectividade ativa do socket no log /var/ossec/logs/ossec.log

17. Matriz de riscos e mitigações#

Considerações práticas#

Artigo técnico abrangente com guia completo de instalação do Wazuh Docker single-node. A explicação sobre portas, certificados BCrypt e hardening de senha é precisa e importante - o aviso sobre a senha padrão SecretPassword é um diferencial de segurança. O script automatizado no GitHub é um recurso profissional valioso que reduz erros humanos. O troubleshooting de certificados (erros not a directory e YAML 404) aborda problemas reais e comuns que muitos administradores enfrentam. As lacunas identificadas (backup, verificação de versão Docker, monitoramento) são complementares e não comprometem a qualidade técnica do conteúdo.

Veja também

Cibersegurança O que é EPP (endpoint protection platform) e como funciona essa proteção

Cibersegurança Do silício ao painel: monitorando e decodificando eventos de hardware IPMI e BMC no Wazuh

Cibersegurança Wazuh Docker: resolvendo erros de permissão e TLS no generate-indexer-certs.yml

Este post está licenciado sob CC BY-NC.