coalmine

云蜜令令牌管理 — 在 AWS 和 GCP 上部署、监控并轮换欺骗性凭证，以检测未授权访问。

[!WARNING] Alpha 版本 — 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 通知
• 基础设施即代码 — 通过 OpenTofu 管理的资源
• REST API — 使用 API 密钥或会话认证进行编程访问
• WebUI — 基于浏览器的仪表盘，地址为 /ui
• RBAC — 基于 Casbin 的角色访问控制
• CLI — 分组的子命令结构 (coalmine <资源> <动作>)

快速开始

前提条件

• 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 Worker、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 <资源> <动作> [选项]

蜜令命令

命令	描述
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 命令

命令	描述
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 密钥头或会话 Cookie 进行认证。

配置 (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"

资源类型

类型	提供商	描述
AWS_IAM_USER	AWS	带有访问密钥的 IAM 用户
AWS_BUCKET	AWS	启用了日志记录的 S3 存储桶
GCP_SERVICE_ACCOUNT	GCP	带有密钥的服务账号
GCP_BUCKET	GCP	Cloud Storage 存储桶

开发

# 运行所有测试
docker compose run --rm app pytest -v

# 仅运行单元测试
docker compose run --rm app pytest tests/unit/ -v

# 运行集成测试
docker compose run --rm app pytest tests/integration/ -v

# 查看 worker 日志
docker compose logs -f worker

# 代码更改后重新构建
docker compose build && docker compose up -d

安全注意事项

• 切勿提交凭证 — 使用 .env 文件或密钥管理器
• 轮换管理员凭证 — 用于管理蜜令的云凭证
• 网络隔离 — 在安全的网络段中运行 Coalmine
• 最小权限原则 — 蜜令凭证应拥有最小权限
• API 密钥安全 — 安全存储 API 密钥，定期轮换

许可证