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

### التشغيل عبر Docker

شغّل Krawl في الوضع المستقل باستخدام أحدث صورة:```bash
docker run -d \
  -p 5000:5000 \
  -e KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard" \
  -e KRAWL_DASHBOARD_PASSWORD="my-secret-password" \
  -v krawl-data:/app/data \
  --name krawl \
  ghcr.io/blessedrebus/krawl:latest

**قابل للتوسع**: مع PostgreSQL و Redis:

> [!CAUTION]
> المثال أدناه يستخدم **كلمات مرور افتراضية** (`krawl`/`krawl`). **قم بتغييرها قبل النشر في بيئة الإنتاج.**```yaml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: krawl
      POSTGRES_USER: krawl
      POSTGRES_PASSWORD: krawl
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U krawl -d krawl"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  krawl:
    image: ghcr.io/blessedrebus/krawl:latest
    container_name: krawl-server
    ports:
      - "5000:5000"
    environment:
      - CONFIG_LOCATION=config.yaml
      - KRAWL_MODE=scalable
      - KRAWL_POSTGRES_HOST=postgres
      - KRAWL_POSTGRES_PORT=5432
      - KRAWL_POSTGRES_USER=krawl
      - KRAWL_POSTGRES_PASSWORD=krawl
      - KRAWL_POSTGRES_DATABASE=krawl
      - KRAWL_REDIS_HOST=redis
      - KRAWL_REDIS_PORT=6379
      # - KRAWL_DASHBOARD_PASSWORD=my-secret-password
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

volumes:
  postgres_data:
  redis_data:

ملفات compose الجاهزة للإنتاج متوفرة أيضًا في دليل [`docker/`](https://github.com/blessedrebus/krawl/blob/main/docker). للتطوير **development** (البناء من المصدر مع إعادة التحميل التلقائي)، استخدم ملفات compose الموجودة في [`docker/dev/`](https://github.com/blessedrebus/krawl/blob/main/docker/dev).

لمزيد من التفاصيل حول كلا الوضعين، راجع [أوضاع النشر](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md).

### Kubernetes
**يتوفر Krawl أيضًا بشكل أصلي على Kubernetes**. يمكن إجراء التثبيت إما [عبر manifest](https://github.com/blessedrebus/krawl/blob/main/kubernetes/README.md) أو [باستخدام مخطط Helm](https://github.com/blessedrebus/krawl/blob/main/helm/README.md).

**يتميز مخطط Helm افتراضيًا بوضع قابل للتوسع** مع PostgreSQL وRedis مدمجين:```bash
helm install krawl oci://ghcr.io/blessedrebus/krawl-chart --version 2.3.1 \
  -n krawl-system --create-namespace \
  --set postgres.password=your-password \
  --set redis.password=your-redis-password \
  --set dashboardPassword=your-dashboard-password \
  --set config.dashboard.secret_path=/my-secret-dashboard

قم بالوصول إلى الخادم على `http://localhost:5000`


## الإعدادات
يستخدم Krawl **تسلسلاً هرمياً للإعدادات** حيث **تتجاوز متغيرات البيئة ملف الإعدادات**. يُنصح بهذا الأسلوب لنشر Docker والتخصيص السريع الجاهز للاستخدام.

### الإعداد عبر config.yaml
يمكنك استخدام ملف [config.yaml](https://github.com/blessedrebus/krawl/blob/main/config.yaml) للإعدادات المتقدمة، مثل نشر Docker Compose أو مخططات Helm.

### الإعداد عبر متغيرات البيئة

يمكن توفير جميع الإعدادات كمتغيرات بيئة، والتي تتجاوز `config.yaml`.
اسم المتغير هو `KRAWL_` بالإضافة إلى مسار الإعداد بالأحرف الكبيرة، لذا فإن `dashboard.password`
يصبح `KRAWL_DASHBOARD_PASSWORD`.

<details>
<summary><b>الخادم وتوليد الروابط</b> (12 متغيراً)</summary>

كيف يقدم Krawl نفسه ويشكل متاهة الصفحات المُولَّدة.

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `CONFIG_LOCATION` | مسار ملف إعدادات yaml | `config.yaml` |
| `KRAWL_PORT` | منفذ استماع الخادم | `5000` |
| `KRAWL_DELAY` | تأخير الاستجابة بالمللي ثانية | `100` |
| `KRAWL_SERVER_HEADER` | ترويسة خادم HTTP للخداع | `""` |
| `KRAWL_LINKS_LENGTH_RANGE` | نطاق طول الروابط بصيغة `min,max` | `5,15` |
| `KRAWL_LINKS_PER_PAGE_RANGE` | الروابط لكل صفحة بصيغة `min,max` | `10,15` |
| `KRAWL_CHAR_SPACE` | الأحرف المستخدمة لتوليد الروابط | `abcdefgh...` |
| `KRAWL_MAX_COUNTER` | قيمة العداد الأولية | `10` |
| `KRAWL_PROBABILITY_ERROR_CODES` | احتمالية استجابات الخطأ (0-100%) | `0` |
| `KRAWL_INFINITE_PAGES_FOR_MALICIOUS` | تقديم صفحات لا نهائية لعناوين IP الخبيثة | `true` |
| `KRAWL_MAX_PAGES_LIMIT` | الحد الأقصى لعدد الصفحات للزاحفين | `250` |
| `KRAWL_BAN_DURATION_SECONDS` | مدة الحظر بالثواني لعناوين IP المقيَّدة المعدل | `600` |

</details>

<details>
<summary><b>لوحة التحكم والمقاييس والتسجيل</b> (8 متغيرات)</summary>

الوصول إلى لوحة التحكم، التسخين المسبق للذاكرة المؤقتة، Prometheus ومستوى السجل.

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_DASHBOARD_SECRET_PATH` | مسار لوحة تحكم مخصص | مُولَّد تلقائياً |
| `KRAWL_DASHBOARD_PASSWORD` | كلمة مرور للوحات التحكم المحمية | مُولَّدة تلقائياً |
| `KRAWL_DASHBOARD_CACHE_WARMUP` | حساب مسبق لبيانات لوحة التحكم كل 5 دقائق لتحميل فوري للصفحات | `true` |
| `KRAWL_DASHBOARD_WARMUP_PAGES` | عدد الصفحات للتسخين المسبق لكل لوحة جدول | `10` |
| `KRAWL_DASHBOARD_WARMUP_AGGREGATION` | حساب مسبق كامل لتجميعات top_paths/top_ua لخدمة بدون استعلامات | `false` |
| `KRAWL_DASHBOARD_TOP_N_MIN_COUNT` | الحد الأدنى لعدد الوصول للوحات المسارات/وكلاء المستخدم الأعلى (اضبطه على 1 لتعطيله) | `5` |
| `KRAWL_METRICS_ENABLED` | كشف مقاييس Prometheus على `/<dashboard_path>/metrics` | `true` |
| `KRAWL_LOG_LEVEL` | مستوى سجل التطبيق (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |

</details>

<details>
<summary><b>قاعدة البيانات والاحتفاظ والنسخ الاحتياطي</b> (6 متغيرات)</summary>

موقع التخزين، مدة الاحتفاظ بالبيانات، ومهمة التفريغ.

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_DATABASE_PATH` | موقع ملف قاعدة البيانات | `data/krawl.db` |
| `KRAWL_DATABASE_PERSIST_SUSPICIOUS_ONLY` | الاحتفاظ بالطلبات المشبوهة فقط في سجل الوصول | `false` |
| `KRAWL_DATABASE_RETENTION_DAYS` | أيام الاحتفاظ بالبيانات في قاعدة البيانات | `30` |
| `KRAWL_BACKUPS_PATH` | المسار الذي تُحفظ فيه نسخ قاعدة البيانات | `backups` |
| `KRAWL_BACKUPS_CRON` | تعبير cron للتحكم بجدول مهمة النسخ الاحتياطي | `*/30 * * * *` |
| `KRAWL_BACKUPS_ENABLED` | قيمة منطقية لتفعيل مهمة تفريغ قاعدة البيانات | `true` |

</details>

<details>
<summary><b>الفخاخ: tarpit وصفحات الخداع وcanary</b> (6 متغيرات)</summary>

فخاخ اختيارية والصفحات المقدمة للمهاجمين.

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_TARPIT_ENABLED` | محاصرة وكلاء الذكاء الاصطناعي باستجابات بطيئة ونص عشوائي | `false` |
| `KRAWL_TARPIT_DELAY_SECONDS` | تأخير إضافي بالثواني يُضاف لكل استجابة عند تفعيل tarpit | `5` |
| `KRAWL_DECEPTION_IMPORT_PAGES` | استيراد تلقائي لصفحات الخداع من `src/templates/deception/` عند بدء التشغيل | `true` |
| `KRAWL_CUSTOM_TEMPLATE_PATH` | مسار داخل الحاوية لقالب HTML مخصص. يجب أن يتضمن القالب العناصر النائبة `{counter}` و`{content}`. | `/templates/custom_page.html` |
| `KRAWL_CANARY_TOKEN_URL` | عنوان URL خارجي لرمز canary | لا شيء |
| `KRAWL_CANARY_TOKEN_TRIES` | الطلبات قبل عرض رمز canary | `10` |

</details>

<details>
<summary><b>محلل سمعة عنوان IP</b> (6 متغيرات)</summary>

عتبات تحدد كيفية تصنيف عنوان IP.

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_HTTP_RISKY_METHODS_THRESHOLD` | عتبة اكتشاف طرق HTTP الخطرة | `0.1` |
| `KRAWL_VIOLATED_ROBOTS_THRESHOLD` | عتبة انتهاكات robots.txt | `0.1` |
| `KRAWL_UNEVEN_REQUEST_TIMING_THRESHOLD` | عتبة معامل الاختلاف للتوقيت | `0.5` |
| `KRAWL_UNEVEN_REQUEST_TIMING_TIME_WINDOW_SECONDS` | النافذة الزمنية لتحليل توقيت الطلبات بالثواني | `300` |
| `KRAWL_USER_AGENTS_USED_THRESHOLD` | عتبة اكتشاف وكلاء مستخدم متعددين | `2` |
| `KRAWL_ATTACK_URLS_THRESHOLD` | عتبة اكتشاف عناوين URL الهجومية | `1` |

</details>

<details>
<summary><b>قائمة الحظر وعناوين IP المتجاهلة</b> (4 متغيرات)</summary>

مشاركة قوائم الحظر مع مثيلات أخرى، والحركة التي لا يتم تتبعها أبداً.

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_IGNORED_IPS` | عناوين IP/CIDRs مفصولة بفواصل لا يتم تتبعها أو حظرها أو تصديرها أبداً | Loopback, RFC1918, link-local, CGNAT |
| `KRAWL_BANLIST_EXPORT_PATH` | مسار تنزيل عام لقائمة الحظر، مثل `/public_banlist.txt` (فارغ = معطل) | `""` |
| `KRAWL_BANLIST_SOURCES` | عناوين URL لقوائم حظر علوية مفصولة بفواصل لجلبها ودمجها | قائمة حظر مجتمع Krawl |
| `KRAWL_BANLIST_REFRESH_INTERVAL` | الثواني بين عمليات جلب قوائم الحظر العلوية | `3600` |

</details>

<details>
<summary><b>صفحات الخداع المُولَّدة بالذكاء الاصطناعي</b> (10 متغيرات)</summary>

راجع [توثيق توليد الذكاء الاصطناعي](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md).

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_AI_ENABLED` | تفعيل صفحات الخداع المُولَّدة بالذكاء الاصطناعي | `false` |
| `KRAWL_AI_PROVIDER` | مزود الذكاء الاصطناعي (`"openrouter"` أو `"openai"`) | `"openrouter"` |
| `KRAWL_AI_OPENAI_BASE_URL` | عنوان URL أساسي اختياري لـ OpenAI لنقاط نهاية API مخصصة | `"https://api.openai.com/v1"` |
| `KRAWL_AI_API_KEY` | مفتاح API لمزود الذكاء الاصطناعي | `None` |
| `KRAWL_AI_MODEL` | نموذج الذكاء الاصطناعي المستخدم لتوليد الصفحات | `"nvidia/nemotron-3-super-120b-a12b:free"` |
| `KRAWL_AI_TIMEOUT` | مهلة الطلب بالثواني لاستدعاءات API الخاصة بالذكاء الاصطناعي | `60` |
| `KRAWL_AI_MAX_DAILY_REQUESTS` | الحد الأقصى لعدد الصفحات المُولَّدة بالذكاء الاصطناعي يومياً (0 = غير محدود) | `0` |
| `KRAWL_AI_PROMPT` | قالب مطالبة مخصص لتوليد صفحات الذكاء الاصطناعي | المطالبة الافتراضية |
| `KRAWL_AI_REASONING_ENABLED` | تفعيل رموز الاستدلال (نماذج OpenRouter للاستدلال فقط) | `false` |
| `KRAWL_AI_REASONING_EFFORT` | جهد الاستدلال (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) | `"medium"` |

</details>

<details>
<summary><b>الوضع القابل للتوسع: PostgreSQL وRedis</b> (13 متغيراً)</summary>

يُستخدم فقط عند `KRAWL_MODE=scalable`. راجع [أوضاع النشر](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md).

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_MODE` | وضع النشر (`standalone` أو `scalable`) | `standalone` |
| `KRAWL_POSTGRES_HOST` | اسم مضيف PostgreSQL | `localhost` |
| `KRAWL_POSTGRES_PORT` | منفذ PostgreSQL | `5432` |
| `KRAWL_POSTGRES_USER` | اسم مستخدم PostgreSQL | `krawl` |
| `KRAWL_POSTGRES_PASSWORD` | كلمة مرور PostgreSQL | `krawl` |
| `KRAWL_POSTGRES_DATABASE` | اسم قاعدة بيانات PostgreSQL | `krawl` |
| `KRAWL_REDIS_HOST` | اسم مضيف Redis | `localhost` |
| `KRAWL_REDIS_PORT` | منفذ Redis | `6379` |
| `KRAWL_REDIS_DB` | رقم قاعدة بيانات Redis | `0` |
| `KRAWL_REDIS_PASSWORD` | كلمة مرور Redis | لا شيء |
| `KRAWL_REDIS_CACHE_TTL` | TTL بالثواني لبيانات تسخين لوحة التحكم | `600` |
| `KRAWL_REDIS_HOT_TTL` | TTL بالثواني لبيانات المسار السريع (معلومات الحظر، فئات IP) | `30` |
| `KRAWL_REDIS_TABLE_TTL` | TTL بالثواني لجداول لوحة التحكم المقسمة إلى صفحات | `120` |

</details>


على سبيل المثال```bash
# Set canary token
export CONFIG_LOCATION="config.yaml"
export KRAWL_CANARY_TOKEN_URL="http://your-canary-token-url"

# Set number of pages range (min,max format)
export KRAWL_LINKS_PER_PAGE_RANGE="5,25"

# Set analyzer thresholds
export KRAWL_HTTP_RISKY_METHODS_THRESHOLD="0.2"
export KRAWL_VIOLATED_ROBOTS_THRESHOLD="0.15"

# Set custom dashboard path and password
export KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard"
export KRAWL_DASHBOARD_PASSWORD="my-secret-password"

## استخدام Krawl لحظر عناوين IP الضارة
يستخدم Krawl نظامًا قائمًا على السمعة لتصنيف عناوين IP الخاصة بالمهاجمين، ويوفر طريقتين لتصدير قوائم IP للتكامل مع جدار الحماية.

تستعلم نقطة النهاية `/api/export-ips` من قاعدة البيانات مباشرةً وتدعم التصفية حسب فئة IP (`attacker`, `bad_crawler`, `regular_user`, `good_crawler`) وصيغة الإخراج (`raw`, `iptables`, `nftables`):```bash
curl "https://your-krawl-instance/<DASHBOARD-PATH>/api/export-ips?categories=attacker&fwtype=raw"

للحصول على التكوين والاستخدام المفصل، راجع [وثائق توليد الذكاء الاصطناعي](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md).

يمكنك أيضًا **المساهمة بقوالب الخداع** عن طريق فتح طلب سحب (PR)، راجع [المساهمة بقوالب الخداع](https://github.com/blessedrebus/krawl/blob/main/docs/deception_pages.md#contributing-deception-templates-via-pr).

## التشغيل خلف وكيل عكسي أو شبكة توصيل المحتوى (CDN)

**NGINX وTraefik والوكلاء الآخرون مثل CloudFlare** يحتاجون إلى توجيه الرؤوس (header forwarding) حتى يتمكن Krawl من رؤية عنوان IP الحقيقي. راجع [وثائق الوكيل العكسي](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md) للحصول على أمثلة التكوين وقائمة الرؤوس الكاملة.

## المقاييس والمراقبة

يكشف Krawl عن مقاييس [Prometheus](https://prometheus.io/) على `/<dashboard_secret_path>/metrics` (مفعّلة افتراضيًا) ويأتي مع لوحة تحكم [Grafana](https://grafana.com/) جاهزة للاستيراد في [`grafana-dashboard.json`](https://github.com/blessedrebus/krawl/blob/main/grafana-dashboard.json).

راجع [وثائق المراقبة](https://github.com/blessedrebus/krawl/blob/main/docs/monitoring.md) للحصول على قائمة المقاييس الكاملة، وخطوات استيراد Grafana، وإعداد الجمع عبر Prometheus / Kubernetes (`ServiceMonitor`).

## وثائق إضافية

| الموضوع | الوصف |
|---------|-------|
| [توليد الذكاء الاصطناعي](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md) | تكوين صفحات خداع مولّدة بالذكاء الاصطناعي باستخدام OpenRouter أو OpenAI |
| [صفحات الخداع](https://github.com/blessedrebus/krawl/blob/main/docs/deception_pages.md) | إدارة صفحات الخداع واستيرادها وتصديرها؛ العمليات الجماعية والتصفية المستندة إلى التاريخ |
| [أنماط النشر](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md) | الوضع المستقل (SQLite) مقابل الوضع القابل للتوسع (PostgreSQL + Redis)، والتكوين، وترحيل البيانات |
| [خادم الطُعم (Honeypot)](https://github.com/blessedrebus/krawl/blob/main/docs/honeypot.md) | نظرة عامة كاملة على صفحات خادم الطُعم: عمليات تسجيل دخول مزيفة، وقوائم الدلائل، وملفات بيانات الاعتماد، وفخاخ SQLi/XSS/XXE/حقن الأوامر، والمزيد |
| [لوحة التحكم](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard.md) | الوصول إلى لوحة تحكم المراقبة في الوقت الفعلي واستكشافها |
| [واجهة برمجة تطبيقات لوحة التحكم](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard-api.md) | واجهة JSON API الخاصة بـ Krawl: مرجع نقاط النهاية، والمصادقة، ووثائق OpenAPI التفاعلية، وتنزيلات المرفقات |
| [واجهات برمجة التطبيقات الخارجية](https://github.com/blessedrebus/krawl/blob/main/docs/api.md) | واجهات برمجة التطبيقات التابعة لجهات خارجية التي يستدعيها Krawl للحصول على بيانات IP والسمعة والموقع الجغرافي |
| [الوكيل العكسي](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md) | كيفية نشر Krawl خلف NGINX أو استخدام نطاقات فرعية خادعة |
| [النسخ الاحتياطي لقاعدة البيانات](https://github.com/blessedrebus/krawl/blob/main/docs/backups.md) | تفعيل وتكوين مهمة تفريغ قاعدة البيانات التلقائية |
| [رمز الكناري (Canary Token)](https://github.com/blessedrebus/krawl/blob/main/docs/canary-token.md) | إعداد مشغلات تنبيه خارجية عبر canarytokens.org |
| [قائمة الكلمات](https://github.com/blessedrebus/krawl/blob/main/docs/wordlist.md) | تخصيص أسماء المستخدمين وكلمات المرور وقوائم الدلائل المزيفة |
| [البنية المعمارية](https://github.com/blessedrebus/krawl/blob/main/docs/architecture.md) | نظرة عامة تقنية على قاعدة الكود وخط أنابيب الطلبات ومخطط قاعدة البيانات والمهام الخلفية |
| [مزامنة قائمة حظر Cloudflare](https://github.com/blessedrebus/krawl/blob/main/docs/cloudflare_banlist.md) | دفع عناوين IP المحظورة من Krawl إلى قائمة عناوين IP لحساب Cloudflare لاستخدامها في قواعد WAF. تعمل المزامنة كمهمة خلفية وتحدّث القائمة بالاستبدال الكامل. |
| [مصدّرات جدار الحماية](https://github.com/blessedrebus/krawl/blob/main/docs/firewall-exporters.md) | تصدير قوائم حظر IP بتنسيقات raw أو iptables أو nftables عبر REST API |
| [فخ الإبطاء (Tarpit)](https://github.com/blessedrebus/krawl/blob/main/docs/tarpit.md) | إبطاء وتسميم زاحفي الذكاء الاصطناعي باستجابات متأخرة ومحشوة بالضوضاء |
| [المقاييس والمراقبة](https://github.com/blessedrebus/krawl/blob/main/docs/monitoring.md) | نقطة نهاية مقاييس Prometheus، ومرجع المقاييس المكشوفة، ولوحة تحكم Grafana، وجمع ServiceMonitor |

## المساهمة

المساهمات مرحّب بها! يرجى:
1. عمل fork للمستودع
2. إنشاء فرع ميزة
3. إجراء التغييرات
4. تقديم طلب سحب (اشرح التغييرات!)

## إخلاء مسؤولية
> [!CAUTION]
> هذا نظام خداع/خادم طُعم. انشره في بيئات معزولة وراقبه بعناية بحثًا عن الأحداث الأمنية. استخدمه بمسؤولية ووفقًا للقوانين واللوائح المعمول بها.

## سجل النجوم
<img src="https://star-history.dera.page/svg?repos=BlessedRebuS/Krawl&amp;type=Date" width="600" alt="مخطط سجل النجوم" />