coalmine

![Coalmine — إدارة رمز الكناري](https://assets.kitploit.com/production/public/readmes/11524/a9c5a7010fd084526f416db096e9ca8e20c5d647274fd88a2a64219f4b3ff967.png)

> **إدارة رمز الكناري السحابي** — نشر ومراقبة وتدوير بيانات الاعتماد الخادعة عبر AWS وGCP لكشف الوصول غير المصرح به.

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

> [!WARNING]
> **إصدار ألفا** — Coalmine في مرحلة تطوير مبكرة. الوظائف الأساسية هي الأولوية الحالية، ويجب **عدم اعتبار التطبيق مُختبرًا أمنيًا بالكامل** للاستخدام الإنتاجي.

## الحالة

| وظيفي | قيد التطوير (غير مستقر) | قيد التنفيذ |
|-------|-------------------------|-------------|
| كناري مستخدم IAM من AWS | كناري حساب خدمة GCP | دعم أزور |
| كناري حاوية S3 من AWS | كناري حاوية GCP | تكامل SIEM |
| مراقبة CloudTrail | مراقبة سجل التدقيق GCP | |
| خلفية حالة PostgreSQL | التدوير التلقائي | |
| واجهة REST (مفتاح API + مصادقة جلسة) | | |
| لوحة معلومات WebUI | | |
| تنبيهات البريد الإلكتروني وWebhook | | |
| إدارة بيانات الاعتماد والحسابات | | |
| التحكم في الوصول القائم على الأدوار (Casbin) | | |

## نظرة عامة

يقوم Coalmine تلقائيًا بنشر ومراقبة "رموز الكناري" — بيانات اعتماد وموارد خادعة تؤدي إلى إطلاق تنبيهات عند الوصول إليها من قبل المهاجمين.

**الموفرو المدعومون:**
- **AWS**: مستخدمو IAM، حاويات S3
- **GCP**: حسابات الخدمة، حاويات Cloud Storage

## الميزات

- **دعم السحب المتعددة** — AWS وGCP من واجهة واحدة
- **نموذج بيانات الاعتماد والحسابات** — إدارة بيانات اعتماد وحسابات السحابة عبر CLI أو API أو مزامنة YAML
- **التدوير التلقائي** — تدوير بيانات الاعتماد على فترات زمنية قابلة للتكوين
- **المراقبة المركزية** — تكامل CloudTrail وسجل تدقيق GCP
- **التنبيه المرن** — إشعارات عبر البريد الإلكتروني وWebhook وSyslog
- **البنية الأساسية كرمز** — موارد مُدارة بواسطة OpenTofu
- **واجهة REST** — وصول برمجي بمصادقة مفتاح API أو جلسة
- **واجهة ويب** — لوحة معلومات قائمة على المتصفح في `/ui`
- **التحكم في الوصول القائم على الأدوار** — عبر Casbin
- **واجهة CLI** — هيكل أوامر فرعية مجمعة (`coalmine <مورد> <إجراء>`)

## البدء السريع

### المتطلبات الأساسية

- Docker وDocker Compose
- بيانات اعتماد AWS (لكناري AWS)
- بيانات اعتماد GCP (لكناري GCP)

### 1. استنساخ المستودع والتكوين

```bash
git clone https://github.com/yourorg/coalmine.git
cd coalmine
cp .env.example .env
# قم بتحرير .env باستخدام بيانات اعتماد قاعدة البيانات والسحابة
```

### 2. تشغيل الخدمات

```bash
docker compose up -d
```

يؤدي هذا إلى تشغيل API، عامل Celery، Redis، وPostgreSQL. تتوفر واجهة الويب على `http://localhost:8000/ui`.

### 3. تسجيل بيانات الاعتماد والحسابات

```bash
# إضافة بيانات اعتماد 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. إنشاء مورد تسجيل

```bash
# إنشاء وجهة تسجيل CloudTrail
docker compose exec app coalmine logs create my-trail AWS_CLOUDTRAIL \
  --account <ACCOUNT_ID>

# سرد موارد التسجيل
docker compose exec app coalmine logs list
```

### 5. نشر كناري

```bash
# إنشاء كناري مستخدم IAM على AWS
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. التحقق من الكشف

```bash
# تشغيل تنبيه اختبار
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)   │
          └─────────────────┘
```

## مرجع واجهة سطر الأوامر

تتبع الأوامر النمط: `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>` | مسح CloudTrails الحالية |

### أوامر التنبيهات

| الأمر | الوصف |
|-------|-------|
| `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>` | التحقق من نتيجة المهمة |

### المساعدة

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

## واجهة REST

تعمل واجهة API على `http://localhost:8000` وتتطلب المصادقة عبر رأس مفتاح API أو ملف تعريف الجلسة.

### التكوين (`config/api_keys.yaml`)

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

### أمثلة الطلبات

```bash
# سرد الكناري
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).

## التكوين

جميع التهيئة موجودة في دليل `config/`. راجع [config/README.md](https://github.com/johnearle/coalmine/blob/main/config/README.md) للتفاصيل.

### بيانات الاعتماد (`config/credentials.yaml`)

```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`)

```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 |

## التطوير

```bash
# تشغيل جميع الاختبارات
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

# عرض سجلات العامل
docker compose logs -f worker

# إعادة البناء بعد تغييرات الكود
docker compose build && docker compose up -d
```

## اعتبارات أمنية

- **لا تقم أبدًا بإيداع بيانات الاعتماد** — استخدم ملفات `.env` أو مديري الأسرار
- **قم بتدوير بيانات اعتماد المشرف** — بيانات اعتماد السحابة المستخدمة لإدارة الكناري
- **عزل الشبكة** — قم بتشغيل Coalmine في جزء شبكة آمن
- **مبدأ الحد الأدنى من الصلاحيات** — يجب أن تكون صلاحيات بيانات اعتماد الكناري في أدنى حد
- **أمان مفتاح API** — قم بتخزين مفاتيح API بشكل آمن وقم بتدويرها بانتظام

## الرخصة

[رخصة Apache 2.0](https://github.com/johnearle/coalmine/blob/main/LICENSE) — راجع ملف LICENSE للتفاصيل.

## المساهمة

راجع [CONTRIBUTING.md](https://github.com/johnearle/coalmine/blob/main/CONTRIBUTING.md) لإرشادات المساهمة.