coalmine

Gestión de tokens canary en la nube — Despliega, monitoriza y rota credenciales señuelo en AWS y GCP para detectar accesos no autorizados.

[!WARNING] Versión Alfa — Coalmine está en desarrollo temprano. La funcionalidad básica es la prioridad actual, y la aplicación no debe considerarse completamente probada en seguridad para uso en producción.

Estado

Funcional	Desarrollo (Inestable)	Por Hacer
Canarios de Usuario IAM de AWS	Canarios de Cuenta de Servicio GCP	Soporte de Azure
Canarios de Bucket S3 de AWS	Canarios de Bucket GCP	Integración SIEM
Monitoreo de CloudTrail	Monitoreo de Registros de Auditoría GCP
Backend de Estado PostgreSQL	Rotación Automática
API REST (Clave API + Autenticación de Sesión)
Panel WebUI
Alertas por Correo y Webhook
Gestión de Credenciales y Cuentas
RBAC (Casbin)

Resumen

Coalmine despliega y monitoriza automáticamente "tokens canary" — credenciales y recursos señuelo que generan alertas cuando un atacante accede a ellos.

Proveedores soportados:

• AWS: Usuarios IAM, Buckets S3
• GCP: Cuentas de Servicio, Buckets de Cloud Storage

Características

• Soporte Multi-Nube — AWS y GCP desde una única interfaz
• Modelo de Credenciales y Cuentas — Gestiona credenciales y cuentas en la nube mediante CLI, API o sincronización YAML
• Rotación Automática — Las credenciales rotan en intervalos configurables
• Monitoreo Centralizado — Integración con CloudTrail y Registros de Auditoría GCP
• Alertas Flexibles — Notificaciones por correo, webhook y syslog
• Infraestructura como Código — Recursos gestionados por OpenTofu
• API REST — Acceso programático con clave API o autenticación de sesión
• WebUI — Panel de control basado en navegador en /ui
• RBAC — Control de acceso basado en roles mediante Casbin
• CLI — Estructura de subcomandos agrupados (coalmine <recurso> <acción>)

Inicio Rápido

Requisitos Previos

• Docker y Docker Compose
• Credenciales de AWS (para canarios de AWS)
• Credenciales de GCP (para canarios de GCP)

1. Clonar y Configurar

git clone https://github.com/yourorg/coalmine.git
cd coalmine
cp .env.example .env
# Edita .env con tu base de datos y credenciales de la nube

2. Iniciar Servicios

docker compose up -d

Esto inicia la API, el worker de Celery, Redis y PostgreSQL. El WebUI está disponible en http://localhost:8000/ui.

3. Registrar Credenciales y Cuentas

# Añadir una credencial de AWS
docker compose exec app coalmine credentials add my-aws-cred AWS \
  --secrets '{"access_key_id": "...", "secret_access_key": "...", "region": "us-east-1"}'

# Añadir una cuenta bajo esa credencial
docker compose exec app coalmine accounts add prod-east --credential my-aws-cred \
  --account-id 111111111111

# O sincronizar credenciales y cuentas desde configuración YAML
docker compose exec app coalmine credentials sync --dry-run

4. Crear un Recurso de Registro

# Crear destino de registro CloudTrail
docker compose exec app coalmine logs create my-trail AWS_CLOUDTRAIL \
  --account <ACCOUNT_ID>

# Listar recursos de registro
docker compose exec app coalmine logs list

5. Desplegar un Canario

# Crear un canario de Usuario IAM de AWS
docker compose exec app coalmine canary create my-canary AWS_IAM_USER \
  --account <ACCOUNT_ID> --logging-id <LOGGING_ID>

# Listar canarios
docker compose exec app coalmine canary list

6. Verificar Detección

# Disparar una alerta de prueba
docker compose exec app coalmine canary trigger my-canary

# Esperar el ciclo de monitoreo (~1 min) y luego revisar alertas
docker compose exec app coalmine alerts list

Arquitectura

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│     CLI     │   │  REST API   │   │   WebUI     │
│  (coalmine) │   │  (FastAPI)  │   │  (React)    │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │
       └────────┬────────┴────────┬────────┘
                │                 │
                │          ┌──────▼──────┐
                │          │Auth / RBAC  │
                │          │  (Casbin)   │
                │          └──────┬──────┘
                │                 │
         ┌──────▼─────────────────▼──────┐
         │         Celery Workers        │
         │  (Canary · Monitoring · Logs) │
         └──────────────┬────────────────┘
                        │
      ┌─────────────────┼─────────────────┐
      │                 │                 │
┌─────▼─────┐   ┌──────▼──────┐   ┌──────▼──────┐
│ OpenTofu  │   │  Monitors   │   │Notifications│
│ Templates │   │(CloudTrail/ │   │(Email/Hook/ │
│           │   │ Audit Logs) │   │   Syslog)   │
└─────┬─────┘   └──────┬──────┘   └─────────────┘
      │                │
┌─────▼─────┐   ┌──────▼──────┐
│ AWS / GCP │   │   Alerts    │
│(Resources)│   │    (DB)     │
└───────────┘   └─────────────┘

          ┌─────────────────┐
          │   PostgreSQL    │
          │   (Inventory)   │
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │   Celery Beat   │
          │   (Scheduler)   │
          └─────────────────┘

Referencia CLI

Los comandos siguen el patrón: coalmine <recurso> <acción> [opciones]

Comandos de Canarios

Comando	Descripción
canary create <name> <type>	Crear un nuevo canario
canary list	Listar todos los canarios
canary delete <name_or_id>	Eliminar un canario
canary creds <name>	Obtener credenciales del canario
canary trigger <name_or_id>	Probar detección del canario

Comandos de Credenciales

Comando	Descripción
credentials list	Listar todas las credenciales
credentials add <name> <provider>	Añadir una credencial
credentials update <name_or_id>	Actualizar una credencial
credentials remove <name_or_id>	Eliminar una credencial
credentials validate <name_or_id>	Validar estado de la credencial
credentials sync [--dry-run]	Sincronizar desde configuración YAML

Comandos de Cuentas

Comando	Descripción
accounts list [--credential <name>]	Listar todas las cuentas
accounts add <name>	Añadir una cuenta
accounts update <name_or_id>	Actualizar una cuenta
accounts enable <name_or_id>	Habilitar una cuenta
accounts disable <name_or_id>	Deshabilitar una cuenta
accounts remove <name_or_id>	Eliminar una cuenta
accounts validate <name_or_id>	Validar estado de la cuenta

Comandos de Registro

Comando	Descripción
logs create <name> <type>	Crear recurso de registro
logs list	Listar recursos de registro
logs scan --account <id>	Escanear CloudTrails existentes

Comandos de Alertas

Comando	Descripción
alerts list [--canary <name>]	Ver alertas de seguridad

Comandos de Autenticación

Comando	Descripción
auth key list	Listar claves API
auth key add <name>	Añadir una clave API
auth session list	Listar sesiones activas

Comandos de Usuario

Comando	Descripción
user list	Listar todos los usuarios
user roles	Listar roles disponibles

Comandos de Tareas