ستكون واجهة API متاحة على `http://localhost:8000`.

لتنفيذ التحويل محليًا، يجب أن يكون Redis وعامل التحويل (transform worker) قيد التشغيل أيضًا. Redis وحده لا يكفي.

ابدأ Redis:```bash
docker run -d --name ogi-redis -p 6379:6379 redis:7-alpine

إذا رأيت `Job queue not available` أو `Redis not available`، تأكد من أن:

- يشير `OGI_REDIS_URL` إلى `redis://localhost:6379/0` للتشغيل المحلي على المضيف
- تم إعادة تشغيل الخلفية بعد أن أصبح Redis قيد التشغيل
- عملية العامل المنفصلة قيد التشغيل
- لا تستخدم اسم المضيف الخاص بـ Docker فقط `redis` خارج Docker Compose

إذا قمت بتشغيل الخلفية باستخدام PostgreSQL (`OGI_USE_SQLITE=false`)، فسيقوم بدء التشغيل بتطبيق ترحيلات Alembic تلقائيًا قبل خدمة الطلبات. تقوم عمليات نشر Docker بذلك أيضًا في نقطة دخول حاوية الخلفية.

يتم معالجة عمليات تشغيل AI Investigator بواسطة عامل منفصل آخر:```bash
cd backend
uv run python -m ogi.agent.run_worker

افتح http://localhost:5173. هذا كل شيء.

### AI Investigator

AI Investigator هو سير عمل اختياري مدعوم من مزود يمكنه تخطيط تسلسلات التحويل، وطلب الموافقات، وتلخيص تقدم التحقيق داخل مساحة العمل.

- افتح علامة التبويب `AI Investigator` داخل مشروع
- قم بتكوين مزود ونموذج في مربع حوار إعدادات المحقق
- قم بتخزين مفاتيح API الخاصة بالمزود في `API Keys`
- قم بتشغيل عملية `agent-worker` المنفصلة بجانب الخادم الخلفي

التنفيذ الحالي يدعم تكوين مزود لكل مستخدم وعامل مخصص ينفذ خطوات التحقيق بشكل مستقل عن خادم API الرئيسي.

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

طريقتان مدعومتان لتشغيل واجهة سطر الأوامر:

**موصى به** (لا يتطلب تنشيط):```bash
cd backend
uv sync
uv run ogi --help

## Docker

### التطوير```bash
cp .env.example .env
docker compose up

استخدم ملف compose للإنتاج فقط عندما يكون لديك بالفعل مثيل PostgreSQL يمكن الوصول إليه وقد قمت بتعيين `OGI_DATABASE_URL` وفقًا لذلك:```bash
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

لإزالة قيود محددة في نشر محلي أولاً:```env
OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=none,max_urls=none,max_links=none,max_content_chars=none

### فئات التحويل المدمجة

| الفئة    | الأمثلة                                      |
| -------- | -------------------------------------------- |
| DNS      | A, AAAA, MX, NS, CNAME records              |
| IP & ASN | GeoIP, reverse IP, ASN info                  |
| SSL/TLS  | Certificate transparency, SSL labs           |
| Email    | Mailserver validation, breach checks         |
| Web      | WHOIS, domain info, web extraction           |
| Social   | Username enumeration, social profiles        |
| Hash     | MD5, SHA1, SHA256 lookups                    |
| Location | Geocoding, weather, nearby ASN data          |

### أنواع الكيانات المدعومة

`Person` • `Username` • `Domain` • `IPAddress` • `EmailAddress` • `PhoneNumber` • `Organization` • `URL` • `SocialMedia` • `Hash` • `Document` • `Location` • `ASNumber` • `Network` • `MXRecord` • `NSRecord` • `Nameserver` • `SSLCertificate` • `Subdomain` • `HTTPHeader`

### بناء التحويلات الخاصة بك

هل تريد بناء تحويلاتك الخاصة؟ طالع [دليل المساهمة](https://github.com/opengraphintel/ogi-transforms/blob/main/CONTRIBUTING.md).

إذا كان تحويلك يحتاج إلى بيانات اعتماد من خدمة خارجية، فقم بتعريفها في `api_keys_required`. لا تخزّن الأسرار في إعدادات التحويل. يقوم OGI بإدارتها تحت `API Keys`، وتعتبر الإضافات التي تستخدم الأسرار كودًا مميزًا.

إذا كان تحويلك يعرض إعدادات محدودة مثل `max_results` أو `max_content_chars`، ففضل استخدام أسماء إعدادات مستقرة بدلاً من الأسماء المخصصة الفردية حيثما أمكن. يمكن لـ OGI تجاوز القيم القصوى مركزياً باستخدام `OGI_TRANSFORM_SETTING_MAX_OVERRIDES`، مما يساعد عمليات النشر السحابية على فرض القيود بينما يمكن للمستخدمين المحليين إزالتها.

كل إضافة هي مجلد يحتوي على ملف بيان `plugin.yaml`:```yaml
name: my-transform
version: "1.0.0"
display_name: My Transform
description: What it does
author: Your Name
license: MIT
category: dns
input_types: [Domain]
output_types: [IPAddress]
permissions:
  network: true
  filesystem: false
  subprocess: false

### الإعدادات

يستخدم OGI [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) مع دعم ملف `.env`. متغيرات وقت التشغيل/النهاية الخلفية مسبوقة بـ `OGI_`.

تقبل إعدادات القائمة إما:

- مصفوفات JSON، على سبيل المثال `["plugins","../plugins"]`
- سلاسل مفصولة بفواصل، على سبيل المثال `plugins,../plugins`

<details>
<summary><strong>متغيرات البيئة الرئيسية</strong></summary>

| المتغير                                        | الوصف                                                                                                      | الافتراضي                                             |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `OGI_APP_NAME`                                  | اسم التطبيق                                                                                                 | `OGI`                                               |
| `OGI_HOST`                                      | مضيف ربط النهاية الخلفية                                                                                                | `0.0.0.0`                                           |
| `OGI_PORT`                                      | منفذ النهاية الخلفية                                                                                                     | `8000`                                              |
| `OGI_CORS_ORIGINS`                              | أصول الواجهة الأمامية المسموح بها                                                                                         | `http://localhost:5173,http://localhost:3000`       |
| `OGI_USE_SQLITE`                                | استخدام SQLite بدلاً من PostgreSQL                                                                                 | `true`                                              |
| `OGI_DB_PATH`                                   | مسار ملف قاعدة بيانات SQLite                                                                                        | `ogi.db`                                            |
| `OGI_DATABASE_URL`                              | سلسلة اتصال PostgreSQL                                                                                     | `postgresql://postgres:postgres@localhost:5432/ogi` |
| `OGI_REDIS_URL`                                 | سلسلة اتصال Redis لوظائف RQ                                                                              | `redis://localhost:6379/0`                          |
| `OGI_RQ_QUEUE_NAME`                             | اسم قائمة الانتظار لوظائف التحويل                                                                                    | `transforms`                                        |
| `OGI_TRANSFORM_TIMEOUT`                         | مهلة وظيفة التحويل بالثواني                                                                             | `300`                                               |
| `OGI_AGENT_WORKER_POLL_INTERVAL_SEC`            | فترة الاستقصاء لعامل المحقق الذكي                                                                     | `2.0`                                               |
| `OGI_AGENT_CLAIM_TIMEOUT_SEC`                   | مهلة المطالبة القديمة لاستعادة خطوة المحقق الذكي                                                            | `120`                                               |
| `OGI_AUTO_RUN_MIGRATIONS`                       | تشغيل Alembic تلقائياً عند بدء تشغيل التطبيق المحلي غير SQLite                                                                 | `true`                                              |
| `OGI_RUN_DB_MIGRATIONS`                         | تشغيل ترحيلات قاعدة البيانات في نقطة دخول الحاوية                                                                        | `false`                                             |
| `OGI_DB_MIGRATION_RETRIES`                      | عدد محاولات إعادة ترحيل نقطة الدخول                                                                                | `30`                                                |
| `OGI_DB_MIGRATION_DELAY_SECONDS`                | التأخير بين محاولات إعادة ترحيل نقطة الدخول                                                                      | `2`                                                 |
| `OGI_PLUGIN_DIRS`                               | أدلة البحث عن الإضافات                                                                                        | `plugins,../plugins`                                |
| `OGI_DEPLOYMENT_MODE`                           | وضع النشر (`self-hosted` أو `cloud`)                                                                       | `self-hosted`                                       |
| `OGI_CLOUD_BILLING_ENABLED`                     | تمكين الفوترة للمؤيدين في السحابة فقط وفرض فترة التهدئة للتحويل                                           | `false`                                             |
| `OGI_FREE_TRANSFORM_COOLDOWN_SECONDS`           | فترة التهدئة بين تشغيل المحولات للمستخدمين المجانيين في السحابة                                                                | `1800`                                              |
| `OGI_PAID_TRANSFORM_COOLDOWN_SECONDS`           | فترة التهدئة بين تشغيل المحولات للمستخدمين المدفوعين في السحابة                                                                | `0`                                                 |
| `OGI_STRIPE_SECRET_KEY`                         | مفتاح Stripe السري من جانب الخادم لجلسات الدفع والبوابة                                                   | غير معين                                               |
| `OGI_STRIPE_WEBHOOK_SECRET`                     | سر توقيع webhook من Stripe                                                                                    | غير معين                                               |
| `OGI_STRIPE_SUPPORTER_PRICE_ID`                 | معرف السعر المتكرر من Stripe لخطة المؤيد                                                                 | غير معين                                               |
| `OGI_STRIPE_SUPPORTER_AMOUNT_CENTS`             | المبلغ المعروض لخطة المؤيد                                                                            | `300`                                               |
| `OGI_STRIPE_SUPPORTER_CURRENCY`                 | العملة المعروضة لخطة المؤيد                                                                          | `usd`                                               |
| `OGI_BILLING_SUCCESS_URL`                       | إعادة توجيه نجاح الدفع من Stripe اختيارياً                                                                        | مشتق من الطلب                                |
| `OGI_BILLING_CANCEL_URL`                        | إعادة توجيه إلغاء الدفع من Stripe اختيارياً                                                                         | مشتق من الطلب                                |
| `OGI_BILLING_PORTAL_RETURN_URL`                 | عنوان URL لإرجاع بوابة الفوترة من Stripe اختيارياً                                                                        | مشتق من الطلب                                |
| `OGI_REGISTRY_REPO`                             | مستودع GitHub لسجل المحولات                                                                                   | `opengraphintel/ogi-transforms`                     |
| `OGI_REGISTRY_CACHE_TTL`                        | وقت حياة ذاكرة التخزين المؤقت للسجل بالثواني                                                                                    | `3600`                                              |
| `OGI_TRANSFORM_SETTING_MAX_OVERRIDES`           | تجاوز أقصى عام اختياري لإعدادات المحول                                                          | فارغ                                               |
| `OGI_GITHUB_TOKEN`                              | رمز GitHub اختياري لحدود معدل السجل/API                                                               | غير معين                                               |
| `OGI_SUPABASE_URL`                              | عنوان URL لمشروع Supabase                                                                                             | غير معين                                               |
| `OGI_SUPABASE_ANON_KEY`                         | مفتاح Supabase العام/المجهول                                                                                         | غير معين                                               |
| `OGI_SUPABASE_SERVICE_ROLE_KEY`                 | مفتاح دور الخدمة في Supabase                                                                                        | غير معين                                               |
| `OGI_SUPABASE_JWT_SECRET`                       | سر JWT في Supabase                                                                                              | غير معين                                               |
| `OGI_SUPABASE_REDIRECT_URL`                     | عنوان URL لإعادة التوجيه المستخدم في تدفقات المصادقة للواجهة الأمامية                                                                         | غير معين                                               |
| `OGI_ADMIN_EMAILS`                              | مستخدمون إداريون لإدارة السجل والإضافات                                                                       | غير معين                                               |
| `OGI_TELEMETRY_ENABLED`                         | تمكين أو تعطيل القياس عن بعد على مستوى التثبيت                                                                   | `true`                                              |
| `OGI_TELEMETRY_LEVEL`                           | مستوى القياس عن بعد (`basic` أو `full`)                                                                              | `full`                                              |
| `OGI_API_KEY_ENCRYPTION_KEY`                    | مفتاح Fernet لتخزين مفتاح API المشفر                                                                         | غير معين ولكن يوصى بشدة                      |
| `OGI_API_KEY_INJECTION_ALLOW_COMMUNITY_PLUGINS` | السماح للإضافات المجتمعية بتلقي مفاتيح API المخزنة                                                               | `true`                                              |
| `OGI_API_KEY_INJECTION_TRUSTED_TIERS_ONLY`      | تقييد حقن المفتاح المخزن لفئات موثوقة فقط                                                              | `false`                                             |
| `OGI_API_KEY_INJECTION_ALLOWED_TIERS`           | الفئات المسموح بها عند تمكين الوضع الموثوق فقط                                                                  | `official,verified`                                 |
| `OGI_API_KEY_SERVICE_ALLOWLIST`                 | قائمة الخدمات المسموح بها اختيارياً لحقن المفتاح المخزن                                                               | فارغ                                               |
| `OGI_API_KEY_SERVICE_BLOCKLIST`                 | قائمة الخدمات المحظورة اختيارياً لحقن المفتاح المخزن                                                               | فارغ                                               |
| `OGI_LLM_PROVIDER`                              | موفر المحقق الذكي الافتراضي الاحتياطي                                                                        | `openai`                                            |
| `OGI_LLM_MODEL`                                 | نموذج المحقق الذكي الافتراضي الاحتياطي                                                                           | `gpt-4.1-mini`                                      |
| `OGI_EXPOSE_ERROR_DETAILS`                      | تضمين التفاصيل الداخلية في استجابات 500                                                                        | `false`                                             |
| `OGI_SANDBOX_ENABLED`                           | تمكين وضع التنفيذ في وضع الحماية                                                                                    | `false`                                             |
| `OGI_SANDBOX_TIMEOUT`                           | مهلة وضع الحماية بالثواني                                                                                       | `30`                                                |
| `OGI_SANDBOX_MEMORY_MB`                         | حد الذاكرة لوضع الحماية بالميغابايت                                                                                       | `256`                                               |
| `OGI_SANDBOX_ALLOWED_TIERS`                     | الفئات المسموح بها في وضع الحماية السحابي                                                                              | `official,verified`                                 |
| `OGI_BOOT_REQUIREMENTS_ENABLE`                  | تمكين تثبيت تبعيات الإضافات عند بدء التشغيل                                                                       | `true`                                              |
| `OGI_BOOT_REQUIREMENTS_FILE`                    | مسار ملف متطلبات بدء التشغيل                                                                                      | `/app/plugins/requirements.txt`                     |
| `OGI_BOOT_LOCK_FILE`                            | مسار ملف قفل بدء التشغيل                                                                                              | `/app/plugins/ogi-lock.json`                        |
| `OGI_BOOT_REQUIREMENTS_STRICT`                  | فشل بدء التشغيل إذا كانت متطلبات الإضافات مفقودة                                                                  | `false`                                             |
| `OGI_BOOT_REQUIREMENTS_CACHE_DIR`               | دليل مؤقت/ذاكرة تخزين مؤقت لتوليد متطلبات بدء التشغيل                                                             | `/tmp/ogi-boot`                                     |
| `OGI_FRONTEND_PORT`                             | تعيين منفذ الواجهة الأمامية في Docker المحلي                                                                               | `3000`                                              |
| `OGI_IMAGE_TAG`                                 | علامة صورة الإنتاج لنشر compose/Coolify                                                                                | `latest`                                            |
| `OGI_BACKEND_IMAGE`                             | تجاوز صورة النهاية الخلفية اختيارياً                                                                                  | `ghcr.io/khashashin/ogi-backend`                    |
| `OGI_WORKER_IMAGE`                              | تجاوز صورة العامل اختيارياً. القيمة الافتراضية هي صورة النهاية الخلفية لأن العامل والنهاية الخلفية يشتركان في بناء الصورة نفسه. | `ghcr.io/khashashin/ogi-backend`                    |
| `OGI_FRONTEND_IMAGE`                            | تجاوز صورة الواجهة الأمامية اختيارياً                                                                                 | `ghcr.io/khashashin/ogi-frontend`                   |
| `OGI_CLI_BEARER_TOKEN`                          | رمز حامل CLI اختياري للنهايات الخلفية الممكّنة للمصادقة                                                              | غير معين                                               |

انظر [`.env.example`](https://github.com/khashashin/ogi/blob/HEAD/.env.example) للحصول على القائمة الكاملة.

</details>

## التطوير

### تشغيل الاختبارات```bash
# Backend
cd backend
OGI_DB_PATH=":memory:" OGI_USE_SQLITE=true uv run pytest

# Frontend
cd frontend
pnpm test

### خط أنابيب CI

يتم تشغيل [سير عمل CI](https://github.com/khashashin/ogi/blob/HEAD/.github/workflows/ci.yml) عند كل طلب سحب:

- **الخلفية:** ruff lint, mypy type check, pytest
- **الواجهة الأمامية:** vitest, eslint, vite build

## المساهمة

نرحب بطلبات السحب! إذا وجدت خطأ أو لديك فكرة، [افتح مشكلة](https://github.com/khashashin/ogi/issues).

للتحويلات الجديدة، ساهم في [ogi-transforms](https://github.com/opengraphintel/ogi-transforms).

### البدء

1. انسخ المستودع
2. أنشئ فرع ميزة (`git checkout -b feature/my-feature`)
3. قم بإجراء التغييرات
4. قم بتشغيل الاختبارات والفحص
5. قدم طلب سحب

## الاستخدام القانوني والمسؤول

OGI هي أداة استخبارات مفتوحة المصدر (OSINT) وتحليل رسوم بيانية للأغراض العامة. **أنت المسؤول الوحيد عن كيفية استخدامها.** راجع [LEGAL.md](https://github.com/khashashin/ogi/blob/HEAD/LEGAL.md) للإشعار القانوني الكامل.

- **الامتثال لشروط الخدمة الخاصة بالأطراف الثالثة.** يجب استخدام التحويلات التي تستعلم عن الخدمات الخارجية (DNS، WHOIS، تجريف الويب، البحث عن أسماء المستخدمين، إلخ) وفقًا لشروط الخدمة لتلك الخدمات. قد يؤدي الاستعلام الآلي أو الجماعي للمواقع التي تحظره إلى انتهاك شروطها.
- **احترم قانون حماية البيانات.** إذا كنت في الاتحاد الأوروبي أو تعالج بيانات عن مقيمين في الاتحاد الأوروبي، فإن اللائحة العامة لحماية البيانات (GDPR) تنطبق عليك كمراقب بيانات. يتطلب جمع أو تخزين أو معالجة البيانات الشخصية (الأسماء، عناوين البريد الإلكتروني، عناوين IP، إلخ) أساسًا قانونيًا. OGI نفسها لا تخزن بيانات تتجاوز مثيلك المحلي — أنت مسؤول عن ما تجمعه وتحتفظ به.
- **الاستخدام للأغراض القانونية فقط.** OGI مخصصة لأبحاث الأمن المشروعة، التحقيقات، استخبارات التهديدات، والاستخدام التعليمي. لا تستخدمها لمضايقة الأفراد، أو الوصول غير المصرح به، أو انتهاك القانون الساري.
- **توافق تنسيق الملف.** تدعم OGI استيراد تنسيق تبادل الرسوم البيانية MTGX. هذا متوفر فقط لتشغيل البيانات فيما بينها ولا يعني أي انتساب أو تأييد من صانعي الأدوات التي تستخدم هذا التنسيق.

> **إخلاء مسؤولية:** يتم توفير OGI "كما هي" دون أي ضمان من أي نوع. المؤلفون غير مسؤولين عن أي إساءة استخدام أو أضرار ناشئة عن استخدام هذا البرنامج.

## الترخيص

هذا المشروع مرخص بموجب [رخصة جنو أفيرو العمومية العامة v3.0](https://github.com/khashashin/ogi/blob/HEAD/LICENSE).

---

<div align="center">

**[الإبلاغ عن خطأ](https://github.com/khashashin/ogi/issues) &bull; [طلب ميزة](https://github.com/khashashin/ogi/issues) &bull; [المناقشات](https://github.com/opengraphintel/ogi-transforms/discussions)**

صُنع بـ 💜 من مجتمع OGI

</div>