Cowrie & Grafana Honeypot using Terraform on DigitalOcean

Demo Video

Table of Contents

• Table of Contents
• System Overview
• Technologies
• Project Directory Structure
• Hardware Requirements
• Installation & Setup
• Terraform State Management
• CI/CD Pipeline
• System Architecture
• Observations
• Usage
• Project Documentation
  • Architecture Design and Trade-offs
  • System Execution Walkthrough
  • Issues & Limitations Encountered
  • Future Improvements
• Security Considerations
• Contributors
• License

System Overview

An SSH/Telnet honeypot stack deployed on a DigitalOcean droplet using Terraform. Attacks are captured by Cowrie, stored in Loki, and visualised in Grafana with a live world map of attack origins.

Technologies

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

Project Directory Structure

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

Hardware Requirements

Note: These requirements are based on the DigitalOcean Basic Droplet plan as of May 2026 and are the minimum requirements to run the project.

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

Installation & Setup

Note: After installation, it is recommended to open a new terminal and verify you can still SSH on ADMIN_SSH_PORT (Default: 2022) before closing your original session.

Terraform Deployment (Recommended)

1. Create a DigitalOcean API token with read/write permissions:

• Log into DigitalOcean and navigate to Account > API > Tokens > Generate New Token.
• Name your token (e.g., "Cowrie Honeypot") and select "Full Access" permissions.
• Click "Generate Token" and copy the token value to a secure location (you won't be able to see it again).

2. Create an SSH key pair on your local machine and copy the public key path.

3. Go to the terraform directory then copy and edit the variables file:

Note: do_token, ssh_public_key_path, and grafana_admin_password must be configured at minimum in terraform.tfvars before applying.

cd terraform
cp terraform.tfvars.example terraform.tfvars

4. Apply the configuration and start the deployment:

Note: Terraform must be installed on your local machine. Visit Terraform Installation Guide for instructions.

terraform init  # Initialize Terraform and download providers
terraform apply

5. If Testing - Redeploy with replacement:

terraform apply -replace="digitalocean_droplet.honeypot" 

6. Clean-up - Destroy the infrastructure when you're done:

terraform destroy

Manual Deployment (Legacy)

1. Create a DigitalOcean droplet with the above hardware requirements and your SSH key.

2. SSH into the droplet or use the DigitalOcean web console and run the following commands:

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

Terraform State Management

Note: By default, Terraform writes state to terraform/terraform.tfstate on your local machine. This file contains sensitive output values (droplet IP, Grafana password, SSH key fingerprint) and must never be committed. .gitignore covers *.tfstate and *.tfstate.*.

Risks of local state:

• Lost if the machine is lost or the file is deleted
• Cannot be shared across team members
• No locking — two concurrent apply runs can corrupt the file

For anything beyond a personal lab, switch to a remote backend. terraform/backend.tf contains a commented-out DigitalOcean Spaces configuration (S3-compatible).

To enable remote backend:

1. Create a Spaces bucket in your DigitalOcean account

2. Generate a Spaces access key under API > Spaces Keys

3. Export the keys as environment variables (do not put them in terraform.tfvars):

   export AWS_ACCESS_KEY_ID=<spaces-access-key>
   export AWS_SECRET_ACCESS_KEY=<spaces-secret-key>
   

4. Uncomment the backend "s3" block in terraform/backend.tf and fill in your bucket name and region endpoint.

5. Run terraform init -migrate-state to move existing local state to Spaces.

CI/CD Pipeline

.gitlab-ci.yml runs three jobs on every push in a single validate stage: