Honeypot Cowrie e Grafana usando Terraform no DigitalOcean

Vídeo de Demonstração

Índice

• Índice
• Visão Geral do Sistema
• Tecnologias
• Estrutura do Diretório do Projeto
• Requisitos de Hardware
• Instalação e Configuração
• Gerenciamento de Estado do Terraform
• Pipeline CI/CD
• Arquitetura do Sistema
• Observações
• Uso
• Documentação do Projeto
  • Design de Arquitetura e Compensações
  • Passo a Passo da Execução do Sistema
  • Problemas e Limitações Encontradas
  • Melhorias Futuras
• Considerações de Segurança
• Contribuidores
• Licença

Visão Geral do Sistema

Uma pilha de honeypot SSH/Telnet implantada em um droplet da DigitalOcean usando Terraform. Os ataques são capturados pelo Cowrie, armazenados no Loki e visualizados no Grafana com um mapa-múndi ao vivo das origens dos ataques.

Tecnologias

• DigitalOcean
• Terraform
• Docker
• Cowrie
• Loki
• Grafana
• Promtail
• DB-IP (City Lite download)

Estrutura do Diretório do Projeto```

honeypot/ ├── cowrie/ │ └── etc/ │ ├── cowrie.cfg # Cowrie honeypot configuration │ └── userdb.txt # Accepted and rejected fake credentials ├── geoip/ │ └── .gitkeep # Placeholder - MMDB files are gitignored ├── grafana/ │ ├── provisioning/ │ │ ├── dashboards/ │ │ │ ├── dashboards.yml # Provisioning: dashboard provider │ │ │ └── honeypot-dashboard.json # Pre-built Attack Monitor dashboard │ │ └── datasources/ │ │ └── loki.yml # Auto-provisioned Loki datasource │ └── grafana.ini # Grafana server settings ├── loki/ │ └── config.yml # Loki single-binary config and retention ├── promtail/ │ └── config.yml # Promtail scrape and GeoIP pipeline ├── scripts/ │ ├── geoip-update.sh # Download or refresh GeoIP database │ └── setup-firewall.sh # Host UFW rules for honeypot ports ├── terraform/ │ ├── templates/ │ │ ├── cloud-init.yaml.tftpl # Droplet first-boot script (Terraform-templated) │ │ └── env.tftpl # .env lines embedded via Terraform │ ├── backend.tf # Terraform backend config │ ├── main.tf # Droplet, SSH key, firewall, cloud-init │ ├── outputs.tf # IPs and helpful post-apply values │ ├── terraform.tfvars.example # Example variable values (copy to terraform.tfvars) │ ├── variables.tf # Terraform input variables │ └── versions.tf # Terraform and provider version constraints ├── .env.example # Example environment file for manual setup ├── .gitignore # Ignored paths and files ├── .gitlab-ci.yml # CI/CD pipeline: fmt, validate, Checkov ├── docker-compose.yml # Docker Compose file for the honeypot stack ├── LICENSE # GPLv2 license ├── manual-deployment.sh # Legacy VM bootstrap without Terraform └── README.md # Project documentation

## Requisitos de Hardware

> Nota: Estes requisitos são baseados no plano Basic Droplet da DigitalOcean a partir de maio de 2026 e são os requisitos mínimos para executar o projeto.

- Provedor: DigitalOcean
- Plano: Basic Droplet - 1 vCPU Intel
- RAM: 1 GB (+2 GB de swap)
- Armazenamento: 35 GB SSD NVMe
- SO: Ubuntu 24.04 LTS

## Instalação e Configuração

>Nota: Após a instalação, é recomendado abrir um novo terminal e verificar se ainda é possível fazer SSH na porta `ADMIN_SSH_PORT` (Padrão: 2022) antes de fechar sua sessão original.

### Implantação com Terraform (Recomendado)

1. Crie um token da API do DigitalOcean com permissões de leitura/escrita:

- Faça login no DigitalOcean e navegue até Account > API > Tokens > Generate New Token.
- Nomeie seu token (exemplo: "Cowrie Honeypot") e selecione permissões "Full Access".
- Clique em "Generate Token" e copie o valor do token para um local seguro (não será possível vê-lo novamente).

2. Crie um par de chaves SSH em sua máquina local e copie o caminho da chave pública.

3. Vá para o diretório `terraform` e copie e edite o arquivo de variáveis:

> Nota: `do_token`, `ssh_public_key_path` e `grafana_admin_password` devem ser configurados no mínimo em `terraform.tfvars` antes de aplicar.```bash
cd terraform
cp terraform.tfvars.example terraform.tfvars

4. Aplique a configuração e inicie a implantação:

Nota: O Terraform deve estar instalado na sua máquina local. Visite Guia de Instalação do Terraform para obter instruções.```bash terraform init # Initialize Terraform and download providers terraform apply

5. Se Teste - Reimplantar com substituição:```bash
terraform apply -replace="digitalocean_droplet.honeypot" 

6. Limpeza - Destrua a infraestrutura quando terminar:```bash terraform destroy

### Implantação Manual (Legado)

1. Crie um droplet na DigitalOcean com os requisitos de hardware acima e sua chave SSH.

2. Faça SSH no droplet ou use o console web da DigitalOcean e execute os seguintes comandos:```bash
ssh root@<your-droplet-ip> # If using DigitalOcean web console, skip this command
git clone https://gitlab.com/Oseguera12/cowrie-honeypot-digitalocean.git /opt/honeypot
cd /opt/honeypot
cp .env.example .env
nano .env
bash manual-deployment.sh

Gerenciamento de Estado do Terraform

Nota: Por padrão, o Terraform escreve o estado em terraform/terraform.tfstate na sua máquina local. Este arquivo contém valores de saída sensíveis (IP do droplet, senha do Grafana, impressão digital da chave SSH) e nunca deve ser commitado. O .gitignore cobre *.tfstate e *.tfstate.*.

Riscos do estado local:

• Perdido se a máquina for perdida ou o arquivo for deletado
• Não pode ser compartilhado entre membros da equipe
• Sem bloqueio — duas execuções apply concorrentes podem corromper o arquivo

Para qualquer coisa além de um laboratório pessoal, mude para um backend remoto. O terraform/backend.tf contém uma configuração comentada do DigitalOcean Spaces (compatível com S3).

Para ativar o backend remoto:

1. Crie um bucket Spaces na sua conta DigitalOcean
2. Gere uma chave de acesso Spaces em API > Spaces Keys
3. Exporte as chaves como variáveis de ambiente (não as coloque no terraform.tfvars): ```bash export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY=
   root@kitploit:~

4. Descomente o bloco backend "s3" em terraform/backend.tf e preencha o nome do seu bucket e o endpoint da região.
5. Execute terraform init -migrate-state para mover o estado local existente para o Spaces.

Pipeline CI/CD

O arquivo .gitlab-ci.yml executa três jobs a cada push em um único estágio validate:

Nota: terraform:fmt e terraform:validate bloqueiam o pipeline em caso de falha. checkov:scan está configurado como allow_failure: true porque alguns achados são compromissos intencionais. Suprima achados específicos aceitáveis com comentários inline # checkov:skip=CKXXX em vez de desabilitar o job inteiramente.

Riscos aceitos conhecidos

CKV_DIO_4 ("Garanta que o ingress do firewall não esteja totalmente aberto") dispara uma vez contra todo o recurso digitalocean_firewall. Ele é suprimido com um único comentário # checkov:skip=CKV_DIO_4: colocado dentro do bloco do recurso em terraform/main.tf. A tabela abaixo documenta por que cada porta aberta é intencional.

Arquitetura do Sistema```mermaid

flowchart TB internet((Internet))

subgraph tf["Terraform"] fw[DigitalOcean Cloud Firewall] droplet[Ubuntu 24.04 droplet] fw --> droplet end

subgraph compose["Docker Compose on droplet"] cowrie["Cowrie honeypot — SSH on port 22, Telnet on port 23"] promtail[Promtail with GeoIP labels] loki[Loki log store] grafana["Grafana — host :3000"] cowrie -->|JSON logs from ./data/cowrie-logs| promtail --> loki --> grafana end

internet -->|22/23 honeypot| fw internet -->|Admin SSH :2022| fw internet -->|Grafana :3000| fw droplet --> compose

## Observações

Dados capturados durante 5 dias de implantação ao vivo (2026-05-05 a 2026-05-09):

| Métrica                    | Valor  |
|---------------------------|--------|
| Total de conexões         | 41.700 |
| Tentativas de login       | 15.400 |
| Logins bem-sucedidos      | 868    |
| Comandos executados       | 836    |
| Arquivos baixados         | 6      |
| Países de origem únicos   | 106    |

### Principais países atacantes

| País             | Conexões |
|-----------------|----------|
| Alemanha         | 9.768    |
| Países Baixos    | 9.110    |
| Estados Unidos   | 7.706    |
| Reino Unido      | 3.858    |
| Singapura        | 1.770    |
| Bélgica          | 1.422    |

### Padrões de credenciais

O nome de usuário mais comum tentado foi `root` com 3.866 tentativas, seguido por
`admin` (728) e `user` (494), refletindo scanners automatizados que visam
credenciais padrão e contas de serviço conhecidas. A senha mais comum foi
`123456` (1.480 tentativas) seguida por `123` e `12345`, consistente com
ferramentas de força bruta baseadas em dicionário.

### Comportamento do atacante dentro do shell falso

868 tentativas de login foram bem-sucedidas contra o conjunto de credenciais falsas. Dessas sessões,
836 comandos foram executados. O comando mais comum foi `uname -s -v -n -r -m`
(360 execuções) — um comando padrão de identificação de sistema executado por scripts
automatizados de pós-exploração para identificar o SO e a arquitetura alvo antes de
implantar um payload. Outros comandos observados incluíram `export HISTFILE=/dev/null`
para desabilitar o registro do histórico do shell, e `export HISTSAVE=/dev/null`, indicando
que os atacantes estavam ativamente tentando encobrir seus rastros mesmo dentro do que acreditavam
ser um sistema comprometido.

### Principal conclusão

O volume de tráfego de varredura automatizada — 41.700 conexões em 5 dias de 106
países — confirma que qualquer serviço SSH publicamente acessível enfrenta constantes
tentativas de força bruta dentro de horas após a exposição. O padrão comportamental de
executar imediatamente `uname` seguido de comandos de supressão de histórico é consistente
com frameworks automatizados de pós-exploração operando com envolvimento humano mínimo.

## Uso

### Usando o Dashboard do Grafana

> Nota: As credenciais do dashboard são definidas em terraform.tfvars ou .env (para implantação manual)

O dashboard pode ser acessado em:```
http://<your-droplet-ip>:3000

Faça login com admin / <GRAFANA_ADMIN_PASSWORD>.

Credenciais aceitas pelo honeypot Cowrie

cowrie/etc/userdb.txt - contém as credenciais aceitas para o honeypot.

• Edite este arquivo para ajustar as credenciais do honeypot

• Logins aceitos colocam o atacante em um shell falso onde todos os comandos são registrados

• Entradas rejeitadas são registradas como tentativas falhas

Documentação do Projeto

Esta seção detalha as decisões tomadas e os problemas encontrados durante o desenvolvimento deste projeto. Serve como uma reflexão sobre o processo de desenvolvimento do projeto e as lições aprendidas. Pule para Considerações de Segurança se você só quiser saber como usar o projeto.

Decisões de Arquitetura e Trade-offs

Por que Hospedagem em Nuvem?

• Honeypots são projetados para serem altamente disponíveis para capturar e analisar dados 24 horas por dia. Embora o honeypot pudesse ser implantado em uma máquina local usando máquinas virtuais ou contêineres, manter essa máquina online e acessível 24 horas por dia não é prático. A hospedagem em nuvem oferece uma solução mais prática e confiável para hospedar o honeypot e capturar dados continuamente.
• Além disso, como a hospedagem em nuvem permite selecionar recursos e serviços específicos, é mais fácil criar e manter uma base de código que pode ser implantada e expandida. Qualquer pessoa interessada em implantar seu próprio honeypot pode fazê-lo sem etapas extras, desde que o projeto funcione e o ambiente provisionado corresponda ao que o projeto espera.

Por que DigitalOcean?

• Embora outros provedores como AWS, GCP e Azure estejam disponíveis, a DigitalOcean oferece uma opção mais acessível para este projeto. Como um honeypot deve permanecer online e enviar dados para dentro e para fora do droplet 24 horas por dia, o modelo de preços da DigitalOcean ajudou a manter os custos previsíveis. Isso não leva em conta as promoções de outros provedores, como créditos gratuitos ou descontos para novos usuários ou compromissos de longo prazo.

Por que Terraform?

• A alternativa, manual-deployment.sh, é para usuários que não têm experiência com Terraform ou preferem não usá-lo. Esse caminho requer provisionar um droplet, conectar-se a ele, clonar o repositório e executar o script. O Terraform permite iteração mais rápida: edite a base de código e reimplante sem repetir cada etapa manual a partir da sua máquina local. Também facilita a desmontagem da infraestrutura e o recomeço. Se o projeto crescer de um único honeypot para uma honeynet, o Terraform escala de forma mais limpa do que o provisionamento manual ou o script legado sozinho.

Por que Cowrie?

• Cowrie é um honeypot de interação média bem conhecido e ativamente mantido. Pode usar mais recursos do que armadilhas mais leves, mas seus recursos e ajuste com o restante da pilha o tornaram uma escolha natural. Outros honeypots poderiam ser substituídos para casos de uso específicos, embora muitos não sejam mantidos ou precisem de ainda mais recursos.

Por que Loki?

• A principal restrição foi o hardware: agregação de logs e pesquisa em um droplet de 1 GB de RAM com vários outros serviços em execução. Elasticsearch era pesado demais. Graylog ainda depende do Elasticsearch internamente e não funcionaria adequadamente dentro dos limites. Outras opções consumiam muitos recursos semelhantes. Grafana Loki correspondeu à pilha e ficou dentro do orçamento, exceto sob consultas muito pesadas. Alguns recursos de consulta foram sacrificados: se os dashboards puxam muitos dados, o Loki fica lento, a UI parece não responder e o honeypot pode perder ou atrasar dados.

Por que Grafana?

• Originalmente considerei um painel personalizado, mas o Grafana é completo, personalizável e bem documentado, o que acelerou a configuração para que eu pudesse me concentrar na coleta e envio de logs. Não é tão leve quanto uma UI personalizada mínima, mas após uma pequena atualização do droplet, funciona confortavelmente dentro dos limites de hardware. Outras ferramentas com dashboards pré-construídos consumiriam mais recursos sem ganhos claros para este caso de uso.

Por que Promtail?

• Promtail é o remetente de logs estabelecido para Loki (Grafana Alloy é o sucessor mais novo). Promtail é leve em RAM e suporta estágios de pipeline (análise JSON, GeoIP, rótulos) que correspondem a este projeto. Alternativas como Fluentd ou Logstash eram pesadas demais para um droplet de 1 GB.

Por que GeoIP?

• Mapas de ataque precisam de contexto de cidade e país a partir de IPs de origem. O projeto usa DB-IP City Lite via scripts/geoip-update.sh: sem conta ou chave de API, o que mantém a implantação simples para qualquer pessoa que clone o repositório. O estágio GeoIP embutido do Promtail lê o arquivo MMDB local e adiciona rótulos para o painel Geomap do Grafana.

Passo a Passo da Execução do Sistema

Visão geral passo a passo do que ocorre quando o honeypot é configurado usando Terraform ou o script de implantação manual.

Terraform (recomendado)

Na sua máquina:

1. Configure terraform/terraform.tfvars: token da API, caminho da chave pública SSH, senha do Grafana, URL/ramo do repositório, manage_do_firewall opcional
2. Execute terraform init: instala o provedor DigitalOcean localmente
3. Execute terraform apply: Terraform constrói um plano e depois cria ou atualiza recursos

No DigitalOcean:

4. A chave pública SSH é enviada para sua conta
5. O droplet é criado a partir das suas variáveis do Terraform:
   • Imagem (Ubuntu), tamanho e região vêm de droplet_image, droplet_size, region, etc.
   • A chave SSH do passo 4 é anexada
   • user_data é definido como o cloud-init renderizado: na primeira inicialização, a VM obtém a porta SSH de administração, git repo_url / repo_branch e uma cópia codificada em base64 do .env gerado (senha do Grafana e ADMIN_SSH_PORT de env.tftpl)
6. Firewall na nuvem (apenas quando manage_do_firewall é verdadeiro):
   • Terraform cria um firewall DigitalOcean e o associa a este droplet
   • TCP de entrada: sua porta SSH de administração, 22, 23 e 3000 (veja terraform/main.tf)
   • Saída: TCP/UDP amplo e ICMP para que o droplet possa atualizar pacotes, puxar imagens e baixar dados GeoIP

No droplet, o cloud-init é executado automaticamente:

7. Cloud-config: package_update / package_upgrade, depois instala os pacotes listados (curl, git, ufw, …). No início da inicialização, write_files cria /root/honeypot.env (o env.tftpl renderizado pelo Terraform como base64: senha do Grafana, ADMIN_SSH_PORT, etc.)
8. Script de inicialização runcmd (ordem em terraform/templates/cloud-init.yaml.tftpl): define iptables / ip6tables para backends legados
9. Swap: arquivo de 2 GB se ausente (/swapfile, fstab, swappiness)

Dentro do Docker Compose:

18. Loki inicia e deve passar em sua verificação de saúde (/ready na porta 3100 dentro do contêiner; no host apenas 127.0.0.1:3100)
19. Promtail e Grafana aguardam Loki ficar saudável (depends_on em docker-compose.yml) e depois iniciam
20. Cowrie pode iniciar independentemente: publica as portas do host 22 e 23 no contêiner e escreve logs JSON em data/cowrie-logs para o Promtail

Configuração Manual (legado)

O usuário cria a VM, faz SSH e executa o script a partir do repositório clonado.

manual-deployment.sh faz o seguinte:

1. Carrega e valida .env
2. Atualização do sistema: apt update e apt upgrade
3. Instala pacotes: ferramentas mais ufw e iptables
4. Configura swap: arquivo de 2 GB se ausente
5. Instala Docker: Engine + plugin Compose, ativa serviços
6. Configura SSH: sshd na ADMIN_SSH_PORT e desativa ssh.socket
7. Configura firewall: scripts/setup-firewall.sh
8. Configura GeoIP: scripts/geoip-update.sh e cron mensal
9. Inicia a pilha: docker compose pull / up -d, então o script aguarda verificações de saúde do Loki e Grafana e imprime um resumo

Problemas Encontrados

Limitações de Hardware

• Recursos de hardware limitados resultaram em desempenho lento e timeouts ocasionais. Isso impactou o painel que depende da capacidade de consultar o banco de dados rapidamente em intervalos definidos pelo usuário, às vezes com vários dispositivos acessando o painel ao mesmo tempo.

Soluções Consideradas:

• Escalar verticalmente para mais recursos
• Painel personalizado com menos painéis para reduzir a carga no banco de dados
• Limitar o número de dispositivos que podem acessar o painel ao mesmo tempo
• Agregar logs em um banco de dados separado para o painel ler, reduzindo a pressão sobre o banco de dados principal

Resolução:

• Escalou para um droplet um pouco maior com melhor desempenho

Trade-offs:

• Embora o custo tenha aumentado cerca de $1-2 por mês, os recursos disponíveis dobraram. O acesso a armazenamento SSD NVMe e mais RAM em relação ao Droplet Básico permitiu um painel mais estável e com melhor desempenho. Isso evitou ter que gastar tempo criando um painel personalizado com menos painéis e uma experiência menos responsiva.

Lições Aprendidas:

• Obter o máximo de recursos possível dentro do orçamento aproveitando promoções, descontos e faixas de preço. A diferença entre o droplet mais básico e um pequeno aumento no custo resultou na duplicação dos recursos disponíveis, o que economizou tempo ao permitir um produto mais completo. Além disso, colocar o honeypot em funcionamento mais cedo significou capturar e analisar dados mais cedo.

Problemas de Timeout

• Ao tentar fazer SSH no droplet para acesso de administração, as conexões expiravam. Separadamente, docker compose up falhava porque a porta 22 já estava em uso e não podia ser vinculada pelo Cowrie.

Soluções Consideradas:

• sshd estava mal configurado ou ouvindo na porta errada
• As regras de firewall estavam bloqueando a porta SSH de administração após ela ser movida
• Outro processo já estava segurando a porta 22

Resolução:

• Corrigiu a ordem das operações: sshd é movido para ADMIN_SSH_PORT (padrão 2022) e reiniciado primeiro, depois ssh.socket é parado e desativado para liberar a porta 22 para o Docker vincular para Cowrie. As regras UFW são aplicadas após ambas as etapas para permitir a nova porta de administração.

Trade-offs:

• Nenhum trade-off funcional. Foi uma correção de configuração e ordem.

Lições Aprendidas:

• É importante estar ciente de quaisquer serviços que precisam de recursos específicos liberados em uma ordem específica antes de iniciarem. Neste caso, no Ubuntu 24.04, ssh.socket é uma unidade de socket systemd que mantém a porta 22 reservada para ativação SSH sob demanda. Ela deve ser parada e desativada antes que o Docker possa vincular a porta 22 do host para Cowrie. Se ainda estiver ativa, docker compose up falha com "address already in use".

Melhorias Futuras

Funcionalidade GeoIP

• O GeoIP a nível de cidade é aproximado. Os painéis do mapa dependem do banco de dados DB-IP e podem perder ou rotular incorretamente alguns IPs (móveis, VPNs, dados desatualizados). A pilha pode ser estendida posteriormente com um banco de dados diferente ou pipeline de enriquecimento para maior confiança na geografia.

Grafana HTTPS

• O Grafana atualmente opera em HTTP. Uma melhoria futura seria colocá-lo atrás de um proxy reverso (nginx ou Caddy) com um certificado TLS, o que também permitiria restringir a porta do Grafana a localhost e fazer proxy através da porta 443.

Funcionalidade de Servidor Proxy

• Para fazer o honeypot parecer mais legítimo, ele poderia ser proxy através de um servidor em uma região diferente. Isso dificultaria que atacantes o identificassem como um honeypot com base em seu IP ou geolocalização.

Considerações de Segurança

• Grafana usa HTTP. A porta 3000 sem TLS significa que as credenciais trafegam em texto claro.
• Loki escuta apenas em 127.0.0.1 (não exposto)
• terraform.tfvars está no .gitignore e nunca deve ser commitado
• Cowrie é executado como um usuário não privilegiado dentro de seu contêiner
• Grafana deve ser colocado atrás de um proxy reverso com HTTPS se exposto além de um ambiente de teste

Contribuidores

• Oseguera12

Licença

GNU General Public License Version 2.0 (GPLv2) Veja o texto completo da licença no arquivo LICENSE.