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

### تشغيل 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/HEAD/docker/). للتطوير **التطوير** (البناء من المصدر مع إعادة التحميل التلقائي)، استخدم ملفات compose الموجودة في [`docker/dev/`](https://github.com/blessedrebus/krawl/blob/HEAD/docker/dev/).

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

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

مخطط Helm **يفترض الوضع القابل للتوسع افتراضيًا** مع PostgreSQL وRedis مدمجين:```bash
helm install krawl oci://ghcr.io/blessedrebus/krawl-chart --version 2.3.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

يمكنك الوصول إلى الخادم على `http://localhost:5000`


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

### الإعدادات عبر config.yaml
يمكنك استخدام ملف [config.yaml](https://github.com/blessedrebus/krawl/blob/HEAD/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 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> (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>

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

| متغير البيئة | الوصف | الافتراضي |
|----------------------|-------------|---------|
| `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` | رابط رمز canary خارجي | None |
| `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` | عتبة اكتشاف روابط الهجوم | `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 upstream لقوائم الحظر مفصولة بفواصل ليتم جلبها ودمجها | قائمة حظر مجتمع Krawl |
| `KRAWL_BANLIST_REFRESH_INTERVAL` | الثواني بين عمليات جلب قوائم الحظر من upstream | `3600` |

</details>

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

انظر [توثيق توليد الذكاء الاصطناعي](https://github.com/blessedrebus/krawl/blob/HEAD/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` | مهلة الطلب بالثواني لاستدعاءات واجهة برمجة تطبيقات الذكاء الاصطناعي | `60` |
| `KRAWL_AI_MAX_DAILY_REQUESTS` | الحد الأقصى لعدد الصفحات المولّدة بالذكاء الاصطناعي يومياً (0 = غير محدود) | `0` |
| `KRAWL_AI_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/HEAD/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 | None |
| `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/HEAD/docs/ai_generation.md).

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

## التشغيل خلف وكيل عكسي أو CDN

تحتاج **NGINX وTraefik والوكلاء الآخرون مثل CloudFlare** إلى تمرير الترويسات (headers) حتى يتمكن Krawl من رؤية عنوان IP الحقيقي. راجع [توثيق الوكيل العكسي](https://github.com/blessedrebus/krawl/blob/HEAD/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/HEAD/grafana-dashboard.json).

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

## توثيق إضافي

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

## المساهمة

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

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

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