Coalmine — Gestione dei Canary Token

Gestione dei Canary Token su Cloud — Distribuisci, monitora e ruota credenziali ingannevoli su AWS e GCP per rilevare accessi non autorizzati.

[!WARNING] Versione Alpha — Coalmine è in fase di sviluppo iniziale. La funzionalità di base è la priorità attuale e l'applicazione non dovrebbe essere considerata completamente testata per la sicurezza per l'uso in produzione.

Stato

Funzionale	Sviluppo (Instabile)	Da Fare
AWS IAM User Canaries	GCP Service Account Canaries	Supporto Azure
AWS S3 Bucket Canaries	GCP Bucket Canaries	Integrazione SIEM
Monitoraggio CloudTrail	Monitoraggio Log Audit GCP
Backend di Stato PostgreSQL	Rotazione Automatica
API REST (Chiave API + Autenticazione Sessione)
Dashboard WebUI
Avvisi Email e Webhook
Gestione Credenziali e Account
RBAC (Casbin)

Panoramica

Coalmine distribuisce e monitora automaticamente "canary token" — credenziali e risorse esca che attivano avvisi quando vengono acceduti da parte degli aggressori.

Provider Supportati:

AWS: Utenti IAM, Bucket S3
GCP: Account di Servizio, Bucket Cloud Storage

Funzionalità

Supporto Multi-Cloud — AWS e GCP da un'unica interfaccia
Modello Credenziali e Account — Gestisci credenziali e account cloud tramite CLI, API o sincronizzazione YAML
Rotazione Automatica — Le credenziali vengono ruotate a intervalli configurabili
Monitoraggio Centralizzato — Integrazione con CloudTrail e GCP Audit Log
Avvisi Flessibili — Notifiche via Email, Webhook e Syslog
Infrastruttura come Codice — Risorse gestite da OpenTofu
API REST — Accesso programmatico con chiave API o autenticazione di sessione
WebUI — Dashboard basata su browser su /ui
RBAC — Controllo degli accessi basato sui ruoli tramite Casbin
CLI — Struttura di sottocomandi raggruppati (coalmine <risorsa> <azione>)

Avvio Rapido

Prerequisiti

Docker e Docker Compose
Credenziali AWS (per canary AWS)
Credenziali GCP (per canary GCP)

1. Clona e Configura

git clone https://github.com/yourorg/coalmine.git
cd coalmine
cp .env.example .env
# Modifica .env con le tue credenziali del database e cloud

2. Avvia i Servizi

docker compose up -d

Questo avvia API, worker Celery, Redis e PostgreSQL. La WebUI è disponibile su http://localhost:8000/ui.

3. Registra Credenziali e Account

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

# Aggiungi un account sotto quella credenziale
docker compose exec app coalmine accounts add prod-east --credential my-aws-cred \
  --account-id 111111111111

# Oppure sincronizza credenziali e account da un file YAML
docker compose exec app coalmine credentials sync --dry-run

4. Crea una Risorsa di Logging

# Crea una destinazione di logging CloudTrail
docker compose exec app coalmine logs create my-trail AWS_CLOUDTRAIL \
  --account <ACCOUNT_ID>

# Elenca le risorse di logging
docker compose exec app coalmine logs list

5. Distribuisci un Canary

# Crea un canary utente IAM AWS
docker compose exec app coalmine canary create my-canary AWS_IAM_USER \
  --account <ACCOUNT_ID> --logging-id <LOGGING_ID>

# Elenca i canary
docker compose exec app coalmine canary list

6. Verifica il Rilevamento

# Attiva un avviso di test
docker compose exec app coalmine canary trigger my-canary

# Attendi il ciclo di monitoraggio (~1 min) poi controlla gli avvisi
docker compose exec app coalmine alerts list

Architettura

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│     CLI     │   │  REST API   │   │   WebUI     │
│  (coalmine) │   │  (FastAPI)  │   │  (React)    │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │
       └────────┬────────┴────────┬────────┘
                │                 │
                │          ┌──────▼──────┐
                │          │Auth / RBAC  │
                │          │  (Casbin)   │
                │          └──────┬──────┘
                │                 │
         ┌──────▼─────────────────▼──────┐
         │         Celery Workers        │
         │  (Canary · Monitoraggio · Logs)│
         └──────────────┬────────────────┘
                        │
      ┌─────────────────┼─────────────────┐
      │                 │                 │
┌─────▼─────┐   ┌──────▼──────┐   ┌──────▼──────┐
│ Template  │   │  Monitor    │   │ Notifiche   │
│ OpenTofu  │   │(CloudTrail/ │   │(Email/Hook/ │
│           │   │ Log Audit)  │   │   Syslog)   │
└─────┬─────┘   └──────┬──────┘   └─────────────┘
      │                │
┌─────▼─────┐   ┌──────▼──────┐
│ AWS / GCP │   │   Avvisi    │
│(Risorse)  │   │    (DB)     │
└───────────┘   └─────────────┘

          ┌─────────────────┐
          │   PostgreSQL    │
          │   (Inventario)  │
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │   Celery Beat   │
          │ (Pianificatore) │
          └─────────────────┘

Riferimento CLI

I comandi seguono lo schema: coalmine <risorsa> <azione> [opzioni]

Comandi Canary

Comando	Descrizione
`canary create <nome> <tipo>`	Crea un nuovo canary
`canary list`	Elenca tutti i canary
`canary delete <nome_o_id>`	Elimina un canary
`canary creds <nome>`	Ottieni le credenziali del canary
`canary trigger <nome_o_id>`	Testa il rilevamento del canary

Comandi Credenziali

Comando	Descrizione
`credentials list`	Elenca tutte le credenziali
`credentials add <nome> <provider>`	Aggiungi una credenziale
`credentials update <nome_o_id>`	Aggiorna una credenziale
`credentials remove <nome_o_id>`	Rimuovi una credenziale
`credentials validate <nome_o_id>`	Convalida lo stato della credenziale
`credentials sync [--dry-run]`	Sincronizza dalla configurazione YAML

Comandi Account

Comando	Descrizione
`accounts list [--credential <nome>]`	Elenca tutti gli account
`accounts add <nome>`	Aggiungi un account
`accounts update <nome_o_id>`	Aggiorna un account
`accounts enable <nome_o_id>`	Abilita un account
`accounts disable <nome_o_id>`	Disabilita un account
`accounts remove <nome_o_id>`	Rimuovi un account
`accounts validate <nome_o_id>`	Convalida lo stato dell'account

Comandi di Logging

Comando	Descrizione
`logs create <nome> <tipo>`	Crea una risorsa di logging
`logs list`	Elenca le risorse di logging
`logs scan --account <id>`	Scansiona CloudTrail esistenti

Comandi Avvisi

Comando	Descrizione
`alerts list [--canary <nome>]`	Visualizza gli avvisi di sicurezza

Comandi Autenticazione

Comando	Descrizione
`auth key list`	Elenca le chiavi API
`auth key add <nome>`	Aggiungi una chiave API
`auth session list`	Elenca le sessioni attive

Comandi Utente

Comando	Descrizione
`user list`	Elenca tutti gli utenti
`user roles`	Elenca i ruoli disponibili

Comandi Attività

Comando	Descrizione
`task list`	Visualizza le attività asincrone recenti
`task status <task_id>`	Controlla il risultato di un'attività

coalmine

Più Popolari