CrowdSec: de cero a protección real — guía práctica para principiantes

CrowdSec es un sistema de detección de intrusión (IDS) ligero, colaborativo y extensible que convierte los registros de tus servicios en decisiones de bloqueo ejecutadas por remediation components (antes llamados bouncers). Ya tratamos su despliegue con Docker, Traefik y bouncer de firewall en CrowdSec con Docker, Traefik y bouncer firewall; aquí nos centramos en los principios fundamentales para ponerlo en marcha desde cero en un servidor Debian/Ubuntu, instalando el Security Engine, configurando bouncers y protegiendo un servicio web real paso a paso.

Advertencia: la instalación de componentes a nivel de kernel (iptables/nftables) y la exposición de la API local (puerto 8080) requieren privilegios de root y acceso a la consola de emergencia del proveedor. Prueba primero en un entorno no productivo.

---

1. Conceptos clave y arquitectura

Componente	Función	Nota
Security Engine	Motor de detección: adquiere logs, los parsea, evalúa scenarios y emite decisiones	No bloquea por sí mismo
Acquisition	Define qué ficheros/registros leer (syslog, journald, archivos planos)	/etc/crowdsec/acquis.yaml
Parsers	Normalizan líneas de log a eventos estructurados	Proveídos por hub
Scenarios	Reglas de correlación (fuerza bruta, escaneo, etc.)	Proveídos por hub
Decisions	Acciones derivadas (ban IP, captcha, rate-limit)	Tienen TTL y alcance
Local API (LAPI)	Expone decisiones a los bouncers (puerto 8080/TCP, localhost)	Requiere API key por bouncer
Remediation Component (Bouncer)	Aplica la decisión en el plano de datos (firewall, Nginx, Cloudflare, etc.)	No decide, solo ejecuta

El flujo es: logs → parsers → scenarios → decisions → LAPI → bouncer → enforcement [1][2].

---

2. Requisitos previos

Recurso	Mínimo recomendado
CPU	1 núcleo
RAM	100 MB libres
Disco	1 GB libre (base de datos SQLite por defecto)
SO	Debian 12 / Ubuntu 22.04+ (amd64, arm64)
Puertos	6060/TCP (métricas Prometheus), 8080/TCP (LAPI) — solo loopback por defecto

---

3. Instalación del Security Engine (Debian/Ubuntu)

3.1 Añadir repositorio oficial

# Opción rápida (script oficial)
curl -s https://install.crowdsec.net | sudo sh

# Opción manual (control total)
sudo apt update
sudo apt install -y curl gnupg apt-transport-https
mkdir -p /etc/apt/keyrings
curl -fsSL https://packagecloud.io/crowdsec/crowdsec/gpgkey \
  | gpg --dearmor > /etc/apt/keyrings/crowdsec_crowdsec-archive-keyring.gpg

cat <<'EOF' | sudo tee /etc/apt/sources.list.d/crowdsec_crowdsec.list
deb [signed-by=/etc/apt/keyrings/crowdsec_crowdsec-archive-keyring.gpg] https://packagecloud.io/crowdsec/crowdsec/any any main
deb-src [signed-by=/etc/apt/keyrings/crowdsec_crowdsec-archive-keyring.gpg] https://packagecloud.io/crowdsec/crowdsec/any any main
EOF

sudo apt update

3.2 Fijar prioridad del repo (evita versiones antiguas de Ubuntu Pro/ESM)

cat <<'EOF' | sudo tee /etc/apt/preferences.d/crowdsec
Package: *
Pin: release o=packagecloud.io/crowdsec/crowdsec,a=any,n=any,c=main
Pin-Priority: 1001
EOF
sudo apt update
apt-cache policy crowdsec   # debe mostrar Candidate ≥ 1.6.x

3.3 Instalar motor y bouncer de firewall (iptables)

sudo apt install crowdsec crowdsec-firewall-bouncer-iptables

El paquete crowdsec-firewall-bouncer-iptables registra un systemd service que consulta la LAPI cada 10 s y añade reglas DROP en la cadena INPUT para las IPs con decisión ban [1].

3.4 Verificar servicios

systemctl status crowdsec
systemctl status crowdsec-firewall-bouncer
cscli version
cscli decisions list

---

4. Configuración básica tras la instalación

Acción	Comando	Qué hace
Ver parsers y scenarios instalados	cscli parsers list / cscli scenarios list	Muestra colecciones cargadas desde el hub
Añadir colección (ej. nginx)	sudo cscli collections install crowdsecurity/nginx	Descarga parsers + scenarios para logs de Nginx
Revisar adquisiciones	cat /etc/crowdsec/acquis.yaml	Asegura que /var/log/nginx/*.log esté presente
Generar API key para un bouncer	sudo cscli bouncers add mi-nginx-bouncer	Devuelve una clave (guárdala)
Probar conectividad LAPI	curl -H "X-Api-Key: <KEY>" http://127.0.0.1:8080/v1/decisions	Debe devolver JSON (array vacío al inicio)

Nota: la LAPI escucha solo en 127.0.0.1:8080 por defecto. Para bouncers remotos, edita listen_addr en /etc/crowdsec/local_api_credentials.yaml y abre el puerto en el firewall del host.

---

5. Caso real: proteger una aplicación web detrás de Nginx

5.1 Instalar el nginx bouncer (WAF + virtual patching)

sudo apt install crowdsec-nginx-bouncer

Durante la instalación se pedirá la API key generada en el paso anterior. El paquete compila un módulo Lua y modifica /etc/nginx/nginx.conf añadiendo:

load_module /usr/lib/nginx/modules/ngx_http_crowdsec_module.so;

y dentro del bloque http {}:

crowdsec_agent on;
crowdsec_agent_lapi http://127.0.0.1:8080;
crowdsec_agent_api_key <TU_API_KEY>;

5.2 Recargar Nginx y validar

sudo nginx -t && sudo systemctl reload nginx
curl -I http://example.com   # cabecera X-CrowdSec-Decision si hay ban

5.3 Simular un ataque de fuerza bruta SSH (para ver decisión en firewall)

# Desde otra máquina (o contenedor) intenta login fallido repetido
for i in {1..10}; do ssh usuario@example.com -o PasswordAuthentication=yes; done

En el servidor:

cscli decisions list
# Debe aparecer la IP atacante con decision=ban, origin=cscli/ssh-bf

El firewall bouncer habrá insertado una regla iptables -A INPUT -s <IP> -j DROP.

---

6. Monitorización y mantenimiento

Tarea	Comando	Frecuencia
Listar decisiones activas	cscli decisions list	Diaria
Ver alertas recientes	cscli alerts list --since 24h	Diaria
Actualizar colecciones del hub	sudo cscli hub update && sudo cscli hub upgrade	Semanal
Revisar métricas Prometheus	curl http://127.0.0.1:6060/metrics	Continua (Grafana/Prometheus)
Rotar logs de CrowdSec	logrotate /etc/logrotate.d/crowdsec	Mensual

---

7. Buenas prácticas y siguientes pasos

1. Habilita el modo colaborativo (cscli capi register) para recibir la community blocklist y compartir tus detecciones anónimas.
2. Separa LAPI y bouncers en hosts distintos para alta disponibilidad (usa MTLS).
3. Integra con SIEM (Elastic, Splunk) vía la API /v1/alerts.
4. Ajusta profiles y simulation (cscli simulation enable) antes de pasar a live en producción.
5. Backup de la base de datos (/var/lib/crowdsec/data/crowdsec.db) antes de actualizaciones mayores.

---

Conclusiones / En resumen

1. CrowdSec separa detección (Security Engine) de reacción (bouncers), lo que permite escalar y combinar capas (L3/L4 + L7).
2. La instalación en Debian/Ubuntu es trivial gracias al repositorio oficial; el firewall bouncer protege SSH, bases de datos y SMTP sin tocar la aplicación.
3. Para aplicaciones web, el nginx bouncer aporta WAF y virtual patching en‑line sin modificar el código de la app.
4. La visibilidad (cscli, métricas Prometheus) y la comunidad convierten a CrowdSec en una opción viable frente a soluciones propietarias caras.

---

📚 Fuentes consultadas

1. Linux installation – CrowdSec Docs
2. Introduction – CrowdSec Docs
3. Remediation Components (Bouncers) – CrowdSec Docs
4. Nginx Bouncer installation – CrowdSec Docs
5. Firewall Bouncer (iptables) – CrowdSec Docs
6. Post‑installation steps – CrowdSec Docs