coalmine

Cloud Canary Token Verwaltung — Bereitstellung, Überwachung und Rotation von Täuschungsanmeldeinformationen über AWS und GCP zur Erkennung unbefugten Zugriffs.

[!WARNING] Alpha-Version — Coalmine befindet sich in der frühen Entwicklung. Die grundlegende Funktionalität hat derzeit Priorität, und die Anwendung sollte nicht als vollständig sicherheitsgeprüft für den Produktionseinsatz betrachtet werden.

Status

Funktionsfähig	In Entwicklung (Instabil)	Noch zu erledigen
AWS IAM User Canaries	GCP Service Account Canaries	Azure-Unterstützung
AWS S3 Bucket Canaries	GCP Bucket Canaries	SIEM-Integration
CloudTrail-Überwachung	GCP Audit Log-Überwachung
PostgreSQL-Zustands-Backend	Automatische Rotation
REST API (API-Schlüssel + Sitzungsauthentifizierung)
WebUI-Dashboard
E-Mail- & Webhook-Benachrichtigungen
Anmeldeinformations- & Kontoverwaltung
RBAC (Casbin)

Überblick

Coalmine setzt automatisch „Canary Tokens“ ein und überwacht sie – das sind Täuschungsanmeldeinformationen und -ressourcen, die bei Zugriff durch Angreifer einen Alarm auslösen.

Unterstützte Anbieter:

• AWS: IAM-Benutzer, S3-Buckets
• GCP: Dienstkonten, Cloud Storage-Buckets

Funktionen

• Multi-Cloud-Unterstützung — AWS und GCP aus einer einzigen Oberfläche
• Anmeldeinformations- & Kontomodell — Verwaltung von Cloud-Anmeldeinformationen und -Konten über CLI, API oder YAML-Synchronisierung
• Automatische Rotation — Anmeldeinformationen rotieren in konfigurierbaren Intervallen
• Zentralisierte Überwachung — Integration von CloudTrail und GCP Audit Logs
• Flexible Alarmierung — Benachrichtigungen per E-Mail, Webhook und Syslog
• Infrastruktur als Code — Von OpenTofu verwaltete Ressourcen
• REST API — Programmgesteuerter Zugriff mit API-Schlüssel oder Sitzungsauthentifizierung
• WebUI — Browserbasiertes Dashboard unter /ui
• RBAC — Rollenbasierte Zugriffskontrolle über Casbin
• CLI — Gruppierte Befehlsstruktur (coalmine <resource> <action>)

Schnellstart

Voraussetzungen

• Docker & Docker Compose
• AWS-Anmeldeinformationen (für AWS-Canaries)
• GCP-Anmeldeinformationen (für GCP-Canaries)

1. Klonen und Konfigurieren

git clone https://github.com/yourorg/coalmine.git
cd coalmine
cp .env.example .env
# Bearbeiten Sie .env mit Ihren Datenbank- und Cloud-Anmeldeinformationen

2. Dienste starten

docker compose up -d

Dadurch werden die API, der Celery Worker, Redis und PostgreSQL gestartet. Das WebUI ist unter http://localhost:8000/ui verfügbar.

3. Anmeldeinformationen und Konten registrieren

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

# Konto unter dieser Anmeldeinformation hinzufügen
docker compose exec app coalmine accounts add prod-east --credential my-aws-cred \
  --account-id 111111111111

# Oder Anmeldeinformationen und Konten aus YAML-Konfiguration synchronisieren
docker compose exec app coalmine credentials sync --dry-run

4. Protokollierungsressource erstellen

# CloudTrail-Protokollierungsziel erstellen
docker compose exec app coalmine logs create my-trail AWS_CLOUDTRAIL \
  --account <ACCOUNT_ID>

# Protokollierungsressourcen auflisten
docker compose exec app coalmine logs list

5. Canary bereitstellen

# AWS IAM-Benutzer-Canary erstellen
docker compose exec app coalmine canary create my-canary AWS_IAM_USER \
  --account <ACCOUNT_ID> --logging-id <LOGGING_ID>

# Canarys auflisten
docker compose exec app coalmine canary list

6. Erkennung überprüfen

# Testalarm auslösen
docker compose exec app coalmine canary trigger my-canary

# Auf Überwachungszyklus warten (~1 Min.), dann Alarme prüfen
docker compose exec app coalmine alerts list

Architektur

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

CLI-Referenz

Befehle folgen dem Muster: coalmine <resource> <action> [options]

Canary-Befehle

Befehl	Beschreibung
canary create <name> <type>	Neuen Canary erstellen
canary list	Alle Canarys auflisten
canary delete <name_or_id>	Canary löschen
canary creds <name>	Canary-Anmeldeinformationen abrufen
canary trigger <name_or_id>	Canary-Erkennung testen

Befehle für Anmeldeinformationen

Befehl	Beschreibung
credentials list	Alle Anmeldeinformationen auflisten
credentials add <name> <provider>	Anmeldeinformation hinzufügen
credentials update <name_or_id>	Anmeldeinformation aktualisieren
credentials remove <name_or_id>	Anmeldeinformation entfernen
credentials validate <name_or_id>	Gesundheitszustand der Anmeldeinformationen überprüfen
credentials sync [--dry-run]	Von YAML-Konfiguration synchronisieren

Kontobefehle

Befehl	Beschreibung
accounts list [--credential <name>]	Alle Konten auflisten
accounts add <name>	Konto hinzufügen
accounts update <name_or_id>	Konto aktualisieren
accounts enable <name_or_id>	Konto aktivieren
accounts disable <name_or_id>	Konto deaktivieren
accounts remove <name_or_id>	Konto entfernen
accounts validate <name_or_id>	Gesundheitszustand des Kontos überprüfen

Protokollierungsbefehle

Befehl	Beschreibung
logs create <name> <type>	Protokollierungsressource erstellen
logs list	Protokollierungsressourcen auflisten
logs scan --account <id>	Vorhandene CloudTrails scannen

Alarmbefehle

Befehl	Beschreibung
alerts list [--canary <name>]	Sicherheitswarnungen anzeigen

Authentifizierungsbefehle

Befehl	Beschreibung
auth key list	API-Schlüssel auflisten
auth key add <name>	API-Schlüssel hinzufügen
auth session list	Aktive Sitzungen auflisten

Benutzerbefehle