Cloud Canary Token Management — Deploy, monitor, and rotate deceptive credentials across AWS and GCP to detect unauthorized access.

Coalmine automatically deploys and monitors "canary tokens" — decoy credentials and resources that trigger alerts when accessed by attackers.

Supported Providers:

• AWS: IAM Users, S3 Buckets
• GCP: Service Accounts, Cloud Storage Buckets

• Multi-Cloud Support — AWS and GCP from a single interface
• Credential & Account Model — Manage cloud credentials and accounts through CLI, API, or YAML sync
• Automatic Rotation — Credentials rotate on configurable intervals
• Centralized Monitoring — CloudTrail and GCP Audit Log integration
• Flexible Alerting — Email, Webhook, and Syslog notifications
• Infrastructure as Code — OpenTofu-managed resources
• REST API — Programmatic access with API key or session authentication
• WebUI — Browser-based dashboard at /ui
• RBAC — Role-based access control via Casbin
• CLI — Grouped subcommand structure (coalmine <resource> <action>)

• Docker & Docker Compose
• AWS credentials (for AWS canaries)
• GCP credentials (for GCP canaries)

git clone https://github.com/yourorg/coalmine.git
cd coalmine
cp .env.example .env
# Edit .env with your database and cloud credentials

docker compose up -d

This starts the API, Celery worker, Redis, and PostgreSQL. The WebUI is available at http://localhost:8000/ui.

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

# Add an account under that credential
docker compose exec app coalmine accounts add prod-east --credential my-aws-cred \
  --account-id 111111111111

# Or sync credentials and accounts from YAML config
docker compose exec app coalmine credentials sync --dry-run

# Create CloudTrail logging destination
docker compose exec app coalmine logs create my-trail AWS_CLOUDTRAIL \
  --account <ACCOUNT_ID>

# List logging resources
docker compose exec app coalmine logs list

# Create an AWS IAM User canary
docker compose exec app coalmine canary create my-canary AWS_IAM_USER \
  --account <ACCOUNT_ID> --logging-id <LOGGING_ID>

# List canaries
docker compose exec app coalmine canary list

# Trigger a test alert
docker compose exec app coalmine canary trigger my-canary

# Wait for monitoring cycle (~1 min) then check alerts
docker compose exec app coalmine alerts list

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

Commands follow the pattern: coalmine <resource> <action> [options]

docker compose exec app coalmine --help
docker compose exec app coalmine canary --help

The API runs at http://localhost:8000 and requires authentication via API key header or session cookie.

api_keys:
  - key: "your-api-key-here"
    name: "admin"
    permissions: ["read", "write"]
    scopes: ["all"]

# List canaries
curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/canaries

# Create a canary
curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "api-canary", "resource_type": "AWS_IAM_USER", "account_id": "...", "logging_id": "..."}' \
  http://localhost:8000/api/v1/canaries

Interactive API docs are available at http://localhost:8000/docs (Swagger UI).

All configuration lives in the config/ directory. See config/README.md for details.

credentials:
  my-aws-cred:
    provider: AWS
    auth_type: STATIC
    secrets:
      access_key_id: ${AWS_ACCESS_KEY_ID}
      secret_access_key: ${AWS_SECRET_ACCESS_KEY}
      region: ${AWS_DEFAULT_REGION:-us-east-1}
    accounts:
      - name: prod-east
        account_id: "111111111111"

Sync with: docker compose exec app coalmine credentials sync

outputs:
  email_admin:
    type: "email"
    enabled: true
    smtp_host: "smtp.example.com"
    smtp_port: 587
    to_addrs: ["security@example.com"]
  
  webhook_siem:
    type: "webhook"
    enabled: true
    url: "https://siem.example.com/webhook"

# Run all tests
docker compose run --rm app pytest -v

# Run unit tests only
docker compose run --rm app pytest tests/unit/ -v

# Run integration tests
docker compose run --rm app pytest tests/integration/ -v

# View worker logs
docker compose logs -f worker

# Rebuild after code changes
docker compose build && docker compose up -d

• Never commit credentials — Use .env files or secrets managers
• Rotate admin credentials — The cloud credentials used to manage canaries
• Network isolation — Run Coalmine in a secure network segment
• Principle of least privilege — Canary credentials should have minimal permissions
• API key security — Store API keys securely, rotate regularly

Apache License 2.0 — See LICENSE file for details.

See CONTRIBUTING.md for contribution guidelines.