Tecnologías

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

Estructura del Directorio del Proyecto```

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

4. Aplica la configuración e inicia el despliegue:

Nota: Terraform debe estar instalado en tu máquina local. Visita Guía de instalación de Terraform para obtener instrucciones.```bash terraform init # Initialize Terraform and download providers terraform apply

6. Limpieza - Destruye la infraestructura cuando termines:```bash terraform destroy

Gestión del Estado de Terraform

Nota: Por defecto, Terraform escribe el estado en terraform/terraform.tfstate en tu máquina local. Este archivo contiene valores de salida sensibles (IP del droplet, contraseña de Grafana, huella digital de la clave SSH) y nunca debe ser enviado al repositorio. .gitignore cubre *.tfstate y *.tfstate.*.

Riesgos del estado local:

• Se pierde si la máquina se pierde o el archivo se elimina
• No se puede compartir entre miembros del equipo
• Sin bloqueo — dos ejecuciones concurrentes de apply pueden corromper el archivo

Para cualquier cosa más allá de un laboratorio personal, cambia a un backend remoto. terraform/backend.tf contiene una configuración comentada de DigitalOcean Spaces (compatible con S3).

Para habilitar el backend remoto:

1. Crea un bucket de Spaces en tu cuenta de DigitalOcean
2. Genera una clave de acceso de Spaces en API > Spaces Keys
3. Exporta las claves como variables de entorno (no las pongas en terraform.tfvars): ```bash export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY=
   root@kitploit:~

4. Descomenta el bloque backend "s3" en terraform/backend.tf y completa con el nombre de tu bucket y el endpoint de la región.
5. Ejecuta terraform init -migrate-state para mover el estado local existente a Spaces.

Pipeline de CI/CD

.gitlab-ci.yml ejecuta tres trabajos en cada push en una sola etapa validate:

Nota: terraform:fmt y terraform:validate bloquean el pipeline en caso de fallo. checkov:scan está configurado con allow_failure: true porque algunos hallazgos son compromisos intencionales. Suprime hallazgos aceptables específicos con comentarios en línea # checkov:skip=CKXXX en lugar de deshabilitar el trabajo por completo.

Riesgos aceptados conocidos

CKV_DIO_4 ("Asegurar que la entrada del cortafuegos no esté completamente abierta") se dispara una vez contra todo el recurso digitalocean_firewall. Se suprime con un único comentario # checkov:skip=CKV_DIO_4: colocado dentro del bloque del recurso en terraform/main.tf. La tabla a continuación documenta por qué cada puerto abierto es intencional.

Arquitectura 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

Iniciar sesión con admin / <GRAFANA_ADMIN_PASSWORD>.

Credenciales aceptadas del honeypot Cowrie

cowrie/etc/userdb.txt - contiene las credenciales aceptadas para el honeypot.

• Edite este archivo para ajustar las credenciales del honeypot

• Los inicios de sesión aceptados colocan al atacante en un shell falso donde todos los comandos se registran

• Las entradas rechazadas se registran como intentos fallidos

Documentación del proyecto

Esta sección detalla las decisiones tomadas y los problemas encontrados durante el desarrollo de este proyecto. Sirve como reflexión del proceso de desarrollo y las lecciones aprendidas. Pase a Consideraciones de seguridad si solo desea saber cómo usar el proyecto.

Diseño de arquitectura y compensaciones

¿Por qué alojamiento en la nube?

• Los honeypots están diseñados para ser altamente disponibles con el fin de capturar y analizar datos las 24 horas del día. Si bien el honeypot podría implementarse en una máquina local utilizando máquinas virtuales o contenedores, mantener esa máquina en línea y accesible todo el tiempo no es práctico. El alojamiento en la nube proporciona una solución más práctica y confiable para alojar el honeypot y capturar datos de manera continua.
• Además, debido a que el alojamiento en la nube permite seleccionar recursos y servicios específicos, es más fácil crear y mantener una base de código que pueda implementarse y ampliarse. Cualquier persona interesada en implementar su propio honeypot puede hacerlo sin pasos adicionales, siempre que el proyecto funcione y el entorno aprovisionado coincida con lo que el proyecto espera.

¿Por qué DigitalOcean?

• Si bien hay otros proveedores como AWS, GCP y Azure, DigitalOcean ofrece una opción más asequible para este proyecto. Debido a que un honeypot debe permanecer en línea y enviar datos dentro y fuera del droplet las 24 horas del día, el modelo de precios de DigitalOcean ayudó a mantener los costos predecibles. Esto no tiene en cuenta las promociones de otros proveedores, como créditos gratuitos o descuentos para nuevos usuarios o compromisos a largo plazo.

¿Por qué Terraform?

• La alternativa, manual-deployment.sh, es para usuarios que no tienen experiencia con Terraform o prefieren no usarlo. Esa ruta requiere aprovisionar un droplet, conectarse a él, clonar el repositorio y ejecutar el script. Terraform permite una iteración más rápida: edite la base de código y vuelva a implementar sin repetir cada paso manual desde su máquina local. También facilita desmantelar la infraestructura y comenzar de nuevo. Si el proyecto crece de un solo honeypot a una honeynet, Terraform escala de manera más limpia que el aprovisionamiento manual o el script heredado por sí solo.

¿Por qué Cowrie?

• Cowrie es un honeypot de interacción media, bien conocido y mantenido activamente. Puede usar más recursos que trampas más ligeras, pero sus características y su ajuste con el resto del stack lo convirtieron en una opción natural. Se podrían intercambiar otros honeypots para casos de uso específicos, aunque muchos no están mantenidos o necesitan aún más recursos.

¿Por qué Loki?

• La principal limitación fue el hardware: agregación y búsqueda de registros en un droplet de 1 GB de RAM con varios otros servicios en ejecución. Elasticsearch era demasiado pesado. Graylog todavía depende de Elasticsearch internamente y no funcionaría correctamente dentro de los límites. Otras opciones consumían recursos similares. Grafana Loki coincidió con el stack y se mantuvo dentro del presupuesto excepto bajo consultas muy pesadas. Se sacrificaron algunas funciones de consulta: si los paneles obtienen demasiados datos, Loki se vuelve lento, la interfaz de usuario se siente poco receptiva y el honeypot puede perder o retrasar datos.

¿Por qué Grafana?

• Originalmente consideré un panel personalizado, pero Grafana es completo, personalizable y está bien documentado, lo que aceleró la configuración para que pudiera centrarme en recopilar y enviar registros. No es tan ligero como una interfaz de usuario personalizada mínima, pero después de una pequeña actualización del droplet se ejecuta cómodamente dentro de los límites del hardware. Otras herramientas con paneles predefinidos habrían usado más recursos sin beneficios claros para este caso de uso.

¿Por qué Promtail?

• Promtail es el transportista de registros Loki establecido (Grafana Alloy es el sucesor más nuevo). Promtail es ligero en RAM y admite etapas de canalización (análisis JSON, GeoIP, etiquetas) que coinciden con este proyecto. Alternativas como Fluentd o Logstash eran demasiado pesadas para un droplet de 1 GB.

¿Por qué GeoIP?

• Los mapas de ataques necesitan contexto de ciudad y país a partir de las IP de origen. El proyecto utiliza DB-IP City Lite a través de scripts/geoip-update.sh: sin cuenta ni clave API, lo que mantiene la implementación simple para cualquiera que clone el repositorio. La etapa GeoIP incorporada de Promtail lee el archivo MMDB local y agrega etiquetas para el panel Geomap de Grafana.

Recorrido de ejecución del sistema

Resumen paso a paso de lo que ocurre cuando se configura el honeypot usando Terraform o el script de implementación manual.

Terraform (recomendado)

En su máquina:

1. Configure terraform/terraform.tfvars: token API, ruta de la clave SSH pública, contraseña de Grafana, URL/rama del repositorio, manage_do_firewall opcional
2. Ejecute terraform init: instala el proveedor de DigitalOcean localmente
3. Ejecute terraform apply: Terraform crea un plan, luego crea o actualiza recursos

En DigitalOcean:

4. La clave SSH pública se carga en su cuenta
5. El droplet se crea a partir de sus variables de Terraform:
   • Imagen (Ubuntu), tamaño y región provienen de droplet_image, droplet_size, region, etc.
   • La clave SSH del paso 4 se adjunta
   • user_data se establece en el cloud-init renderizado: en el primer arranque la VM obtiene el puerto SSH de administración, git repo_url / repo_branch, y una copia codificada en base64 del .env generado (contraseña de Grafana y ADMIN_SSH_PORT de env.tftpl)
6. Firewall en la nube (solo cuando manage_do_firewall es verdadero):
   • Terraform crea un firewall de DigitalOcean y lo asocia con este droplet
   • TCP entrante: su puerto SSH de administración, 22, 23 y 3000 (consulte terraform/main.tf)
   • Saliente: TCP/UDP amplio e ICMP para que el droplet pueda actualizar paquetes, extraer imágenes y descargar datos de GeoIP

En el droplet, cloud-init se ejecuta automáticamente:

7. Cloud-config: package_update / package_upgrade, luego instala los paquetes listados (curl, git, ufw, …). Al inicio del arranque, write_files crea /root/honeypot.env (el env.tftpl renderizado por Terraform como base64: contraseña de Grafana, ADMIN_SSH_PORT, etc.)
8. Script de arranque runcmd (orden en terraform/templates/cloud-init.yaml.tftpl): establece los backends iptables / ip6tables a heredados
9. Swap: archivo de 2 GB si falta (/swapfile, fstab, swappiness)
10. Docker: instala Engine y el plugin Compose desde el repositorio apt de Docker; systemctl enable --now docker
11. SSH real: sshd en ADMIN_SSH_PORT; deshabilita ssh.socket para que el puerto 22 del host esté libre para Cowrie
12. Repositorio de la aplicación: git clone desde repo_url / repo_branch en /opt/honeypot (debe incluir docker-compose.yml y configuraciones)
13. .env en disco: mueve /root/honeypot.env a /opt/honeypot/.env (modo 600)
14. Firewall del host: scripts/setup-firewall.sh (UFW para SSH de administración, 22, 23, 3000)
15. GeoIP: scripts/geoip-update.sh (DB-IP City Lite en geoip/); añade una línea cron mensual para el mismo script
16. Montajes bind de Cowrie: crea data/cowrie-logs y data/cowrie-dl con permisos que espera Compose
17. Inicio del stack: desde /opt/honeypot, docker compose pull luego docker compose up -d

Dentro de Docker Compose:

18. Loki se inicia y debe pasar su verificación de salud (/ready en el puerto 3100 dentro del contenedor; en el host solo 127.0.0.1:3100)
19. Promtail y Grafana esperan a que Loki esté saludable (depends_on en docker-compose.yml), luego se inician
20. Cowrie puede iniciarse independientemente: publica los puertos del host 22 y 23 en el contenedor y escribe registros JSON en data/cowrie-logs para Promtail

Configuración manual (heredada)

El usuario crea la VM, se conecta por SSH y ejecuta el script desde el repositorio clonado.

manual-deployment.sh hace lo siguiente:

1. Carga y valida .env
2. Actualización del sistema: apt update y apt upgrade
3. Instala paquetes: herramientas más ufw e iptables
4. Configura swap: archivo de 2 GB si falta
5. Instala Docker: Engine + plugin Compose, habilita servicios
6. Configura SSH: sshd en ADMIN_SSH_PORT y deshabilita ssh.socket
7. Configura firewall: scripts/setup-firewall.sh
8. Configura GeoIP: scripts/geoip-update.sh y cron mensual
9. Inicia el stack: docker compose pull / up -d, luego el script espera las verificaciones de salud de Loki y Grafana e imprime un resumen

Problemas encontrados

Limitaciones de hardware

• Los recursos limitados de hardware resultaron en un rendimiento lento y tiempos de espera ocasionales. Esto afectó al panel que depende de poder consultar la base de datos rápidamente en intervalos establecidos por el usuario, a veces con múltiples dispositivos accediendo al panel al mismo tiempo.

Soluciones consideradas:

• Escalar verticalmente para obtener más recursos
• Panel personalizado con menos paneles para reducir la carga en la base de datos
• Limitar la cantidad de dispositivos que pueden acceder al panel simultáneamente
• Agregar registros en una base de datos separada para que el panel la lea y reducir la tensión en la base de datos principal

Resolución:

• Escaló a un droplet ligeramente más grande con mejor rendimiento

Compensaciones:

• Aunque el costo aumentó alrededor de $1-2 por mes, los recursos disponibles se duplicaron. El acceso a almacenamiento SSD NVMe y más RAM sobre el Droplet Básico permitió un panel más estable y con mejor rendimiento. Esto evitó tener que dedicar tiempo a crear un panel personalizado con menos paneles y una experiencia menos receptiva.

Lecciones aprendidas:

• Obtener tantos recursos como sea posible dentro del presupuesto aprovechando promociones, descuentos y niveles de precios. La diferencia entre el droplet más básico y un ligero aumento de costo resultó en duplicar los recursos disponibles, lo que ahorró tiempo al permitir un producto más completo. Además, poner el honeypot en funcionamiento antes significó capturar y analizar datos antes.

Problemas de tiempo de espera

• Al intentar SSH al droplet para acceso de administración, las conexiones expiraban. Por separado, docker compose up fallaba porque el puerto 22 ya estaba en uso y no podía ser vinculado por Cowrie.

Soluciones consideradas:

• sshd estaba mal configurado o escuchando en el puerto incorrecto
• Las reglas del firewall estaban bloqueando el puerto SSH de administración después de moverlo
• Otro proceso ya estaba usando el puerto 22

Resolución:

• Se corrigió el orden de operaciones: sshd se mueve a ADMIN_SSH_PORT (por defecto 2022) y se reinicia primero, luego se detiene y deshabilita ssh.socket para liberar el puerto 22 para que Docker lo vincule para Cowrie. Las reglas de UFW se aplican después de ambos pasos para permitir el nuevo puerto de administración.

Compensaciones:

• Sin compensaciones funcionales. Fue una corrección de configuración y orden.

Lecciones aprendidas:

• Es importante estar al tanto de cualquier servicio que necesite liberar recursos específicos en un orden particular antes de poder iniciarse. En este caso, en Ubuntu 24.04, ssh.socket es una unidad de socket de systemd que mantiene el puerto 22 reservado para activación SSH bajo demanda. Debe detenerse y deshabilitarse antes de que Docker pueda vincular el puerto 22 del host para Cowrie. Si sigue activo, docker compose up falla con "address already in use".

Mejoras futuras

Funcionalidad GeoIP

• El GeoIP a nivel de ciudad es aproximado. Los paneles del mapa dependen de la base de datos DB-IP y pueden omitir o etiquetar incorrectamente algunas IPs (móviles, VPNs, datos obsoletos). El stack podría ampliarse posteriormente con una base de datos diferente o un pipeline de enriquecimiento para mayor confianza en la geografía.

HTTPS de Grafana

• Grafana actualmente se ejecuta en HTTP. Una mejora futura sería colocarlo detrás de un proxy inverso (nginx o Caddy) con un certificado TLS, lo que también permitiría restringir el puerto de Grafana a localhost y proxy a través del 443.

Funcionalidad de servidor proxy

• Para que el honeypot parezca más legítimo, podría estar proxy a través de un servidor en una región diferente. Esto dificultaría que los atacantes lo identifiquen como un honeypot basándose en su IP o geolocalización.

Consideraciones de seguridad

• Grafana usa HTTP. El puerto 3000 sin TLS significa que las credenciales viajan en texto claro.
• Loki solo escucha en 127.0.0.1 (no está expuesto)
• terraform.tfvars está en gitignore y nunca debe ser commiteado
• Cowrie se ejecuta como un usuario no privilegiado dentro de su contenedor
• Grafana debe colocarse detrás de un proxy inverso con HTTPS si se expone más allá de un entorno de prueba

Contribuidores

• Oseguera12

Licencia

GNU General Public License Versión 2.0 (GPLv2) Consulte el texto completo de la licencia en el archivo LICENSE.