Cowrie & Grafana Honeypot avec Terraform sur DigitalOcean

Demo Video

Table des matières

• Table des matières
• Vue d'ensemble du système
• Technologies
• Structure du répertoire du projet
• Configuration matérielle requise
• Installation & Configuration
• Gestion de l'état Terraform
• Pipeline CI/CD
• Architecture du système
• Observations
• Utilisation
• Documentation du projet
  • Conception architecturale et compromis
  • Guide d'exécution du système
  • Problèmes et limitations rencontrés
  • Améliorations futures
• Considérations de sécurité
• Contributeurs
• Licence

Vue d'ensemble du système

Une pile de honeypot SSH/Telnet déployée sur un droplet DigitalOcean en utilisant Terraform. Les attaques sont capturées par Cowrie, stockées dans Loki, et visualisées dans Grafana avec une carte en temps réel des origines des attaques.

Technologies

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

Structure du répertoire du projet```

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

## Prérequis matériels

> Remarque : Ces exigences sont basées sur le plan Basic Droplet de DigitalOcean de mai 2026 et sont les exigences minimales pour exécuter le projet.

- Provider : DigitalOcean
- Plan : Basic Droplet - 1 Intel vCPU
- RAM : 1 Go (+2 Go swap)
- Stockage : 35 Go NVMe SSD
- OS : Ubuntu 24.04 LTS

## Installation et configuration

>Remarque : Après l'installation, il est recommandé d'ouvrir un nouveau terminal et de vérifier que vous pouvez toujours vous connecter en SSH sur le port `ADMIN_SSH_PORT` (par défaut : 2022) avant de fermer votre session d'origine.

### Déploiement avec Terraform (recommandé)

1. Créez un jeton API DigitalOcean avec des autorisations de lecture/écriture :

- Connectez-vous à DigitalOcean et naviguez vers Account > API > Tokens > Generate New Token.
- Nommez votre jeton (par exemple, « Cowrie Honeypot ») et sélectionnez les autorisations « Full Access ».
- Cliquez sur « Generate Token » et copiez la valeur du jeton dans un endroit sécurisé (vous ne pourrez plus le voir ensuite).

2. Créez une paire de clés SSH sur votre machine locale et copiez le chemin de la clé publique.

3. Accédez au répertoire `terraform`, puis copiez et modifiez le fichier de variables :

> Remarque : `do_token`, `ssh_public_key_path` et `grafana_admin_password` doivent être configurés au minimum dans `terraform.tfvars` avant d'appliquer.```bash
cd terraform
cp terraform.tfvars.example terraform.tfvars

4. Appliquer la configuration et lancer le déploiement :

Remarque : Terraform doit être installé sur votre machine locale. Consultez le Guide d'installation de Terraform pour les instructions.```bash terraform init # Initialize Terraform and download providers terraform apply

5. Si Test - Redéployer avec remplacement :```bash
terraform apply -replace="digitalocean_droplet.honeypot" 

6. Nettoyage - Détruisez l'infrastructure une fois terminé :```bash terraform destroy

### Déploiement manuel (Legacy)

1. Créez un droplet DigitalOcean avec les exigences matérielles ci-dessus et votre clé SSH.

2. Connectez-vous en SSH au droplet ou utilisez la console web DigitalOcean et exécutez les commandes suivantes :```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

Gestion de l'état Terraform

Note : Par défaut, Terraform écrit l'état dans terraform/terraform.tfstate sur votre machine locale. Ce fichier contient des valeurs de sortie sensibles (IP du droplet, mot de passe Grafana, empreinte de clé SSH) et ne doit jamais être commité. .gitignore couvre *.tfstate et *.tfstate.*.

Risques de l'état local :

• Perdu si la machine est perdue ou si le fichier est supprimé
• Impossible de le partager entre les membres de l'équipe
• Pas de verrouillage — deux exécutions apply simultanées peuvent corrompre le fichier

Pour tout ce qui dépasse un laboratoire personnel, passez à un backend distant. terraform/backend.tf contient une configuration DigitalOcean Spaces commentée (compatible S3).

Pour activer le backend distant :

1. Créez un bucket Spaces dans votre compte DigitalOcean
2. Générez une clé d'accès Spaces sous API > Spaces Keys
3. Exportez les clés en tant que variables d'environnement (ne les mettez pas dans terraform.tfvars) : ```bash export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY=
   root@kitploit:~

4. Décommentez le bloc backend "s3" dans terraform/backend.tf et remplissez le nom de votre bucket et le point de terminaison de la région.
5. Exécutez terraform init -migrate-state pour déplacer l'état local existant vers Spaces.

CI/CD Pipeline

.gitlab-ci.yml exécute trois jobs à chaque push dans une seule étape validate :

Remarque : terraform:fmt et terraform:validate bloquent le pipeline en cas d'échec. checkov:scan est réglé sur allow_failure: true car certains résultats sont des compromis intentionnels. Supprimez les résultats acceptables spécifiques avec des commentaires en ligne # checkov:skip=CKXXX plutôt que de désactiver complètement le job.

Risques acceptés connus

CKV_DIO_4 ("Assurez-vous que l'entrée du pare-feu n'est pas grande ouverte") se déclenche une fois contre l'ensemble de la ressource digitalocean_firewall. Il est supprimé avec un seul commentaire # checkov:skip=CKV_DIO_4: placé à l'intérieur du bloc de ressource dans terraform/main.tf. Le tableau ci-dessous documente pourquoi chaque port ouvert est intentionnel.

System Architecture```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

## Observations

Données capturées sur 5 jours de déploiement en direct (2026-05-05 à 2026-05-09) :

| Métrique                    | Valeur  |
|---------------------------|--------|
| Connexions totales         | 41,700 |
| Tentatives de connexion    | 15,400 |
| Connexions réussies        | 868    |
| Commandes exécutées         | 836    |
| Fichiers téléchargés       | 6      |
| Pays sources uniques       | 106    |

### Principaux pays d'attaque

| Pays         | Connexions |
|--------------|------------|
| Allemagne    | 9,768      |
| Pays-Bas     | 9,110      |
| États-Unis   | 7,706      |
| Royaume-Uni  | 3,858      |
| Singapour    | 1,770      |
| Belgique     | 1,422      |

### Schémas d'identifiants

Le nom d'utilisateur le plus souvent tenté était `root` avec 3,866 tentatives, suivi de `admin` (728) et `user` (494), reflétant des scanners automatisés ciblant les identifiants par défaut et les comptes de service connus. Le mot de passe le plus courant était `123456` (1,480 tentatives) suivi de `123` et `12345`, ce qui est cohérent avec les outils de force brute basés sur des dictionnaires.

### Comportement de l'attaquant dans le faux shell

868 tentatives de connexion ont réussi avec l'ensemble d'identifiants fictifs. Parmi ces sessions, 836 commandes ont été exécutées. La commande la plus courante était `uname -s -v -n -r -m` (360 exécutions) — une commande standard de reconnaissance système exécutée par des scripts automatisés de post-exploitation pour identifier le système d'exploitation et l'architecture cibles avant de déployer une charge utile. Les autres commandes observées incluaient `export HISTFILE=/dev/null` pour désactiver l'enregistrement de l'historique du shell, et `export HISTSAVE=/dev/null`, indiquant que les attaquants tentaient activement de dissimuler leurs traces même à l'intérieur de ce qu'ils pensaient être un système compromis.

### Enseignement clé

Le volume de trafic de balayage automatisé — 41,700 connexions en 5 jours depuis 106 pays — confirme que tout service SSH accessible publiquement fait face à des tentatives constantes de force brute dans les heures suivant son exposition. Le comportement consistant à exécuter immédiatement `uname` suivi de commandes de suppression d'historique est cohérent avec des frameworks de post-exploitation automatisés fonctionnant avec une intervention humaine minimale.

## Utilisation

### Utilisation du tableau de bord Grafana

> Note : Les identifiants du tableau de bord sont définis dans terraform.tfvars ou .env (pour un déploiement manuel)

Le tableau de bord est accessible à l'adresse :```
http://<your-droplet-ip>:3000

Connectez-vous avec admin / <GRAFANA_ADMIN_PASSWORD>.

Identifiants acceptés par le honeypot Cowrie

cowrie/etc/userdb.txt – contient les identifiants acceptés par le honeypot.

• Modifiez ce fichier pour ajuster les identifiants du honeypot

• Les connexions acceptées placent l'attaquant dans un shell factice où toutes les commandes sont enregistrées

• Les entrées rejetées sont enregistrées comme des tentatives échouées

Documentation du projet

Cette section détaille les décisions prises et les problèmes rencontrés lors du développement de ce projet. Elle sert de reflet du processus de développement et des leçons apprises. Passez à la section Considérations de sécurité si vous souhaitez seulement savoir comment utiliser le projet.

Conception de l'architecture et compromis

Pourquoi l'hébergement dans le cloud ?

• Les honeypots sont conçus pour être hautement disponibles afin de capturer et analyser les données 24 heures sur 24. Bien que le honeypot puisse être déployé sur une machine locale à l'aide de machines virtuelles ou de conteneurs, maintenir cette machine en ligne et accessible en permanence n'est pas pratique. L'hébergement dans le cloud offre une solution plus pratique et fiable pour héberger le honeypot et capturer les données en continu.
• De plus, comme l'hébergement dans le cloud vous permet de sélectionner des ressources et services spécifiques, il est plus facile de créer et de maintenir une base de code pouvant être déployée et étendue. Toute personne intéressée par le déploiement de son propre honeypot peut le faire sans étapes supplémentaires, tant que le projet fonctionne et que l'environnement provisionné correspond à ce que le projet attend.

Pourquoi DigitalOcean ?

• Bien que d'autres fournisseurs tels qu'AWS, GCP et Azure soient disponibles, DigitalOcean offre une option plus abordable pour ce projet. Comme un honeypot doit rester en ligne et envoyer des données en entrée et sortie du droplet 24 heures sur 24, le modèle de tarification de DigitalOcean a permis de maintenir des coûts prévisibles. Cela ne tient pas compte des promotions d'autres fournisseurs, telles que les crédits gratuits ou les réductions pour les nouveaux utilisateurs ou les engagements à long terme.

Pourquoi Terraform ?

• L'alternative, manual-deployment.sh, est destinée aux utilisateurs qui ne sont pas expérimentés avec Terraform ou qui préfèrent ne pas l'utiliser. Cette méthode nécessite de provisionner un droplet, de s'y connecter, de cloner le dépôt et d'exécuter le script. Terraform permet une itération plus rapide : modifier la base de code et redéployer sans répéter chaque étape manuelle depuis votre machine locale. Il facilite également la destruction de l'infrastructure pour repartir de zéro. Si le projet passe d'un seul honeypot à un honeynet, Terraform s'adapte plus proprement que le provisionnement manuel ou le script legacy seul.

Pourquoi Cowrie ?

• Cowrie est un honeypot d'interaction moyenne bien connu et activement maintenu. Il peut utiliser plus de ressources que des pièges plus légers, mais ses fonctionnalités et son adéquation avec le reste de la stack en ont fait un choix naturel. D'autres honeypots pourraient être échangés pour des cas d'usage spécifiques, bien que beaucoup ne soient pas maintenus ou nécessitent encore plus de ressources.

Pourquoi Loki ?

• La contrainte principale était matérielle : agrégation et recherche de logs sur un droplet avec 1 Go de RAM et plusieurs autres services en cours d'exécution. Elasticsearch était trop lourd. Graylog dépend toujours d'Elasticsearch en coulisse et ne fonctionnerait pas correctement dans les limites. D'autres options étaient tout aussi gourmandes en ressources. Grafana Loki correspondait à la stack et respectait le budget, sauf pour les requêtes très lourdes. Certaines fonctionnalités de requête ont été sacrifiées : si les tableaux de bord récupèrent trop de données, Loki devient lent, l'interface utilisateur semble ne pas répondre, et le honeypot peut manquer ou retarder des données.

Pourquoi Grafana ?

• J'avais initialement envisagé un tableau de bord personnalisé, mais Grafana est complet, personnalisable et bien documenté, ce qui a accéléré la configuration afin que je puisse me concentrer sur la collecte et l'expédition des logs. Il n'est pas aussi léger qu'une interface utilisateur minimale personnalisée, mais après une légère mise à niveau du droplet, il fonctionne confortablement dans les limites matérielles. D'autres outils avec des tableaux de bord préconstruits auraient utilisé plus de ressources sans avantages évidents pour ce cas d'usage.

Pourquoi Promtail ?

• Promtail est l'expéditeur de logs Loki établi (Grafana Alloy est le successeur plus récent). Promtail est léger en RAM et prend en charge les étapes de pipeline (analyse JSON, GeoIP, étiquettes) qui correspondent à ce projet. Des alternatives telles que Fluentd ou Logstash étaient trop lourdes pour un droplet de 1 Go.

Pourquoi GeoIP ?

• Les cartes d'attaque ont besoin du contexte de la ville et du pays à partir des IP sources. Le projet utilise DB-IP City Lite via scripts/geoip-update.sh : pas de compte ni de clé API, ce qui simplifie le déploiement pour quiconque clone le dépôt. L'étape GeoIP intégrée de Promtail lit le fichier MMDB local et ajoute des étiquettes pour le panneau Geomap de Grafana.

Déroulement d'exécution du système

Aperçu étape par étape de ce qui se produit lorsque le honeypot est configuré à l'aide de Terraform ou du script de déploiement manuel.

Terraform (recommandé)

Sur votre machine :

1. Configurez terraform/terraform.tfvars : jeton API, chemin de la clé publique SSH, mot de passe Grafana, URL/branche du dépôt, manage_do_firewall optionnel
2. Exécutez terraform init : installe le fournisseur DigitalOcean localement
3. Exécutez terraform apply : Terraform construit un plan, puis crée ou met à jour les ressources

Dans DigitalOcean :

4. La clé publique SSH est téléchargée sur votre compte
5. Le droplet est créé à partir de vos variables Terraform :
   • L'image (Ubuntu), la taille et la région proviennent de droplet_image, droplet_size, region, etc.
   • La clé SSH de l'étape 4 est attachée
   • user_data est défini sur le cloud-init rendu : au premier démarrage, la VM obtient le port SSH admin, le repo_url / repo_branch git, et une copie encodée en base64 du .env généré (mot de passe Grafana et ADMIN_SSH_PORT de env.tftpl)
6. Pare-feu cloud (uniquement lorsque manage_do_firewall est vrai) :
   • Terraform crée un pare-feu DigitalOcean et l'associe à ce droplet
   • TCP entrant : votre port SSH admin, 22, 23 et 3000 (voir terraform/main.tf)
   • Sortant : TCP/UDP large et ICMP afin que le droplet puisse mettre à jour les paquets, récupérer les images et télécharger les données GeoIP

Sur le droplet, cloud-init s'exécute automatiquement :

7. Cloud-config : package_update / package_upgrade, puis installe les paquets listés (curl, git, ufw, …). Au début du démarrage, write_files crée /root/honeypot.env (le env.tftpl rendu par Terraform en base64 : mot de passe Grafana, ADMIN_SSH_PORT, etc.)
8. Script d'amorçage runcmd (ordre dans terraform/templates/cloud-init.yaml.tftpl) : définit iptables / ip6tables sur les backends legacy
9. Swap : fichier de 2 Go si manquant (/swapfile, fstab, swappiness)

Dans Docker Compose :

18. Loki démarre et doit passer son check de santé (/ready sur le port 3100 dans le conteneur ; sur l'hôte seulement 127.0.0.1:3100)
19. Promtail et Grafana attendent que Loki soit sain (depends_on dans docker-compose.yml), puis démarrent
20. Cowrie peut démarrer indépendamment : il publie les ports hôtes 22 et 23 dans le conteneur et écrit les logs JSON sous data/cowrie-logs pour Promtail

Configuration manuelle (legacy)

L'utilisateur crée la VM, se connecte en SSH, et exécute le script depuis le dépôt cloné.

manual-deployment.sh effectue les opérations suivantes :

1. Charge et valide .env
2. Mise à jour du système : apt update & apt upgrade
3. Installation des paquets : outils plus ufw et iptables
4. Configuration du swap : fichier de 2 Go si manquant
5. Installation de Docker : moteur + plugin Compose, activation des services
6. Configuration SSH : sshd sur ADMIN_SSH_PORT et désactivation de ssh.socket
7. Configuration du pare-feu : scripts/setup-firewall.sh
8. Configuration GeoIP : scripts/geoip-update.sh et cron mensuel
9. Démarrage de la stack : docker compose pull / up -d, puis le script attend les checks de santé de Loki et Grafana et imprime un résumé

Problèmes rencontrés

Limitations matérielles

• Des ressources matérielles limitées ont entraîné des performances lentes et des dépassements de délai occasionnels. Cela a affecté le tableau de bord qui dépend de la capacité à interroger rapidement la base de données à des intervalles définis par l'utilisateur, parfois par plusieurs appareils accédant au tableau de bord simultanément.

Solutions envisagées :

• Mise à l'échelle verticale pour plus de ressources
• Tableau de bord personnalisé avec moins de panneaux pour réduire la charge sur la base de données
• Limitation du nombre d'appareils pouvant accéder au tableau de bord en même temps
• Agrégation des logs dans une base de données séparée pour que le tableau de bord les lise, afin de réduire la charge sur la base de données principale

Résolution :

• Passage à un droplet légèrement plus grand avec de meilleures performances

Compromis :

• Bien que le coût ait augmenté d'environ 1 à 2 $ par mois, les ressources disponibles ont doublé. L'accès au stockage SSD NVMe et à plus de RAM par rapport au droplet de base a permis d'obtenir un tableau de bord plus stable et plus performant. Cela a évité de devoir passer du temps à créer un tableau de bord personnalisé avec moins de panneaux et une expérience moins réactive.

Leçons apprises :

• Obtenir autant de ressources que possible tout en restant dans le budget en profitant des promotions, réductions et niveaux de tarification. La différence entre le droplet le plus basique et une légère augmentation du coût a permis de doubler les ressources disponibles, ce qui a fait gagner du temps en permettant un produit plus complet. De plus, faire fonctionner le honeypot plus tôt a permis de capturer et d'analyser les données plus tôt.

Problèmes de délai d'attente

• Lors de la tentative de connexion SSH au droplet pour un accès administrateur, les connexions expiraient. Par ailleurs, docker compose up échouait car le port 22 était déjà utilisé et ne pouvait pas être lié par Cowrie.

Solutions envisagées :

• sshd était mal configuré ou écoutait sur le mauvais port
• Les règles du pare-feu bloquaient le port SSH admin après son déplacement
• Un autre processus détenait déjà le port 22

Résolution :

• Correction de l'ordre des opérations : sshd est déplacé sur ADMIN_SSH_PORT (par défaut 2022) et redémarré en premier, puis ssh.socket est arrêté et désactivé pour libérer le port 22 afin que Docker puisse le lier pour Cowrie. Les règles UFW sont appliquées après les deux étapes pour autoriser le nouveau port admin.

Compromis :

• Aucun compromis fonctionnel. Il s'agissait d'une correction de configuration et d'ordre.

Leçons apprises :

• Il est important d'être conscient des services qui nécessitent que des ressources spécifiques soient libérées dans un ordre particulier avant de pouvoir démarrer. Dans ce cas, sur Ubuntu 24.04, ssh.socket est une unité socket systemd qui maintient le port 22 réservé pour une activation SSH à la demande. Il doit être arrêté et désactivé avant que Docker puisse lier le port hôte 22 pour Cowrie. S'il est toujours actif, docker compose up échoue avec "adresse déjà utilisée".

Améliorations futures

Fonctionnalité GeoIP

• Le GeoIP au niveau de la ville est approximatif. Les panneaux de carte dépendent de la base de données DB-IP et peuvent manquer ou mal étiqueter certaines IP (mobiles, VPN, données obsolètes). La stack pourrait être étendue ultérieurement avec une base de données ou un pipeline d'enrichissement différent pour une meilleure confiance géographique.

HTTPS pour Grafana

• Grafana fonctionne actuellement en HTTP. Une amélioration future consisterait à le placer derrière un proxy inverse (nginx ou Caddy) avec un certificat TLS, ce qui permettrait également de restreindre le port Grafana à localhost et de le proxyfier via le 443.

Fonctionnalité de serveur proxy

• Pour rendre le honeypot plus légitime, il pourrait être proxyfié via un serveur dans une région différente. Cela rendrait plus difficile pour les attaquants de l'identifier comme un honeypot en fonction de son IP ou de sa géolocalisation.

Considérations de sécurité

• Grafana utilise HTTP. Le port 3000 sans TLS signifie que les identifiants transitent en clair.
• Loki écoute uniquement sur 127.0.0.1 (non exposé)
• terraform.tfvars est dans .gitignore et ne doit jamais être commité
• Cowrie s'exécute en tant qu'utilisateur non privilégié dans son conteneur
• Grafana doit être placé derrière un proxy inverse avec HTTPS s'il est exposé au-delà d'un environnement de test

Contributeurs

• Oseguera12

Licence

GNU General Public License Version 2.0 (GPLv2) Voir le texte complet de la licence dans le fichier LICENSE.