coalmine

Gerenciamento de Tokens Canary na Nuvem — Implante, monitore e rotacione credenciais enganosas em AWS e GCP para detectar acesso não autorizado.

[!WARNING] Versão Alpha — O Coalmine está em desenvolvimento inicial. A funcionalidade básica é a prioridade atual, e a aplicação não deve ser considerada totalmente testada em segurança para uso em produção.

Status

Funcional	Em Desenvolvimento (Instável)	A Fazer
Canários de Usuário IAM da AWS	Canários de Conta de Serviço do GCP	Suporte Azure
Canários de Bucket S3 da AWS	Canários de Bucket do GCP	Integração SIEM
Monitoramento CloudTrail	Monitoramento de Logs de Auditoria do GCP
Backend de Estado PostgreSQL	Rotação Automática
API REST (Chave de API + Autenticação por Sessão)
Painel WebUI
Alertas por E-mail e Webhook
Gerenciamento de Credenciais e Contas
RBAC (Casbin)

Visão Geral

O Coalmine implanta e monitora automaticamente "tokens canary" — credenciais e recursos isca que disparam alertas quando acessados por atacantes.

Provedores Suportados:

• AWS: Usuários IAM, Buckets S3
• GCP: Contas de Serviço, Buckets Cloud Storage

Funcionalidades

• Suporte a Múltiplas Nuvens — AWS e GCP a partir de uma única interface
• Modelo de Credenciais e Contas — Gerencie credenciais e contas em nuvem via CLI, API ou sincronização YAML
• Rotação Automática — Credenciais rotacionam em intervalos configuráveis
• Monitoramento Centralizado — Integração com CloudTrail e Logs de Auditoria do GCP
• Alertas Flexíveis — Notificações por E-mail, Webhook e Syslog
• Infraestrutura como Código — Recursos gerenciados pelo OpenTofu
• API REST — Acesso programático com chave de API ou autenticação por sessão
• WebUI — Painel baseado em navegador em /ui
• RBAC — Controle de acesso baseado em funções via Casbin
• CLI — Estrutura de subcomandos agrupados (coalmine <recurso> <ação>)

Guia de Início Rápido

Pré-requisitos

• Docker e Docker Compose
• Credenciais AWS (para canários AWS)
• Credenciais GCP (para canários GCP)

1. Clone e Configure

git clone https://github.com/yourorg/coalmine.git
cd coalmine
cp .env.example .env
# Edite .env com suas credenciais de banco de dados e nuvem

2. Inicie os Serviços

docker compose up -d

Isso inicia a API, o worker Celery, o Redis e o PostgreSQL. O WebUI estará disponível em http://localhost:8000/ui.

3. Registre Credenciais e Contas

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

# Adicione uma conta sob essa credencial
docker compose exec app coalmine accounts add prod-east --credential my-aws-cred \
  --account-id 111111111111

# Ou sincronize credenciais e contas a partir de um arquivo YAML
docker compose exec app coalmine credentials sync --dry-run

4. Crie um Recurso de Log

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

# Liste os recursos de log
docker compose exec app coalmine logs list

5. Implante um Canary

# Crie um canary de usuário IAM da AWS
docker compose exec app coalmine canary create my-canary AWS_IAM_USER \
  --account <ACCOUNT_ID> --logging-id <LOGGING_ID>

# Liste canaries
docker compose exec app coalmine canary list

6. Verifique a Detecção

# Dispare um alerta de teste
docker compose exec app coalmine canary trigger my-canary

# Aguarde o ciclo de monitoramento (~1 min) e depois verifique os alertas
docker compose exec app coalmine alerts list

Arquitetura

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│     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)   │
          └─────────────────┘

Referência da CLI

Os comandos seguem o padrão: coalmine <recurso> <ação> [opções]

Comandos de Canary

Comando	Descrição
canary create <nome> <tipo>	Cria um novo canary
canary list	Lista todos os canaries
canary delete <nome_ou_id>	Exclui um canary
canary creds <nome>	Obtém as credenciais do canary
canary trigger <nome_ou_id>	Testa a detecção do canary

Comandos de Credencial

Comando	Descrição
credentials list	Lista todas as credenciais
credentials add <nome> <provedor>	Adiciona uma credencial
credentials update <nome_ou_id>	Atualiza uma credencial
credentials remove <nome_ou_id>	Remove uma credencial
credentials validate <nome_ou_id>	Valida a saúde da credencial
credentials sync [--dry-run]	Sincroniza a partir de configuração YAML

Comandos de Conta

Comando	Descrição
accounts list [--credential <nome>]	Lista todas as contas
accounts add <nome>	Adiciona uma conta
accounts update <nome_ou_id>	Atualiza uma conta
accounts enable <nome_ou_id>	Ativa uma conta
accounts disable <nome_ou_id>	Desativa uma conta
accounts remove <nome_ou_id>	Remove uma conta
accounts validate <nome_ou_id>	Valida a saúde da conta

Comandos de Log

Comando	Descrição
logs create <nome> <tipo>	Cria recurso de log
logs list	Lista recursos de log
logs scan --account <id>	Escaneia CloudTrails existentes

Comandos de Alerta

Comando	Descrição
alerts list [--canary <nome>]	Visualiza alertas de segurança

Comandos de Autenticação

Comando	Descrição
auth key list	Lista chaves de API
auth key add <nome>	Adiciona uma chave de API
auth session list	Lista sessões ativas

Comandos de Usuário

Comando	Descrição
user list	Lista todos os usuários
user roles	Lista as funções disponíveis

Comandos de Tarefa

Comando	Descrição
task list	Visualiza tarefas assíncronas recentes
task status <task_id>	Verifica o resultado de uma tarefa

Ajuda