AIVP [AI Vulnerabilities Playground]

AIVP هو منصة مختبرات أمنية عملية للذكاء الاصطناعي تغطي 4 مراحل وأكثر من 50 مختبرًا (حاليًا أكثر من 50 سيناريو عبر قاعدة الأكواد). تجمع المنصة بين Ollama + Llama 3.1، وواجهة خلفية FastAPI، وواجهة أمامية React/Vite لتمكين الممارسين من ممارسة تقنيات أمن الذكاء الاصطناعي الهجومية والدفاعية بأمان.

إذا كان هذا المشروع مفيدًا لك، يرجى ⭐ وضع نجمة / إعجاب بالمستودع، fork له، ولا تتردد في فتح طلبات سحب (PRs)!

جدول المحتويات

• نظرة عامة
• خطوات التشغيل
• المتطلبات الأساسية
• هيكل المشروع
• متطلبات الأجهزة
• الإعداد والتثبيت
  • بداية سريعة (Windows PowerShell)
  • بداية سريعة (macOS/Linux bash)
  • الخطوات اليدوية
• تشغيل المختبرات
• الإعدادات
• لقطات الشاشة
• استكشاف الأخطاء وإصلاحها
• المساهمة
• المشكلات والملاحظات
• الترخيص

خطوات التشغيل

استخدم دليل التشغيل المخصص: RUN_STEPS.md. يغطي الدليل الطرق اليدوية (Vite + uvicorn) وDocker (nginx + API + Redis، مع Ollama على المضيف)، بما في ذلك المتطلبات الأساسية للوصول الموثوق إلى المختبرات.

سلوك الإعدادات صارم في مسارات التشغيل النشطة: قد يؤدي عدم وجود قيم بيئية مطلوبة إلى فشل بدء التشغيل حسب التصميم.

نظرة عامة

تغطي المنصة أربعة مسارات تدريبية:

• المرحلة 1 (PI): حقن الأوامر (prompt injection) وأنماط إساءة استخدام التعليمات
• المرحلة 2 (DE): الأنظمة الوكيلة (agentic systems)، تسرب الأدوات/الذاكرة/RAG، واستخراج البيانات من أنظمة متعددة
• المرحلة 3 (MM): أسطح الهجوم المتعلقة بالتلاعب بالنموذج (model-manipulation) والنموذج فقط
• المرحلة 4 (MCP): حدود الثقة في MCP وسيناريوهات المخاطر المتوافقة مع OWASP MCP

يستخدم كل مختبر أسرارًا متغيرة (per-lab secrets) وعمليات تحقق صريحة، حتى تتمكن من التحقق من نجاح الاستغلال في بيئة آمنة.

للاستخدام التعليمي فقط — تحاكي المختبرات سيناريوهات أمن الذكاء الاصطناعي الهجومية والدفاعية على الأنظمة المحلية. لا تستهدف خدمات أو بيانات أو بنية تحتية حقيقية لا تملكها أو ليس لديك إذن صريح باختبارها. الأسرار في هذه المختبرات اصطناعية ويتم إعادة توليدها لكل مختبر؛ وهي ليست بيانات اعتماد إنتاجية. استخدم على مسؤوليتك الخاصة. لا يتم تقديم أي ضمان.

• النموذج: Llama 3.1 عبر Ollama (محلي)
• الواجهة الخلفية: FastAPI (بث SSE) — POST /api/labs/{lab}/chat
• الواجهة الأمامية: React + Vite (واجهة Tailwind)
• الأسرار: يتم توليدها لكل مختبر في وقت التشغيل؛ يتم إعادة تعيينها عند إعادة تشغيل API (أو عبر نقطة نهاية إعادة التعيين)
• الميزات الفريدة: محاكاة أنظمة فرعية حقيقية (وكلاء/أدوات/ذاكرة/RAG)، تتبع جلسات التشغيل، وضع إعدادات صارم، وسير عمل يدوي + Docker

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

• Python 3.10+ (3.12 يعمل)
• Node.js 18+ (Node 20 LTS موصى به)
• Ollama مثبت ويعمل محليًا
• Git (اختياري لكن موصى به)

قم بسحب نموذج واحد على الأقل: ollama pull llama3.1 (أو أي متغير متوافق مع llama3.1 تفضله)

هيكل المشروع

apps/
  api/                # FastAPI backend (SSE -> Ollama)
    main.py
    requirements.txt
    .env.example
  web/                # React + Vite frontend
    src/
    .env.example

متطلبات الأجهزة

• الحد الأدنى (CPU فقط): 4 أنوية، 16 جيجابايت RAM، 10 جيجابايت مساحة خالية، بدون GPU → يعمل، لكن التوليد أبطأ
• الموصى به: 8 أنوية، 32 جيجابايت RAM، SSD 20+ جيجابايت مساحة خالية، NVIDIA 8–12 جيجابايت VRAM (أو Apple Silicon) → تجربة سريعة

CPU

• معالج 64 بت مع AVX2 (Intel/AMD حديث) أو Apple Silicon (M1/M2/M3).
• 4 أنوية كحد أدنى؛ 8 أنوية فأكثر موصى بها للدردشة المتوازية مع أدوات التطوير.

RAM (Llama 3 8B عبر Ollama، مضغوط)

• Q4_K_M (~4–5 جيجابايت للنموذج): يحتاج ~6–8 جيجابايت في وقت التشغيل.
• Q5/Q6 (~6–8 جيجابايت): ~10–12 جيجابايت في وقت التشغيل.
• Q8 (~9–10 جيجابايت): ~14–16 جيجابايت في وقت التشغيل.

نصيحة: 16 جيجابايت RAM للنظام تعمل؛ 32 جيجابايت تعطي مساحة مريحة للمتصفح و Node و Python و IDE.

GPU (اختياري)

• Windows/Linux (CUDA): NVIDIA RTX مع ≥8 جيجابايت VRAM (مثل 3060 12 جيجابايت ممتاز).
• macOS (Metal): أي Apple Silicon.
• العمل على CPU فقط جيد؛ الردود ستكون أبطأ فقط.

القرص

• النماذج: 5–10 جيجابايت حسب الضغط.
• المستودع + node_modules + venv: 1–2 جيجابايت.
• خطط لـ 15–20 جيجابايت مساحة خالية.

نظام التشغيل

• Windows 10/11، macOS 12+، Ubuntu 20.04+ (أو ما يماثلها). WSL2 يعمل أيضًا (تحتاج GPU إلى إعداد إضافي).

أدوات التطوير

• Python 3.10+، Node 18+ (20 LTS مثالي)، Ollama مثبت ويعمل.

نصائح الأداء

• ابدأ بـ llama3 (8B) Q4؛ قم بزيادة الضغط فقط إذا كان لديك RAM/VRAM إضافي.
• حافظ على طول المطالبات والسياق معقولاً (2–4k رمز) لتجنب ارتفاع استهلاك الذاكرة.
• أغلق التطبيقات الثقيلة إذا كنت تستخدم 16 جيجابايت RAM.

الإعداد والتثبيت

بداية سريعة (Windows PowerShell)

من جذر المستودع (المجلد الذي يحتوي على apps\api و apps\web):

# 0) تأكد من توفر النموذج
ollama pull llama3.1

# 1) البيئة الافتراضية للواجهة الخلفية + التبعيات + التشغيل
cd apps/api
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
uvicorn main:app --reload --port 8000

افتح نافذة PowerShell جديدة للواجهة الأمامية:

cd apps/web
npm install
copy .env.example .env
npm run dev   # http://localhost:5173

بداية سريعة (macOS/Linux bash)

# 0) النموذج
ollama pull llama3.1

# 1) الواجهة الخلفية
cd apps/api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn main:app --reload --port 8000

في نافذة طرفية أخرى:

cd apps/web
npm install
cp .env.example .env
npm run dev   # http://localhost:5173

الخطوات اليدوية

1. شغل Ollama واجعله يعمل (ollama serve إذا لزم الأمر).
2. اسحب Llama 3.1: ollama pull llama3.1.
3. شغل الواجهة الخلفية (FastAPI) على المنفذ :8000.
4. شغل الواجهة الأمامية (Vite) على المنفذ :5173.

تقوم الواجهة الأمامية ببث أحداث الخادم (SSE) من الواجهة الخلفية؛ تأكد من أن أصول CORS في apps/api/.env تتضمن http://localhost:5173.

تشغيل المختبرات

• افتح الواجهة الأمامية على http://localhost:5173.
• انتقل إلى Explore Labs ← اختر مختبرًا ← Launch Lab.
• استخدم الدردشة لمهاجمة المساعد (تطبق قواعد محددة لكل مختبر).
• بمجرد حصولك على السر (secret)، الصقه في Submit Your Answer.

صيغ معرفات المختبرات المقبولة (بواسطة الواجهة الخلفية): PI-01، PI_01، pi01، p01 → كلها يتم تحويلها إلى PI_01.

أسرار ديناميكية يتم إنشاؤها عند أول استخدام للمختبر بعد إعادة تشغيل الواجهة الخلفية. يمكنك أيضًا إعادة تعيين السر:

POST /api/secrets/reset/{labId}

سر كل مختبر مختلف ويتم إعادة إنشائه عند إعادة تشغيل الواجهة الخلفية (في الذاكرة). ضع في اعتبارك النسخ الاحتياطي إلى ملف/قاعدة بيانات إذا كنت بحاجة إلى الاستمرارية.

الإعدادات

الواجهة الخلفية (apps/api/.env)

OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1
CORS_ORIGINS=http://localhost:5173
SERVER_SALT=change-me-in-production
AIVP_DEFAULT_MODE=off
ENABLE_TRAINING_LABS=false
OLLAMA_MODEL_TRAINING_LABS=llama3.1
REDIS_URL=redis://localhost:6379/0
REDIS_HOST=localhost
REDIS_PORT=6379
MEMORY_TTL_SECONDS=3600
SESSION_TTL_SECONDS=3600
AGENT_B_URL=http://localhost:8001
MM_API_BASE=http://localhost:8000
API_BASE_URL=http://localhost:8000
JIRA_URL=https://example.atlassian.net
GITHUB_API_BASE_URL=https://api.github.com
SLACK_API_BASE_URL=https://slack.com/api

الواجهة الأمامية (apps/web/.env)

# للتطوير المحلي: عنوان URL كامل للـ API (Vite يقوم بوكالة /api في vite.config أيضًا)
VITE_API_BASE=http://localhost:8000/api
VITE_DEV_API_TARGET=http://localhost:8000
[email protected]

إصدارات Docker / الإنتاج تستخدم VITE_API_BASE=/api بحيث يستخدم المتصفح مسارات من نفس الأصل خلف nginx (انظر RUN_STEPS.md → الخيار B).

نقاط النهاية

• POST /api/labs/{lab}/chat — دفق SSE مع data: {"content": "..."}
• POST /api/secrets/validate — { labId, answer } → { success, message }
• POST /api/secrets/reset/{lab} — (اختياري، للاختبار)

لقطات الشاشة

أضف لقطات الشاشة الخاصة بك داخل docs/screenshots/ ثم أشر إليها هنا:

![الصفحة الرئيسية](https://raw.githubusercontent.com/owasp/ai-vulnerabilities-playground/HEAD/docs/screenshots/home.png)
![تشغيل PI‑01](https://raw.githubusercontent.com/owasp/ai-vulnerabilities-playground/HEAD/docs/screenshots/about_labs.png)
![استكشاف المختبرات](https://raw.githubusercontent.com/owasp/ai-vulnerabilities-playground/HEAD/docs/screenshots/explore_labs.png)
![تشغيل PI‑01](https://raw.githubusercontent.com/owasp/ai-vulnerabilities-playground/HEAD/docs/screenshots/PI01.png)

استكشاف الأخطاء وإصلاحها

``
قم بتشغيل npm install داخل apps/web.

``
أضف from typing import Iterator (أو أزل التعليق التوضيحي) في main.py.

CORS / SSE محظور
تأكد من أن CORS_ORIGINS يتضمن http://localhost:5173.

أخطاء Ollama
تأكد من أن ollama serve يعمل وأن النموذج مسحوب: ollama pull llama3.1.

فحص سريع باستخدام curl

curl -N -X POST http://localhost:8000/api/labs/PI_01/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt":"قل مرحباً في جملة واحدة."}'

يجب أن ترى أسطر دفق مثل data: {"content":"مرحباً …"}.

المساهمة

نرحب بالمساهمات! يرجى:

1. Fork المستودع وإنشاء فرع ميزة جديد.
2. اتباع أسلوب الترميز الحالي (TypeScript/React + Python/FastAPI).
3. إضافة اختبارات أو عرض توضيحي سريع حيثما أمكن.
4. فتح طلب سحب (PR) مع وصف واضح، ولقطات شاشة إذا كانت هناك تغييرات في واجهة المستخدم.

المجالات المقترحة:

• مختبرات جديدة (المرحلة 1–4)
• حواجز حماية أفضل / إطار تقييم
• أسرار مستمرة (SQLite/JSON)
• التغليف و Docker

المشكلات والملاحظات

إذا وجدت خطأ أو كانت لديك فكرة:

• افتح Issue مع خطوات إعادة الإنتاج وتفاصيل البيئة.
• أو ابدأ مناقشة لاقتراح تحسينات.

إذا أعجبك هذا المشروع، يرجى ⭐ وضع نجمة / إعجاب به ومشاركته مع الآخرين!

الترخيص

MIT.

البريد الإلكتروني

[email protected]