coalmine

クラウドカナリートークン管理 — AWSおよびGCP全体で偽装認証情報を展開、監視、ローテーションし、不正アクセスを検出します。

[!WARNING] アルファ版 — Coalmineは初期開発段階です。基本機能が現在の優先事項であり、本番環境で使用するには完全なセキュリティテストが行われていないと見なすべきです。

ステータス

機能実装済み	開発中 (不安定)	未実装
AWS IAM ユーザーカナリア	GCP サービスアカウントカナリア	Azure サポート
AWS S3 バケットカナリア	GCP バケットカナリア	SIEM 統合
CloudTrail 監視	GCP 監査ログ監視
PostgreSQL ステートバックエンド	自動ローテーション
REST API (APIキー + セッション認証)
WebUI ダッシュボード
メールおよび Webhook アラート
認証情報およびアカウント管理
RBAC (Casbin)

概要

Coalmineは自動的に「カナリートークン」を展開し監視します。これは、攻撃者によってアクセスされたときにアラートを発動する偽装認証情報やリソースです。

サポート対象プロバイダー:

• AWS: IAM ユーザー、S3 バケット
• GCP: サービスアカウント、Cloud Storage バケット

機能

• マルチクラウド対応 — 単一インターフェースからAWSとGCPを管理
• 認証情報・アカウントモデル — CLI、API、またはYAML同期でクラウド認証情報とアカウントを管理
• 自動ローテーション — 設定可能な間隔で認証情報をローテーション
• 集中監視 — CloudTrailおよびGCP監査ログとの統合
• 柔軟なアラート通知 — メール、Webhook、Syslog通知
• Infrastructure as Code — OpenTofu管理のリソース
• REST API — APIキーまたはセッション認証によるプログラムアクセス
• WebUI — /ui のブラウザベースダッシュボード
• RBAC — Casbinによるロールベースアクセス制御
• CLI — グループ化されたサブコマンド構造 (coalmine <resource> <action>)

クイックスタート

前提条件

• Docker & Docker Compose
• AWS認証情報（AWSカナリア用）
• GCP認証情報（GCPカナリア用）

1. クローンと設定

git clone https://github.com/yourorg/coalmine.git
cd coalmine
cp .env.example .env
# .envファイルを編集してデータベースとクラウド認証情報を設定

2. サービスの起動

docker compose up -d

これによりAPI、Celeryワーカー、Redis、PostgreSQLが起動します。WebUIは http://localhost:8000/ui で利用できます。

3. 認証情報とアカウントの登録

# AWS認証情報を追加
docker compose exec app coalmine credentials add my-aws-cred AWS \
  --secrets '{"access_key_id": "...", "secret_access_key": "...", "region": "us-east-1"}'

# その認証情報の下にアカウントを追加
docker compose exec app coalmine accounts add prod-east --credential my-aws-cred \
  --account-id 111111111111

# またはYAML設定から認証情報とアカウントを同期
docker compose exec app coalmine credentials sync --dry-run

4. ロギングリソースの作成

# CloudTrailログ出力先を作成
docker compose exec app coalmine logs create my-trail AWS_CLOUDTRAIL \
  --account <ACCOUNT_ID>

# ロギングリソース一覧
docker compose exec app coalmine logs list

5. カナリアの展開

# AWS IAM ユーザーカナリアを作成
docker compose exec app coalmine canary create my-canary AWS_IAM_USER \
  --account <ACCOUNT_ID> --logging-id <LOGGING_ID>

# カナリア一覧
docker compose exec app coalmine canary list

6. 検出の確認

# テストアラートを発動
docker compose exec app coalmine canary trigger my-canary

# 監視サイクル（約1分）を待ってからアラートを確認
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)   │
          └─────────────────┘

CLIリファレンス

コマンドは coalmine <resource> <action> [options] のパターンに従います。

カナリアコマンド

コマンド	説明
canary create <name> <type>	新しいカナリアを作成
canary list	すべてのカナリアを一覧表示
canary delete <name_or_id>	カナリアを削除
canary creds <name>	カナリアの認証情報を取得
canary trigger <name_or_id>	カナリアの検出をテスト

認証情報コマンド

コマンド	説明
credentials list	すべての認証情報を一覧表示
credentials add <name> <provider>	認証情報を追加
credentials update <name_or_id>	認証情報を更新
credentials remove <name_or_id>	認証情報を削除
credentials validate <name_or_id>	認証情報の健全性を検証
credentials sync [--dry-run]	YAML設定から同期

アカウントコマンド

コマンド	説明
accounts list [--credential <name>]	すべてのアカウントを一覧表示
accounts add <name>	アカウントを追加
accounts update <name_or_id>	アカウントを更新
accounts enable <name_or_id>	アカウントを有効化
accounts disable <name_or_id>	アカウントを無効化
accounts remove <name_or_id>	アカウントを削除
accounts validate <name_or_id>	アカウントの健全性を検証

ロギングコマンド

コマンド	説明
logs create <name> <type>	ロギングリソースを作成
logs list	ロギングリソースを一覧表示
logs scan --account <id>	既存のCloudTrailをスキャン

アラートコマンド

コマンド	説明
alerts list [--canary <name>]	セキュリティアラートを表示

認証コマンド

コマンド	説明
auth key list	APIキーを一覧表示
auth key add <name>	APIキーを追加
auth session list	アクティブセッションを一覧表示

ユーザーコマンド

コマンド	説明
user list	すべてのユーザーを一覧表示
user roles	利用可能なロールを一覧表示

タスクコマンド

コマンド	説明
task list	最近の非同期タスクを表示
task status <task_id>	タスクの結果を確認

ヘルプ

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

REST API

APIは http://localhost:8000 で動作し、APIキーヘッダーまたはセッションクッキーによる認証が必要です。

設定 (config/api_keys.yaml)

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

リクエスト例

# カナリア一覧
curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/canaries

# カナリアを作成
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

APIドキュメント

対話型APIドキュメントは http://localhost:8000/docs (Swagger UI) で利用できます。

設定

すべての設定は config/ ディレクトリにあります。詳細は config/README.md を参照してください。

認証情報 (config/credentials.yaml)

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"

同期: docker compose exec app coalmine credentials sync

アラート出力 (config/alert_outputs.yaml)

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

リソースタイプ