Como Instalar Wazuh Docker Single Node e Agentes na Nuvem: Passo a Passo

Como Instalar Wazuh Docker Single Node e Agentes na Nuvem: Passo a Passo#

O Wazuh é uma plataforma open source que combina capacidades de XDR (Extended Detection and Response) e SIEM (Security Information and Event Management). Neste guia, mostro o passo a passo completo para instalar um nó único (single node) com Docker, gerar certificados TLS, configurar o primeiro agente em uma instância na nuvem (OCI), aplicar o hardening de senhas do painel e diagnosticar os erros mais frequentes de inicialização.

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 mapeei 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:

[ Agente Wazuh (Host Cliente) ]
       │
       ├── 1514/TCP (Envio de logs) ───────► [ Wazuh Manager ] ─── 9200/TCP (Indexer API) ──► [ Wazuh Indexer ]
       │                                            ▲                                               ▲
       └── 1515/TCP (Registro de agentes) ──────────┘                                               │
                                                                                                9200/TCP
                                                                                                    │
[ Administrador (Navegador Web) ] ─── 4443/TCP (Painel HTTPS) ───► [ Wazuh Dashboard ] ────────────┘

2. Validação dos pré-requisitos do Docker engine#

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#

Caso esteja implementando modificações em laboratório ou executando upgrades do Wazuh, é fundamental realizar backups das configurações e regras existentes.

Execute os comandos a partir da pasta raiz do projeto (ex: /opt/docker/wazuh/wazuh-docker/single-node/):

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

# Criar cópia de segurança das configurações customizadas de ferramentas
cp -r config/ /root/config-backup-$(date +%Y%m%d)/

# Criar cópia de segurança dos certificados TLS gerados anteriormente
cp -r wazuh-certificates/ /root/certificates-backup-$(date +%Y%m%d)/

Essa política de cópia previne a perda de dados locais (alertas, regras locais e chaves de segurança) antes de atualizações críticas.

4. Auditoria de recursos e espaço em disco#

O Wazuh Indexer é intensivo no consumo de operações de I/O em disco e memória virtual. A falta de espaço causará interrupção imediata da indexação de logs (bloqueio de Shards).

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

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

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

Certifique-se de possuir pelo menos 20 GB 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 simplificar e acelerar o deploy, desenvolvi um script Shell interativo que automatiza todo este guia (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

Se preferir fazer a instalação passo a passo manualmente, continue lendo as seções abaixo.

6. Clonando o repositório oficial#

Clone o repositório oficial do Wazuh Docker e acesse o diretório single-node:

git clone https://github.com/wazuh/wazuh-docker.git -b v4.14.3 --depth=1
cd wazuh-docker/single-node

Dica de versão: Sempre use uma tag estável (ex: v4.14.3). Clonar a branch master pode trazer código em desenvolvimento com dependências quebradas.

7. Hardening: alterando a senha padrão do admin#

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

1. Gere o hash BCrypt da nova senha:

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

1. Substitua o hash no arquivo config/wazuh_indexer/internal_users.yml sob a chave do usuário admin.
2. Atualize também a variável INDEXER_PASSWORD no docker-compose.yml para refletir a nova senha em texto plano (necessária para que Dashboard e Manager se autentiquem no Indexer).

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

Se você já subiu a stack e precisa alterar a senha:

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 o 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#

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 no disco:

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

# Inspecionar as datas de início e expiração do certificado gerado diretamente no arquivo
openssl x509 -in wazuh-certificates/wazuh.indexer.pem -noout -dates

O comando de openssl acima valida os campos notBefore e notAfter diretamente no arquivo gravado no disco, confirmando que as chaves criptográficas estão íntegras antes de inicializar a stack.

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  

Agora que a stack está no ar, valide a resposta HTTPS e o certificado servido pelo Dashboard:

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

# Inspecionar as datas do certificado TLS ativo servido na porta 4443
echo | openssl s_client -connect localhost:4443 2>/dev/null | openssl x509 -noout -dates

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)#

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, há shards primários indisponíveis (não alocados) — causas comuns: disco cheio, certificados/nomes de nó incorretos ou bootstrap incompleto. Já o status yellow indica cluster funcional, mas com réplicas pendentes (comum em nós únicos single-node). Antes de qualquer coisa, cheque espaço com df -h / e os logs do indexer (passo acima). 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#

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#

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#

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 e remover certificados inconsistentes;
2. clonar a tag correta em diretório limpo;
3. copiar configurações personalizadas;
4. regenerar certificados na mesma versão da stack;
5. inicializar os containers.

# 1. Parar a stack e remover certificados inconsistentes
docker compose down
rm -rf wazuh-certificates/

# 2. Clonar a tag correta em diretório limpo
git clone https://github.com/wazuh/wazuh-docker.git -b v4.14.3 wazuh-docker-clean
cd wazuh-docker-clean/single-node/

# 3. Copiar configurações personalizadas
cp -r ../../wazuh-docker/single-node/config ./

# 4. Regenerar os certificados na versão idêntica da stack
docker compose -f generate-indexer-certs.yml run --rm generator

# 5. Inicializar os containers
docker compose up -d

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. Re-aplicar customizações no novo docker-compose.yml (porta 4443 e credenciais)
sed -i 's/443:5601/4443:5601/g' docker-compose.yml
# (confira e re-aplique INDEXER_PASSWORD ou outras variáveis caso modificadas)

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

# 5. 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#

Conclusão#

Neste guia cobri o ciclo completo de implantação do Wazuh single-node com Docker: planejamento de capacidade, hardening preventivo de senhas com BCrypt, geração segura de certificados e os diagnósticos para os erros mais frequentes de inicialização e montagem. Se o seu agente cliente não conseguir estabelecer conexão de imediato, comece checando os registros em /var/ossec/logs/ossec.log e siga as recomendações da matriz de riscos acima para isolar a causa raiz.

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.