Cowrie & Grafana Honeypot usando Terraform na DigitalOcean

Vídeo de Demonstração

Índice

• Visão Geral do Sistema
• Tecnologias
• Estrutura de Diretórios do Projeto
• Requisitos de Hardware
• Instalação e Configuração
• Gerenciamento de Estado do Terraform
• Pipeline de CI/CD
• Arquitetura do Sistema
• Observações
• Métricas de Execução
• Uso
• Documentação do Projeto
  • Design de Arquitetura e Trade-offs
  • Passo a Passo da Execução do Sistema
  • Problemas e Limitações Encontrados
  • Melhorias Futuras
• Considerações de Segurança
• Contribuidores
• Licença

Visão Geral do Sistema

Uma stack 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 (download do City Lite)

Estrutura de Diretórios do Projeto```

honeypot/ ├── cowrie/ │ └── etc/ │ ├── cowrie.cfg # Cowrie honeypot configuration │ └── userdb.txt # Accepted and rejected fake credentials ├── docs/ │ └── ttp-to-runtime-rules.md # Observed attacker TTPs → Falco rules (eks-gitops, platform-engineering-lab) ├── 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 ├── metrics/ │ ├── runtime-metrics.schema.json # Shared schema — identical across all 4 portfolio projects │ └── runtime-metrics.json # Generated by scripts/export-honeypot-metrics.sh; gitignored, not committed ├── 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 │ ├── export-honeypot-metrics.sh # Queries Grafana/Loki, writes attacker_telemetry │ └── emit-runtime-metrics.py # Wraps attacker_telemetry in the shared metrics schema ├── 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, metrics schema/export ├── 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 DigitalOcean Basic Droplet em maio de 2026 e são os requisitos mínimos para executar o projeto.

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

> **Margem de memória após as atualizações de versão dos containers:** O `docker-compose.yml` fixa imagens mais recentes do Grafana (12.0.0), Loki e Promtail (3.6.13) do que este tamanho de droplet foi originalmente ajustado. Os valores de `mem_limit`/`memswap_limit` por serviço permanecem inalterados — monitore `docker stats` após o primeiro deploy e aumente o plano do droplet (ou reduza o `retention_period` do Loki / o cache do Grafana) se algum container estiver consistentemente próximo do seu limite.

## Instalação e Configuração

>Nota: Após a instalação, recomenda-se abrir um novo terminal e verificar se você ainda consegue conectar via SSH na `ADMIN_SSH_PORT` (Padrão: 2022) antes de fechar sua sessão original.

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

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

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

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

3. Vá para o diretório `terraform` e então 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 o Guia de Instalação do Terraform para obter instruções.```bash terraform init # Initialize Terraform and download providers terraform apply

5. Se Testando - 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. Acesse o droplet via SSH 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 grava 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, fingerprint 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 excluído
• Não pode ser compartilhado entre membros da equipe
• Sem locking — duas execuções concorrentes de apply podem corromper o arquivo