KcMapper

KcMapper هي أداة لتصدير بيانات إعداد Keycloak إلى قاعدة بيانات رسوم بيانية Neo4j. يتيح هذا التمثيل تحليل العلاقات بين النطاقات (Realms) والعملاء (Clients) والمستخدمين والمجموعات والأدوار. تتضمن الأداة واجهة ويب لتشغيل استعلامات Cypher محددة مسبقًا للتحليل والتدقيق الأمني.

الميزات

• تصدير شامل: يستخرج النطاقات (Realms) والعملاء (Clients) والأدوار (بما في ذلك الأدوار المركّبة) والمجموعات (مع التسلسل الهرمي) والمستخدمين ونطاقات العملاء (Client Scopes) ومخططات التعيين (Mappers) وتدفقات المصادقة.
• نمذجة رسوم بيانية: يمثل إعداد Keycloak على شكل رسم بياني في Neo4j.
• تحليل تفاعلي: يوفر واجهة ويب محلية لتنفيذ استعلامات التحليل المحددة مسبقًا على البيانات المُصدَّرة.
• تدقيق أمني: يتضمن استعلامات للمساعدة في تحديد التكوينات الأمنية الضعيفة المحتملة.
• قابل للتوسعة: يمكن إضافة استعلامات تحليل مخصصة عن طريق تعديل ملف webapp/queries.json.

التثبيت والاستخدام

يغطي هذا الدليل التثبيت المحلي لـ KcMapper. تتطلب هذه الطريقة تثبيت Python وNeo4j على جهازك.

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

• Python 3.9+
• مثيل Neo4j قيد التشغيل (Community أو Desktop).

تثبيت Neo4j (مثال لتوزيعات Debian/Ubuntu)

يمكنك تثبيت Neo4j Community Edition باتباع الخطوات التالية:

# Add the Neo4j GPG key
wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo apt-key add -

# Add the Neo4j repository
echo 'deb https://debian.neo4j.com stable 5' | sudo tee /etc/apt/sources.list.d/neo4j.list

# Update packages and install Neo4j
sudo apt-get update
sudo apt-get install neo4j -y

# Start the Neo4j service
sudo systemctl start neo4j

بعد التثبيت، انتقل إلى http://localhost:7474 في متصفحك وعيّن كلمة المرور الأولية (الافتراضية هي neo4j/neo4j).

للأنظمة الأخرى (Windows وmacOS وغيرها):

• Neo4j Desktop: هذا هو الخيار الأبسط. قم بتنزيل وتثبيت Neo4j Desktop، الذي يوفر واجهة رسومية لإدارة قواعد البيانات الخاصة بك.
• تثبيتات Linux الأخرى: اتبع التعليمات الرسمية في صفحة تثبيت Neo4j.

الإعداد

1. استنساخ المستودع

   root@kitploit:~

   git clone https://github.com/synacktiv/kcmapper.git
   cd kcmapper
   

2. إعداد بيئة Python افتراضية (موصى به)

   root@kitploit:~

   python -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
   

3. تثبيت التبعيات

   root@kitploit:~

   pip install -r requirements.txt
   

4. إعداد متغيرات البيئة انسخ ملف .env.example إلى .env.

   root@kitploit:~

   cp .env.example .env
   

   عدّل ملف .env ليشير إلى مثيل Keycloak الخاص بك وقاعدة بيانات Neo4j المحلية.

   root@kitploit:~

   # --- Keycloak Connection ---
   KEYCLOAK_URL=http://your-keycloak-server:8080/
   KEYCLOAK_USER=admin
   KEYCLOAK_PASSWORD=your_keycloak_admin_password
   # Optional - for confidential clients
   KEYCLOAK_CLIENT_SECRET=
   # Optional - for users with 2FA enabled
   KEYCLOAK_TOTP=
   # Optional - for mTLS authentication
   KEYCLOAK_CERT_PATH=
   
   # --- Neo4j Connection (for local environment) ---
   NEO4J_URI=bolt://localhost:7687
   NEO4J_USER=neo4j
   NEO4J_PASSWORD=your_local_neo4j_password
   

الاستخدام

1. تصدير البيانات شغّل أمر export لملء قاعدة بيانات Neo4j الخاصة بك.

   root@kitploit:~

   python kcmapper_cli.py export
   

   • لتنظيف قاعدة البيانات قبل تصدير جديد، استخدم الخيار --clean:
     root@kitploit:~

     python kcmapper_cli.py export --clean
     

2. تحليل البيانات بمجرد اكتمال التصدير، شغّل واجهة التحليل عبر الويب.

   root@kitploit:~

   python kcmapper_cli.py analyze
   

   • سيكون الخادم متاحًا افتراضيًا على http://127.0.0.1:5001.

البنية

• kcmapper_cli.py: نقطة الدخول الرئيسية لسطر الأوامر.
• /processors: يحتوي على منطق الاستخراج والتحميل لكل نوع من أنواع كائنات Keycloak.
• /utils: دوال مساعدة، أساسًا للاتصال بـ Neo4j وتنظيف البيانات.
• /webapp: يحتوي على تطبيق Flask للويب لتحليل البيانات.

المساهمة

المساهمات مرحّب بها. لا تتردد في فتح issue للإبلاغ عن خطأ أو اقتراح ميزة جديدة. لإضافة استعلامات تحليل جديدة، عدّل ملف webapp/queries.json وقدّم طلب سحب (pull request).

الترخيص

هذا المشروع مرخّص بموجب رخصة MIT. راجع ملف LICENSE للحصول على التفاصيل.