Honeypot Cowrie e Grafana con Terraform su DigitalOcean

Video dimostrativo

Indice dei contenuti

• Indice dei contenuti
• Panoramica del sistema
• Tecnologie
• Struttura della directory del progetto
• Requisiti hardware
• Installazione e configurazione
• Gestione dello stato di Terraform
• Pipeline CI/CD
• Architettura del sistema
• Osservazioni
• Utilizzo
• Documentazione del progetto
  • Progettazione dell'architettura e compromessi
  • Procedura dettagliata di esecuzione del sistema
  • Problemi e limitazioni incontrati
  • Miglioramenti futuri
• Considerazioni sulla sicurezza
• Contributori
• Licenza

Panoramica del sistema

Uno stack di honeypot SSH/Telnet distribuito su un droplet DigitalOcean utilizzando Terraform. Gli attacchi vengono catturati da Cowrie, archiviati in Loki e visualizzati in Grafana con una mappa mondiale in tempo reale delle origini degli attacchi.

Tecnologie

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

Struttura della directory del progetto```

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

## Requisiti Hardware

> Nota: Questi requisiti si basano sul piano DigitalOcean Basic Droplet di maggio 2026 e sono i requisiti minimi per eseguire il progetto.

- Provider: DigitalOcean
- Piano: Basic Droplet - 1 vCPU Intel
- RAM: 1 GB (+2 GB di swap)
- Storage: 35 GB NVMe SSD
- OS: Ubuntu 24.04 LTS

## Installazione e Configurazione

>Nota: Dopo l'installazione, si consiglia di aprire un nuovo terminale e verificare di poter ancora eseguire SSH su `ADMIN_SSH_PORT` (Predefinito: 2022) prima di chiudere la sessione originale.

### Distribuzione con Terraform (Consigliata)

1. Crea un token API DigitalOcean con autorizzazioni di lettura/scrittura:

- Accedi a DigitalOcean e vai su Account > API > Tokens > Generate New Token.
- Assegna un nome al token (ad es., "Cowrie Honeypot") e seleziona le autorizzazioni "Full Access".
- Fai clic su "Generate Token" e copia il valore del token in un luogo sicuro (non potrai vederlo di nuovo).

2. Crea una coppia di chiavi SSH sulla tua macchina locale e copia il percorso della chiave pubblica.

3. Vai nella directory `terraform` quindi copia e modifica il file delle variabili:

> Nota: `do_token`, `ssh_public_key_path` e `grafana_admin_password` devono essere configurati come minimo in `terraform.tfvars` prima di applicare.```bash
cd terraform
cp terraform.tfvars.example terraform.tfvars

4. Applica la configurazione e avvia il deployment:

Nota: Terraform deve essere installato sulla tua macchina locale. Visita la Guida all'installazione di Terraform per le istruzioni.```bash terraform init # Initialize Terraform and download providers terraform apply

5. Se Testing - Ridistribuire con sostituzione:```bash
terraform apply -replace="digitalocean_droplet.honeypot" 

6. Pulizia - Distruggi l'infrastruttura quando hai finito:```bash terraform destroy

### Distribuzione Manuale (Legacy)

1. Crea un droplet DigitalOcean con i requisiti hardware sopra indicati e la tua chiave SSH.

2. Connettiti al droplet via SSH o usa la console web DigitalOcean ed esegui i seguenti comandi:```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

Gestione dello Stato di Terraform

Nota: Per impostazione predefinita, Terraform scrive lo stato in terraform/terraform.tfstate sulla tua macchina locale. Questo file contiene valori di output sensibili (IP del droplet, password di Grafana, impronta digitale della chiave SSH) e non deve mai essere committato. .gitignore copre *.tfstate e *.tfstate.*.

Rischi dello stato locale:

• Perso se la macchina viene smarrita o il file viene cancellato
• Non può essere condiviso tra i membri del team
• Nessun blocco — due esecuzioni concorrenti di apply possono danneggiare il file

Per qualsiasi cosa oltre a un laboratorio personale, passa a un backend remoto. terraform/backend.tf contiene una configurazione DigitalOcean Spaces (compatibile con S3) commentata.

Per abilitare il backend remoto:

1. Crea un bucket Spaces nel tuo account DigitalOcean
2. Genera una chiave di accesso Spaces in API > Spaces Keys
3. Esporta le chiavi come variabili d'ambiente (non inserirle in terraform.tfvars): ```bash export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY=
   root@kitploit:~

4. Decommenta il blocco backend "s3" in terraform/backend.tf e inserisci il nome del tuo bucket e l'endpoint della regione.
5. Esegui terraform init -migrate-state per spostare lo stato locale esistente su Spaces.

Pipeline CI/CD

.gitlab-ci.yml esegue tre job a ogni push in un'unica fase validate:

Nota: terraform:fmt e terraform:validate bloccano la pipeline in caso di fallimento. checkov:scan è impostato su allow_failure: true perché alcuni risultati sono compromessi intenzionali. Sopprimi risultati accettabili specifici con commenti inline # checkov:skip=CKXXX invece di disabilitare completamente il job.

Rischi accettati noti

CKV_DIO_4 ("Assicurati che l'ingresso del firewall non sia completamente aperto") scatta una volta contro l'intera risorsa digitalocean_firewall. È soppresso con un singolo commento # checkov:skip=CKV_DIO_4: inserito all'interno del blocco della risorsa in terraform/main.tf. La tabella seguente documenta perché ogni porta aperta è intenzionale.

Architettura del 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

## Osservazioni

Dati raccolti in 5 giorni di distribuzione live (2026-05-05 to 2026-05-09):

| Metrica                    | Valore  |
|---------------------------|--------|
| Connessioni totali         | 41.700 |
| Tentativi di login         | 15.400 |
| Login riusciti             | 868    |
| Comandi eseguiti           | 836    |
| File scaricati             | 6      |
| Paesi di origine unici     | 106    |

### Principali paesi di attacco

| Paese         | Connessioni |
|-----------------|-------------|
| Germania        | 9.768       |
| Paesi Bassi     | 9.110       |
| Stati Uniti     | 7.706       |
| Regno Unito     | 3.858       |
| Singapore       | 1.770       |
| Belgio          | 1.422       |

### Modelli di credenziali

Il nome utente più comune tentato è stato `root` con 3.866 tentativi, seguito da
`admin` (728) e `user` (494), riflettendo scanner automatici che prendono di mira
credenziali predefinite e account di servizio noti. La password più comune è stata
`123456` (1.480 tentativi), seguita da `123` e `12345`, in linea con
strumenti di attacco a forza bruta basati su dizionario.

### Comportamento degli attaccanti all'interno della shell fittizia

868 tentativi di login sono riusciti contro il set di credenziali fittizie. Di quelle sessioni,
836 comandi sono stati eseguiti. Il comando più comune è stato `uname -s -v -n -r -m`
(360 esecuzioni) — un comando standard di fingerprinting del sistema eseguito da
script automatizzati di post-sfruttamento per identificare il sistema operativo e l'architettura di destinazione prima di
distribuire un payload. Altri comandi osservati includevano `export HISTFILE=/dev/null`
per disabilitare la registrazione della cronologia della shell, e `export HISTSAVE=/dev/null`, indicando
attaccanti che tentano attivamente di coprire le loro tracce anche all'interno di ciò che credevano
fosse un sistema compromesso.

### Punti chiave

Il volume del traffico di scansione automatizzato — 41.700 connessioni in 5 giorni da 106
paesi — conferma che qualsiasi servizio SSH pubblicamente accessibile subisce costanti
tentativi di forza bruta entro ore dall'esposizione. Il modello comportamentale di
eseguire immediatamente `uname` seguito da comandi di soppressione della cronologia è coerente
con framework automatizzati di post-sfruttamento che operano con un coinvolgimento umano
minimo.

## Utilizzo

### Utilizzo della dashboard Grafana

> Nota: Le credenziali della dashboard sono impostate in terraform.tfvars o .env (per distribuzione manuale)

La dashboard è accessibile all'indirizzo:```
http://<your-droplet-ip>:3000

Accedi con admin / <GRAFANA_ADMIN_PASSWORD>.

Credenziali accettate dall'honeypot Cowrie

cowrie/etc/userdb.txt - contiene le credenziali accettate per l'honeypot.

• Modifica questo file per regolare le credenziali dell'honeypot

• Gli accessi accettati portano l'attaccante in una shell fittizia dove tutti i comandi vengono registrati

• Le voci rifiutate vengono registrate come tentativi falliti

Documentazione del progetto

Questa sezione descrive le decisioni prese e i problemi incontrati durante lo sviluppo di questo progetto. Funge da riflessione sul processo di sviluppo e sulle lezioni apprese. Passa a Considerazioni sulla sicurezza se vuoi solo sapere come usare il progetto.

Progettazione dell'architettura e compromessi

Perché il cloud hosting?

• Gli honeypot sono progettati per essere altamente disponibili al fine di catturare e analizzare i dati 24 ore su 24. Sebbene l'honeypot possa essere distribuito su una macchina locale utilizzando macchine virtuali o container, mantenere quella macchina online e accessibile 24 ore su 24 non è pratico. Il cloud hosting fornisce una soluzione più pratica e affidabile per ospitare l'honeypot e catturare i dati in modo continuo.
• Inoltre, poiché il cloud hosting consente di selezionare risorse e servizi specifici, è più facile creare e mantenere un codebase che possa essere distribuito ed espanso. Chiunque sia interessato a distribuire il proprio honeypot può farlo senza passaggi aggiuntivi, purché il progetto funzioni e l'ambiente fornito corrisponda a quanto previsto dal progetto.

Perché DigitalOcean?

• Sebbene altri provider come AWS, GCP e Azure siano disponibili, DigitalOcean offre un'opzione più economica per questo progetto. Poiché un honeypot deve rimanere online e inviare dati in entrata e in uscita dal droplet 24 ore su 24, il modello di prezzo di DigitalOcean ha aiutato a mantenere i costi prevedibili. Ciò non tiene conto delle promozioni di altri provider, come crediti gratuiti o sconti per nuovi utenti o impegni a lungo termine.

Perché Terraform?

• L'alternativa, manual-deployment.sh, è per gli utenti che non hanno esperienza con Terraform o preferiscono non usarlo. Quel percorso richiede il provisioning di un droplet, la connessione ad esso, la clonazione del repository e l'esecuzione dello script. Terraform consente iterazioni più rapide: modifica il codebase e ridistribuisci senza ripetere ogni passaggio manuale dal tuo computer locale. Inoltre, rende facile smantellare l'infrastruttura e ricominciare da capo. Se il progetto cresce da un singolo honeypot a una honeynet, Terraform scala in modo più pulito rispetto al provisioning manuale o al solo script legacy.

Perché Cowrie?

• Cowrie è un honeypot di media interazione ben noto e attivamente mantenuto. Può utilizzare più risorse rispetto a trappole più leggere, ma le sue caratteristiche e l'integrazione con il resto dello stack lo hanno reso una scelta naturale. Altri honeypot potrebbero essere scambiati per casi d'uso specifici, sebbene molti non siano mantenuti o richiedano ancora più risorse.

Perché Loki?

• Il vincolo principale era l'hardware: aggregazione e ricerca dei log su un droplet con 1 GB di RAM con molti altri servizi in esecuzione. Elasticsearch era troppo pesante. Graylog dipende ancora da Elasticsearch sotto il cofano e non funzionerebbe correttamente entro i limiti. Altre opzioni erano ugualmente affamate di risorse. Grafana Loki si adattava allo stack e rimaneva entro il budget eccetto per query molto pesanti. Sono state sacrificate alcune funzionalità di interrogazione: se le dashboard recuperano troppi dati, Loki diventa lento, l'UI sembra non rispondere e l'honeypot può perdere o ritardare i dati.

Perché Grafana?

• Inizialmente avevo considerato una dashboard personalizzata, ma Grafana è completo, personalizzabile e ben documentato, il che ha accelerato la configurazione permettendomi di concentrarmi sulla raccolta e sull'invio dei log. Non è leggero come un'interfaccia utente personalizzata minima, ma dopo un piccolo aggiornamento del droplet funziona comodamente entro i limiti hardware. Altri strumenti con dashboard predefinite avrebbero utilizzato più risorse senza chiari vantaggi per questo caso d'uso.

Perché Promtail?

• Promtail è lo spedizioniere di log consolidato per Loki (Grafana Alloy è il successore più recente). Promtail è leggero in termini di RAM e supporta fasi di pipeline (analisi JSON, GeoIP, etichette) che corrispondono a questo progetto. Alternative come Fluentd o Logstash erano troppo pesanti per un droplet da 1 GB.

Perché GeoIP?

• Le mappe degli attacchi necessitano del contesto di città e paese dagli IP sorgente. Il progetto utilizza DB-IP City Lite tramite scripts/geoip-update.sh: nessun account o chiave API, il che mantiene la distribuzione semplice per chiunque cloni il repository. La fase GeoIP integrata di Promtail legge il file MMDB locale e aggiunge etichette per il pannello Geomap di Grafana.

Panoramica dell'esecuzione del sistema

Panoramica passo dopo passo di ciò che accade quando l'honeypot viene configurato utilizzando Terraform o lo script di distribuzione manuale.

Terraform (consigliato)

Sulla tua macchina:

1. Configura terraform/terraform.tfvars: token API, percorso della chiave pubblica SSH, password di Grafana, URL/branch del repository, manage_do_firewall opzionale
2. Esegui terraform init: installa il provider DigitalOcean localmente
3. Esegui terraform apply: Terraform crea un piano, poi crea o aggiorna le risorse

In DigitalOcean:

4. La chiave pubblica SSH viene caricata nel tuo account
5. Il droplet viene creato dalle tue variabili Terraform:
   • Immagine (Ubuntu), dimensione e regione provengono da droplet_image, droplet_size, region, ecc.
   • La chiave SSH del passaggio 4 viene allegata
   • user_data è impostato sul cloud-init renderizzato: al primo avvio la VM riceve la porta SSH amministrativa, git repo_url / repo_branch e una copia codificata in base64 del .env generato (password di Grafana e ADMIN_SSH_PORT da env.tftpl)
6. Firewall cloud (solo quando manage_do_firewall è true):
   • Terraform crea un firewall DigitalOcean e lo associa a questo droplet
   • TCP in entrata: la tua porta SSH amministrativa, 22, 23 e 3000 (vedi terraform/main.tf)
   • Uscita: TCP/UDP ampio e ICMP in modo che il droplet possa aggiornare pacchetti, scaricare immagini e dati GeoIP

Sul droplet, cloud-init viene eseguito automaticamente:

7. Cloud-config: package_update / package_upgrade, quindi installa i pacchetti elencati (curl, git, ufw, …). All'inizio dell'avvio, write_files crea /root/honeypot.env (env.tftpl renderizzato da Terraform come base64: password di Grafana, ADMIN_SSH_PORT, ecc.)
8. Script di bootstrap runcmd (ordine in terraform/templates/cloud-init.yaml.tftpl): imposta iptables / ip6tables su backend legacy
9. Swap: file da 2 GB se mancante (/swapfile, fstab, swappiness)

All'interno di Docker Compose:

18. Loki si avvia e deve superare il suo health check (/ready sulla porta 3100 nel container; sull'host solo 127.0.0.1:3100)
19. Promtail e Grafana aspettano che Loki sia sano (depends_on in docker-compose.yml), poi si avviano
20. Cowrie può avviarsi indipendentemente: pubblica le porte host 22 e 23 nel container e scrive log JSON in data/cowrie-logs per Promtail

Configurazione manuale (legacy)

L'utente crea la VM, si connette via SSH ed esegue lo script dal repository clonato.

manual-deployment.sh esegue le seguenti operazioni:

1. Carica e convalida .env
2. Aggiornamento del sistema: apt update e apt upgrade
3. Installa i pacchetti: strumenti più ufw e iptables
4. Configura swap: file da 2 GB se mancante
5. Installa Docker: Engine + plugin Compose, abilita i servizi
6. Configura SSH: sshd su ADMIN_SSH_PORT e disabilita ssh.socket
7. Configura firewall: scripts/setup-firewall.sh
8. Configura GeoIP: scripts/geoip-update.sh e cron mensile
9. Avvia lo stack: docker compose pull / up -d, poi lo script attende i controlli di integrità di Loki e Grafana e stampa un riepilogo

Problemi incontrati

Limitazioni hardware

Le risorse hardware limitate hanno portato a prestazioni lente e timeout occasionali. Ciò ha influito sulla dashboard che dipende dalla capacità di interrogare rapidamente il database a intervalli impostati dall'utente, a volte da più dispositivi che accedono contemporaneamente alla dashboard.

Soluzioni considerate:

• Scalare verticalmente per più risorse
• Dashboard personalizzata con meno pannelli per ridurre il carico sul database
• Limitare il numero di dispositivi che possono accedere contemporaneamente alla dashboard
• Aggregare i log in un database separato da cui la dashboard legga per ridurre lo stress sul database principale

Risoluzione:

• Scalato a un droplet leggermente più grande con prestazioni migliori

Compromessi:

• Sebbene il costo sia aumentato di circa $1-2 al mese, le risorse disponibili sono raddoppiate. L'accesso a storage NVMe SSD e più RAM rispetto al Droplet Base ha permesso una dashboard più stabile e performante. Ciò ha evitato di dover dedicare tempo alla creazione di una dashboard personalizzata con meno pannelli e un'esperienza meno reattiva.

Lezioni apprese:

• Ottenere quante più risorse possibile rimanendo entro il budget approfittando di promozioni, sconti e fasce di prezzo. La differenza tra il droplet più basilare e un leggero aumento di costo ha portato al raddoppio delle risorse disponibili, risparmiando tempo grazie a un prodotto più completo. Inoltre, avviare l'honeypot prima ha significato catturare e analizzare i dati prima.

Problemi di timeout

Quando si tentava di connettersi via SSH al droplet per l'accesso amministrativo, le connessioni scadevano. Separatamente, docker compose up falliva perché la porta 22 era già in uso e non poteva essere associata da Cowrie.

Soluzioni considerate:

• sshd era configurato male o in ascolto sulla porta sbagliata
• Le regole del firewall bloccavano la porta SSH amministrativa dopo lo spostamento
• Un altro processo stava già occupando la porta 22

Risoluzione:

• Corretto l'ordine delle operazioni: sshd viene spostato su ADMIN_SSH_PORT (default 2022) e riavviato per primo, poi ssh.socket viene fermato e disabilitato per liberare la porta 22 per Docker che la userà per Cowrie. Le regole UFW vengono applicate dopo entrambi i passaggi per consentire la nuova porta amministrativa.

Compromessi:

• Nessun compromesso funzionale. È stata una correzione di configurazione e ordine.

Lezioni apprese:

• È importante essere consapevoli di eventuali servizi che richiedono la liberazione di risorse specifiche in un determinato ordine prima di poter partire. In questo caso su Ubuntu 24.04, ssh.socket è un'unità socket di systemd che mantiene la porta 22 riservata per l'attivazione on-demand di SSH. Deve essere fermato e disabilitato prima che Docker possa associare la porta host 22 a Cowrie. Se è ancora attivo, docker compose up fallisce con "indirizzo già in uso".

Miglioramenti futuri

Funzionalità GeoIP

• Il GeoIP a livello di città è approssimativo. I pannelli della mappa dipendono dal database DB-IP e potrebbero non rilevare o etichettare erroneamente alcuni IP (mobile, VPN, dati obsoleti). Lo stack potrebbe essere esteso in seguito con un database o una pipeline di arricchimento diversa per una maggiore affidabilità geografica.

Grafana HTTPS

• Grafana attualmente è in esecuzione su HTTP. Un miglioramento futuro sarebbe posizionarlo dietro un proxy inverso (nginx o Caddy) con un certificato TLS, il che consentirebbe anche di limitare la porta di Grafana a localhost e di proxyare attraverso la 443.

Funzionalità server proxy

• Per rendere l'honeypot più legittimo, potrebbe essere reindirizzato tramite un server in una regione diversa. Ciò renderebbe più difficile per gli attaccanti identificarlo come honeypot in base al suo IP o geolocalizzazione.

Considerazioni sulla sicurezza

• Grafana utilizza HTTP. La porta 3000 senza TLS significa che le credenziali transitano in chiaro.
• Loki ascolta solo su 127.0.0.1 (non esposto)
• terraform.tfvars è in gitignore e non deve mai essere committato
• Cowrie viene eseguito come utente non privilegiato all'interno del suo container
• Grafana dovrebbe essere posizionato dietro un proxy inverso con HTTPS se esposto oltre un ambiente di test

Collaboratori

• Oseguera12

Licenza

GNU General Public License Version 2.0 (GPLv2) Vedi il testo completo della licenza nel file LICENSE.