Krawl

<h1 align="center">Krawl</h1>

<h3 align="center">
  <a name="readme-top"></a>
  <img
    src="https://raw.githubusercontent.com/blessedrebus/krawl/HEAD/img/krawl-svg.svg"
    height="250"
  >
</h3>
<div align="center">

<p align="center">
  خادم مصائد ويب حديث وقابل للتخصيص، مصمم لاكتشاف وتتبع النشاط الخبيث الصادر عن المهاجمين وعناكب الويب من خلال صفحات ويب خادعة وبيانات اعتماد مزيفة ورموز الكناري.
</p>

<div align="center">
  <a href="https://github.com/blessedrebus/krawl/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/blessedrebus/krawl" alt="License">
  </a>
  <a href="https://github.com/blessedrebus/krawl/releases">
    <img src="https://img.shields.io/github/v/release/blessedrebus/krawl" alt="Release">
  </a>
</div>

<div align="center">
  <a href="https://ghcr.io/blessedrebus/krawl">
    <img src="https://img.shields.io/badge/ghcr.io-krawl-blue" alt="GitHub Container Registry">
  </a>
  <a href="https://kubernetes.io/">
    <img src="https://img.shields.io/badge/kubernetes-ready-326CE5?logo=kubernetes&amp;logoColor=white" alt="Kubernetes">
  </a>
  <a href="https://github.com/BlessedRebuS/Krawl/pkgs/container/krawl-chart">
    <img src="https://img.shields.io/badge/helm-chart-0F1689?logo=helm&amp;logoColor=white" alt="Helm Chart">
  </a>
</div>
</div>

## جدول المحتويات
- [العرض التوضيحي](#demo)
- [ما هو Krawl؟](#what-is-krawl)
- [لوحة تحكم Krawl](#krawl-dashboard)
- [أوضاع النشر](#deployment-modes)
- [قائمة حظر Krawl](#krawl-banlist)
- [البدء السريع](#quickstart)
  - [Docker Run](#docker-run)
  - [Docker Compose](#docker-compose)
  - [Kubernetes](#kubernetes)
  - [Uvicorn (Python)](#uvicorn-python)
- [الإعدادات](#configuration)
  - [config.yaml](#configuration-via-configyaml)
  - [متغيرات البيئة](#configuration-via-environmental-variables)
- [حظر عناوين IP الخبيثة](#use-krawl-to-ban-malicious-ips)
- [سمعة عنوان IP](#ip-reputation)
- [التشغيل خلف وكيل عكسي أو شبكة CDN](#running-behind-a-reverse-proxy-or-cdn)
- [المقاييس والمراقبة](#metrics--monitoring)
- [وثائق إضافية](#additional-documentation)
- [الخداع باستخدام الذكاء الاصطناعي](#ai-generated-deception-pages)
- [المساهمة](#contributing)

## العرض التوضيحي
نصيحة: قم بزحف مسارات `robots.txt` لمزيد من المتعة
### رابط Krawl: [http://demo.krawlme.com](http://demo.krawlme.com)
### عرض لوحة التحكم [http://demo.krawlme.com/das_dashboard](http://demo.krawlme.com/das_dashboard)

## ما هو Krawl؟

**Krawl** هو خادم خداع سحابي أصلي مصمم لاكتشاف المهاجمين الخبيثين وعناكب الويب والماسحات الضوئية الآلية وإبطائها وتحليلها.

يقوم بإنشاء تطبيقات ويب مزيفة واقعية مليئة بالثغرات السهلة مثل لوحات الإدارة وملفات الإعدادات وبيانات الاعتماد المزيفة المكشوفة لجذب النشاط المشبوه وتحديده.

![dashboard](https://assets.kitploit.com/production/public/readmes/12879/a01b9a420bd9f26c6837b29c55c0c4f7c415cf155d5b640ecf614cfed4097997.png)

من خلال إهدار موارد المهاجم، يساعد Krawl في التمييز بوضوح بين السلوك الخبيث وعناكب الويب الشرعية.

يتميز بـ:

- **[صفحات خداع مُولّدة بالذكاء الاصطناعي](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md)**: **دع المهاجمين يساعدون في توليد سطح هجوم مزيف قابل للاستغلال**
- **صفحات فخ العنكبوت**: روابط عشوائية لا نهائية لإهدار موارد الزاحف بناءً على [مشروع spidertrap](https://github.com/adhdproject/spidertrap)
- **صفحات تسجيل دخول مزيفة**: WordPress، phpMyAdmin، لوحات الإدارة
- **مسارات المصيدة**: يتم الإعلان عنها في robots.txt لالتقاط الماسحات الضوئية
- **بيانات اعتماد مزيفة**: أسماء مستخدمين وكلمات مرور ومفاتيح API تبدو واقعية
- **[دمج رمز الكناري](https://github.com/blessedrebus/krawl/blob/main/docs/canary-token.md)**: تفعيل التنبيهات الخارجية
- **ترويسات خادم عشوائية**: إرباك الهجمات بناءً على ترويسة الخادم وإصداره
- **لوحة تحكم في الوقت الفعلي**: مراقبة النشاط المشبوه
- **قوائم كلمات قابلة للتخصيص**: إعدادات سهلة قائمة على JSON
- **حقن أخطاء عشوائي**: محاكاة سلوك الخادم الحقيقي

يمكنك بسهولة كشف Krawl إلى جانب خدماتك الأخرى لحمايتها من عناكب الويب والمستخدمين الخبيثين باستخدام وكيل عكسي. لمزيد من التفاصيل، راجع [وثائق الوكيل العكسي](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md).

![use case](https://assets.kitploit.com/production/public/readmes/12879/60f7ddddd201d89a440fbd2b0b3ac08a1d19b9b9a87dc956a02a06c608f1a73d.png)

## لوحة تحكم Krawl

يوفر Krawl لوحة تحكم شاملة، يمكن الوصول إليها عبر **مسار سري عشوائي** يتم إنشاؤه عند بدء التشغيل أو عبر **مسار مخصص** يتم تكوينه عبر `KRAWL_DASHBOARD_SECRET_PATH`. هذا يُبقي لوحة التحكم مخفية عن المهاجمين الذين يفحصون مصيدتك.

تنقسم لوحة التحكم إلى ستة تبويبات:

- **نظرة عامة**: عرض عالي المستوى لنشاط الهجوم: خريطة تفاعلية لأصول عناوين IP، والطلبات المشبوهة الأخيرة، وأهم عناوين IP ووكلاء المستخدم والمسارات.

![geoip](https://assets.kitploit.com/production/public/readmes/12879/391bf8fda76ed917c8731427a914f2279d9e0cc8bc69034797c355944972f085.png)

- **الهجمات**: تفصيل دقيق لبيانات الاعتماد الملتقطة ومحفزات المصيدة وأنواع الهجمات المكتشفة (SQLi، XSS، اجتياز المسار، إلخ) مع رسوم بيانية وجداول.

![attack_types](https://assets.kitploit.com/production/public/readmes/12879/30a42393851ed51015609282643749e98372b0ac6eee207eb779f8ea070c7f63.png)

- **التهديدات**: الحمولات مجمعة في حملات حسب تجزئة TLSH الضبابية، بحيث يُقرأ webshell ونسخه المعدلة كحملة واحدة بدلاً من إصابات غير مترابطة، مع فهرس لكل ملف تم التقاطه.

- **رؤية IP**: عرض جنائي متعمق لعنوان IP محدد: الموقع الجغرافي، معلومات ISP/ASN، علامات السمعة، الجدول الزمني السلوكي، توزيع أنواع الهجمات، سجل المُحيل، الملفات وبيانات الاعتماد الملتقطة، وسجل الوصول الكامل.

![ipinsight](https://assets.kitploit.com/production/public/readmes/12879/93a6ddb8e4b69769fadbba30869373248d0f14c2c7c14d008f0143f3e24c5728.png)

بالإضافة إلى ذلك، بعد المصادقة بكلمة مرور لوحة التحكم، تصبح التبويبات المحمية متاحة:

- **عناوين IP المتتبعة**: الاحتفاظ بقائمة مراقبة لعناوين IP التي تريد مراقبتها بمرور الوقت.
- **قائمة حظر IP**: إدارة حظر عناوين IP، وعرض المهاجمين المكتشفين، وتصدير قائمة الحظر بصيغة خام أو IPTables.
- **عناوين IP المنتهية مهلتها**: مراجعة عناوين IP المحتجزة حالياً في المصيدة، وإعفاء أي منها لا ينبغي احتجازه.
- **الخداع**: إدارة الصفحات المُولّدة بالذكاء الاصطناعي، وتصديرها أو استيراد صفحات جديدة.
- **Webhooks**: تمرير عمليات الحظر إلى CloudFlare وجدران الحماية الأخرى.

تفتح أيقونات الترويسة وثائق API، وتصدير قائمة الحظر، ولوحة إعدادات تعرض التكوين الجاري وصفحة صيانة لتشغيل المهام المجدولة عند الطلب.

لمزيد من التفاصيل، راجع [وثائق لوحة التحكم](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard.md).

## أوضاع النشر

يدعم Krawl وضعي نشر، يتم التحكم فيهما عبر إعداد `mode` في `config.yaml` أو متغير البيئة `KRAWL_MODE`.

| | مستقل | قابل للتوسع |
|---|---|---|
| **قاعدة البيانات** | SQLite (وضع WAL) | PostgreSQL |
| **التخزين المؤقت** | قاموس Python في الذاكرة | Redis (TTL متعدد المستويات) |
| **النسخ المتماثلة** | 1 (مثيل واحد) | 1+ (توسع أفقي) |
| **الاعتماديات الخارجية** | لا شيء | PostgreSQL + Redis |
| **الأفضل لـ** | التطوير، المختبرات المنزلية، أقل من 500 ألف طلب | الإنتاج، التوافر العالي، أكثر من 500 ألف طلب |

**مستقل**: مثالي لبيئات التطوير أو المختبرات المنزلية ذات أعداد الطلبات المنخفضة. لا حاجة لتكوين إضافي، فقط شغّل Krawl وسيعمل.
- نشر بحاوية واحدة بدون اعتماديات خارجية
- استخدام أقل للذاكرة والموارد

**قابل للتوسع**: مصمم لبيئات الإنتاج أو المصائد ذات الحركة العالية. مخطط Helm يستخدم هذا الوضع افتراضياً.
- لوحة تحكم أسرع وأكثر استجابة بفضل التخزين المؤقت متعدد المستويات في Redis
- إدخال/إخراج قرص أقل مع عمل Redis كذاكرة تخزين مؤقت للمسار الساخن أمام PostgreSQL
- التوسع الأفقي يزيد عدد نسخ Krawl خلف موازن التحميل

للحصول على التكوين التفصيلي، وأمثلة Docker Compose، وإعداد Kubernetes/Helm، وتعليمات الترحيل خطوة بخطوة، راجع [وثائق أوضاع النشر](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md).

## قائمة حظر Krawl

يحتفظ Krawl بـ [`banlist.txt`](https://github.com/blessedrebus/krawl/blob/main/banlist.txt) محدّثة بانتظام لعناوين IP من **المهاجمين الذين فعّلوا مصائد honeypot الخاصة به**. تُنشر قائمة الحظر أسبوعياً ومتاحة للتنزيل، مما يساعد المجتمع على حظر الجهات الخبيثة المعروفة استباقياً حتى بدون استخدام Krawl.

يمكن أيضاً جلب قائمة الحظر مباشرة من:
[https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw](https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw).

### مشاركة قوائم الحظر بين المثيلات

يمكن لمثيلات Krawl أن تتحالف في قوائم الحظر الخاصة بها: يمكن لكل منها نشر قائمتها الخاصة على
مسار غير مُصادق عليه وسحب القوائم من مثيلات أخرى (أو أي قائمة عناوين IP نصية عادية).
يتم دمج عناوين IP المجلوبة في قرارات الحظر المحلية وتُعرض في لوحة التحكم.```yaml
banlist:
  # Public, unauthenticated download path for this instance's banlist.
  # Supports the same ?categories= and ?fwtype= parameters as the main API.
  # Empty = disabled.
  export_path: "/public_banlist.txt"

  # Upstream banlists to fetch and merge. Plain ".txt" lists work too.
  sources:
    - "https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw"
    - "https://krawl.example.com/public_banlist.txt"

  refresh_interval: 3600  # seconds between fetches
```
## البدء السريع

### تشغيل 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
```
يمكن الوصول إلى الخادم على `http://localhost:5000`

### Docker Compose

أنشئ ملف `docker-compose.yaml` باستخدام أحد وضعي النشر.

**Standalone**: فقط خادم Krawl مع تخزين Sqlite:```yaml
services:
  krawl:
    image: ghcr.io/blessedrebus/krawl:latest
    container_name: krawl-server
    ports:
      - "5000:5000"
    environment:
      - CONFIG_LOCATION=config.yaml
      # - KRAWL_DASHBOARD_PASSWORD=my-secret-password
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - krawl-data:/app/data
    restart: unless-stopped

volumes:
  krawl-data:
```
**قابل للتوسع**: مع 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:
```
لنشر، فقط قم بتشغيل```bash
docker compose up -d
```
ملفات compose الجاهزة للإنتاج متاحة أيضًا في دليل [`docker/`](https://github.com/blessedrebus/krawl/blob/main/docker). لـ**التطوير** (البناء من المصدر مع إعادة التحميل الفوري)، استخدم ملفات 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.4.0 \
  -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
```
تتوفر ملفات قيم نموذجية بسيطة لكلا الوضعين:
- [`values-minimal.yaml`](https://github.com/blessedrebus/krawl/blob/main/helm/values-minimal.yaml) ---> قابل للتوسع (افتراضي)
- [`values-standalone.yaml`](https://github.com/blessedrebus/krawl/blob/main/helm/values-standalone.yaml) ---> مستقل

راجع [أوضاع النشر](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md) و[توثيق المخطط](https://github.com/blessedrebus/krawl/blob/main/helm/README.md) للحصول على التكوين الكامل وتعليمات الترحيل.

### Uvicorn (Python)

شغّل Krawl مباشرةً باستخدام Python 3.13+ و uvicorn للتطوير المحلي أو الاختبار:```bash
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 5000 --app-dir src --no-server-header
```
يمكن الوصول إلى الخادم على `http://localhost:5000`


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

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

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

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

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

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

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `CONFIG_LOCATION` | مسار ملف إعدادات yaml | `config.yaml` |
| `KRAWL_PORT` | منفذ استماع الخادم | `5000` |
| `KRAWL_DELAY` | تأخير الاستجابة بالمللي ثانية | `100` |
| `KRAWL_SERVER_HEADER` | ترويسة HTTP Server للتمويه | `""` |
| `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> (13 متغيراً)</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_DASHBOARD_BRAND_NAME` | الاسم في علامة لوحة التحكم والعنوان | `Krawl` |
| `KRAWL_DASHBOARD_BRAND_URL` | وجهة رابط العلامة (فارغ يعرضها كنص عادي) | مستودع Krawl |
| `KRAWL_DASHBOARD_BRAND_LOGO` | رابط الصورة المعروضة بدلاً من علامة GitHub | غير محدد |
| `KRAWL_DASHBOARD_BRAND_SHOW_VERSION` | إظهار الإصدار بجانب الاسم | `true` |
| `KRAWL_DASHBOARD_BRAND_CONTACT` | جهة الاتصال المعروضة تحت العلامة (عنوان، رابط، أو نص عادي) | غير محدد |
| `KRAWL_METRICS_ENABLED` | كشف مقاييس Prometheus على `/<dashboard_path>/metrics` | `true` |
| `KRAWL_LOG_LEVEL` | مستوى سجل التطبيق (`DEBUG`، `INFO`، `WARNING`، `ERROR`) | `INFO` |

</details>

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

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

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_DATABASE_PATH` | موقع ملف قاعدة البيانات | `data/krawl.db` |
| `KRAWL_DATABASE_PERSIST_SUSPICIOUS_ONLY` | حفظ الطلبات المشبوهة فقط في سجل الوصول | `false` |
| `KRAWL_MAP_TILE_URL` | قالب رابط البلاطة لخريطة لوحة التحكم (`{z}/{x}/{y}`، اختياري `{s}`/`{r}`) | Esri dark canvas |
| `KRAWL_MAP_TILE_ATTRIBUTION` | الإسناد المعروض على الخريطة | Esri/OSM |
| `KRAWL_MAP_API_KEY` | يُضاف إلى كل طلب بلاطة كمعامل استعلام — مطلوب من CARTO | _(فارغ)_ |
| `KRAWL_MAP_API_KEY_PARAM` | اسم معامل الاستعلام هذا (`api_key`، `apikey`، `key`) | `api_key` |
| `KRAWL_IPV6_IGNORE` | إسقاط طلبات IPv6 بالكامل: تُسجَّل في stdout، ولا تُحفظ أبداً، ولا تُفحص للحظر أو تُصدَّر | `false` |
| `KRAWL_IPV6_PURGE_EXISTING` | حذف صفوف IPv6 الموجودة أيضاً عند بدء التشغيل التالي (لا رجعة فيه؛ يتطلب `KRAWL_IPV6_IGNORE`) | `false` |
| `KRAWL_DATABASE_RETENTION_DAYS` | عدد الأيام للاحتفاظ بالبيانات في قاعدة البيانات | `30` |
| `KRAWL_BACKUPS_PATH` | المسار الذي تُحفظ فيه تفريغات قاعدة البيانات | `backups` |
| `KRAWL_BACKUPS_CRON` | تعبير cron للتحكم في جدولة مهمة النسخ الاحتياطي | `*/30 * * * *` |
| `KRAWL_BACKUPS_ENABLED` | قيمة منطقية لتمكين مهمة تفريغ قاعدة البيانات | `true` |

</details>

<details>
<summary><b>الفِخاخ: tarpit وصفحات الخداع والكناري</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` | رابط رمز الكناري الخارجي | لا شيء |
| `KRAWL_CANARY_TOKEN_TRIES` | عدد الطلبات قبل إظهار رمز الكناري | `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` | عتبة كشف روابط الهجوم | `1` |

</details>

<details>
<summary><b>التقاط استخبارات التهديدات</b> (4 متغيرات)</summary>

تجزئة ضبابية للحمولات الملتقطة (الملفات وأجسام الطلبات المُعلَّمة) وتجميع
المتغيرات شبه المكررة في مجموعات حملات. يتطلب `py-tlsh`.

تعمل التجزئة كمهمة خلفية مجدولة `hash-payloads` (انظر
`src/tasks/hash_payloads.py`)، والتي تجزّئ كل هجوم ملتقط مرة واحدة — الإصابات
الجديدة وقت الاستيعاب، ومسح خلفي لمرة واحدة للسجل الموجود
يتتبعه علامة مائية عالية `payload_hash_watermark` — ثم تجمّع
البصمات في حملات ذات أنماط متكررة.

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_TLSH_ENABLED` | تجزئة الملفات المرفوعة وأجسام الطلبات المُعلَّمة بـ TLSH للتجميع شبه المكرر | `true` |
| `KRAWL_TLSH_CLUSTER_THRESHOLD` | مسافة TLSH التي تحتلها تنضم الحمولة دونها إلى حملة موجودة (0 = بايتات متطابقة؛ عادةً ما يكون فرق متغيرات webshell < 100) | `150` |
| `KRAWL_TLSH_CAMPAIGN_MIN_EVENTS` | عدد المرات التي يجب أن تُرى فيها الحمولة قبل ظهور حملتها في تبويب Threats | `10` |
| `KRAWL_REFERER_ENABLED` | تسجيل HTTP Referer الوارد في سجلات الوصول، لتتبع سلسلة الطُعم | `true` |

</details>

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

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

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `KRAWL_IGNORED_IPS` | عناوين IP/CIDR مفصولة بفواصل لا تُتتبع أو تُحظر أو تُصدَّر أبداً | Loopback، RFC1918، link-local، CGNAT |
| `KRAWL_BANLIST_EXPORT_PATH` | مسار تنزيل قائمة الحظر العامة، مثل `/public_banlist.txt` (فارغ = معطّل) | `""` |
| `KRAWL_BANLIST_SOURCES` | روابط قوائم الحظر المصدرية مفصولة بفواصل لجلبها ودمجها | قائمة حظر مجتمع 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` | عنوان OpenAI Base URL اختياري لنقاط نهاية 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` | مهلة الطلب بالثواني لاستدعاءات AI API | `60` |
| `KRAWL_AI_MAX_DAILY_REQUESTS` | الحد الأقصى لعدد الصفحات المولّدة بالذكاء الاصطناعي يومياً (0 = غير محدود) | `0` |
| `KRAWL_AI_PROMPT` | قالب prompt مخصص لتوليد صفحات الذكاء الاصطناعي | 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` | مدة البقاء بالثواني لبيانات تسخين لوحة التحكم | `600` |
| `KRAWL_REDIS_HOT_TTL` | مدة البقاء بالثواني لبيانات المسار الساخن (معلومات الحظر، فئات IP) | `30` |
| `KRAWL_REDIS_TABLE_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"
```
مثال على تشغيل Docker مع متغيرات البيئة (وضع مستقل):```bash
docker run -d \
  -p 5000:5000 \
  -e KRAWL_MODE=standalone \
  -e KRAWL_PORT=5000 \

---

[Read more](https://github.com/blessedrebus/krawl)