BlacksmithAI

التثبيت

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

• Linux أو macOS أو Windows مع WSL2
• Docker 20.10+ و Docker Compose
• Python 3.12+
• Node.js 18+ (لواجهة الويب)
• 4GB+ من الذاكرة العشوائية (8GB موصى به)

تثبيت uv (مدير حزم Python)

# macOS و Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# التحقق من التثبيت
uv --version

تثبيت Docker

# Ubuntu/Debian
sudo apt update && sudo apt install -y docker.io docker-compose

# macOS
brew install --cask docker

# التحقق
docker --version && docker compose version

تثبيت Node.js و pnpm (واجهة الويب فقط)

# Ubuntu/Debian - Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# macOS - Node.js
brew install node@18

# تثبيت pnpm
npm install -g pnpm
# أو
corepack enable && corepack prepare pnpm@latest --activate

استنساخ وإعداد BlacksmithAI

# استنساخ المستودع
git clone https://github.com/yohannesgk/blacksmith.git
cd blacksmith

# تثبيت مكتبات Python
cd blacksmithAI/blacksmithAI
uv sync

# بناء صورة Docker mini-kali
docker compose up -d

# اختياري: تثبيت مكتبات واجهة الويب الأمامية
cd ../frontend && pnpm install

التكوين

إعداد البيئة

# نسخ قالب البيئة
cp blacksmithAI/.env.example blacksmithAI/.env

# تحرير ملف .env
nano blacksmithAI/.env

تكوين OpenRouter

# إضافة إلى .env
OPENROUTER_API_KEY=your-openrouter-api-key-here

تكوين VLLM (نموذج لغة محلي)

# تثبيت VLLM
cd blacksmithAI/blacksmithAI
uv add vllm huggingface_hub

# بدء خادم VLLM
vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
  --host 0.0.0.0 \
  --port 8000 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.75

تكوين مزود نموذج اللغة

تحرير blacksmithAI/config.json:

{
  "defaults": {
    "provider": "openrouter"
  },
  "providers": {
    "openrouter": {
      "base_url": "https://openrouter.ai/api/v1/chat/completions",
      "default_model": "mistralai/devstral-2512:free",
      "default_embedding_model": "openai/text-embedding-3-small",
      "default_model_config": {
        "context_size": 200000,
        "max_retries": 3,
        "max_tokens": null
      }
    },
    "vllm": {
      "base_url": "http://localhost:8000/v1/chat/completions",
      "default_model": "mistralai/devstral-2512",
      "default_embedding_model": "text-embedding-3-small",
      "default_model_config": {
        "context_size": 200000,
        "max_retries": 3
      }
    }
  }
}

إعداد موفر مخصص

# إضافة إلى قسم موفري config.json
"openai": {
  "base_url": "https://api.openai.com/v1/chat/completions",
  "default_model": "gpt-4-turbo",
  "default_embedding_model": "text-embedding-3-small"
}

# إضافة إلى .env
OPENAI_API_KEY=your-openai-key

# تحديث الافتراضيات
"defaults": { "provider": "openai" }

الاستخدام الأساسي

وضع سطر الأوامر (واجهة المحطة)

# المحطة 1: بدء حاوية mini-kali
cd blacksmithAI/blacksmithAI
docker compose up -d

# المحطة 2: تشغيل واجهة سطر أوامر BlacksmithAI
cd blacksmithAI/blacksmithAI
uv run main.py

# أو استخدم اختصار Makefile
make start-cli

وضع واجهة الويب (3 محطات مطلوبة)

# المحطة 1: بدء حاوية Docker mini-kali
cd blacksmithAI/blacksmithAI
docker compose up -d

# المحطة 2: بدء الواجهة الأمامية (من دليل blacksmithAI/frontend)
pnpm build && pnpm start

# المحطة 3: بدء خادم تطوير LangGraph (من blacksmithAI/blacksmithAI)
uv run langgraph dev

# الوصول على http://localhost:3000

إدارة Docker

# بدء الحاوية
docker compose up -d

# عرض السجلات
docker logs mini-kali-slim

# إيقاف الحاوية
docker compose down

# إعادة تشغيل الحاوية
docker compose restart

# إزالة جميع الحاويات
docker compose down -v

معمارية الوكيل

وكيل المنسق

• الدور: التحكم بالأوامر المركزية
• الوظيفة: تخطيط المهمة، تفويض المهام، توليد التقارير
• الأدوات المتاحة: أدوات التخطيط، أدوات نظام الملفات

وكيل الاستطلاع (رسم خريطة سطح الهجوم)

• الغرض: جمع المعلومات السلبي والإيجابي
• الأدوات: assetfinder، subfinder، whois، dig، nslookup، hping3، dnsrecon
• الناتج: سجلات DNS، النطاقات الفرعية، طوبولوجيا الشبكة

وكيل المسح/التعداد (الفحص العميق)

• الغرض: تعداد المستخدمين، اختبار API، اكتشاف الإصدار
• الأدوات: nmap، masscan، enum4linux-ng، nikto، whatweb، fingerprintx، gobuster، wpscan
• الناتج: المنافذ المفتوحة، الخدمات، التقنيات، نقاط النهاية

وكيل تحليل الثغرات (تقييم المخاطر)

• الغرض: خدمات الخرائط ل CVEs، أولويات المخاطر
• الأدوات: nuclei، sslscan
• الناتج: قائمة الثغرات مع درجات الشدة والقابلية للاستغلال

وكيل الاستغلال (تنفيذ PoC)

• الغرض: التحقق من الثغرات من خلال الاستغلال المسيطر عليه
• الأدوات: sqlmap، hydra، medusa، ncrack، البرامج النصية المخصصة (Python/Go/Perl/Ruby)
• الناتج: دليل الاختراق مع الأدلة

وكيل ما بعد الاستغلال (تقييم التأثير)

• الغرض: تقييم نطاق التأثير وفرص التحول
• الأدوات: netcat، socat، نفق SSH، impacket
• الناتج: مسارات الحركة الجانبية، جرد بيانات الاعتماد، التأثير على الأعمال

أوضاع المسح وأسلوب عمل

استطلاع سريع

# سلسلة أسلوب عمل نموذجية
1. مواصفات الهدف (المجال/IP)
2. المنسق يبدأ مرحلة الاستطلاع
3. وكيل Recon يكتشف: النطاقات الفرعية، سجلات DNS، خوادم البريد
4. النتائج المُغذاة بوكيل Scan/Enum

اختبار اختراق كامل

# سلسلة أسلوب العمل للتقييم الكامل
المنسق (التخطيط)
  ↓
وكيل Recon (سطح الهجوم) → الإخراج: الخدمات والتقنيات
  ↓
وكيل Scan/Enum (الفحص العميق) → الإخراج: المنافذ والإصدارات
  ↓
وكيل تحليل Vuln (خريطة المخاطر) → الإخراج: قائمة CVE مع النقاط
  ↓
وكيل Exploit (التحقق من PoC) → الإخراج: الاستغلالات العاملة
  ↓
وكيل ما بعد الاستغلال (التأثير) → الإخراج: مسارات الحركة الجانبية
  ↓
المنسق (التقرير النهائي مع المعالجة)

تقييم الثغرات فقط

# خدمات الهدف المحددة مباشرة لتحليل vuln
1. توفير معلومات الخدمة (الإصدار، المنفذ)
2. وكيل تحليل Vuln يخطط ل CVEs
3. وكيل Exploit يختبر الثغرات ذات الأولوية العالية

مرجع الأدوات

أدوات الاستطلاع

أداة	أمر	الغرض
assetfinder	assetfinder target.com	اكتشاف النطاق الفرعي
subfinder	subfinder -d target.com	تعداد النطاق الفرعي
whois	whois target.com	البحث عن معلومات المجال
dig	dig target.com	استفسارات سجل DNS
dnsrecon	dnsrecon -d target.com	تعداد DNS
hping3	hping3 -p 80 target.com	مسح الشبكة

المسح والتعداد

أداة	أمر	الغرض
nmap	nmap -sV target.com	مسح المنفذ واكتشاف الإصدار
masscan	masscan 0.0.0.0/0 -p80,443	مسح المنفذ عالي السرعة
nikto	nikto -h target.com	مسح ثغرات خادم الويب
gobuster	gobuster dir -u http://target.com -w wordlist.txt	فرض الدليل/DNS
wpscan	wpscan --url target.com	مسح ثغرات WordPress
whatweb	whatweb target.com	تحديد تقنية الويب

تحليل الثغرات

أداة	أمر	الغرض
nuclei	nuclei -target target.com	مسح الثغرات السريع
sslscan	sslscan target.com:443	تحليل تكوين SSL/TLS

أدوات الاستغلال

أداة	الغرض
sqlmap	اختبار حقن SQL المؤتمتة
hydra	فرض كلمة المرور
medusa	تدقيق تسجيل الدخول بالشبكة المتوازي
ncrack	كسر المصادقة بالشبكة
البرامج النصية المخصصة	تطوير الاستغلال Python/Go/Perl/Ruby

ما بعد الاستغلال

أداة	الغرض
netcat	تصحيح الشبكة ونقل البيانات
socat	ممر متعدد الأغراض
ssh -D	نفق وسيط SOCKS للتحول
impacket	أدوات بروتوكول Windows (psexec، secretsdump)

الإخراج والتقرير

توليد التقارير

# المنسق ينشئ تقارير منظمة تحتوي على:
- ملخص تنفيذي
- النتائج مع تصنيفات الشدة
- تفاصيل الأدلة وإثبات المفهوم
- الأنظمة والخدمات المتأثرة
- إرشادات العلاج
- تقييم تأثير العمل

هيكل التقرير

{
  "mission_name": "اختبار الاختراق - مثال Corp",
  "target": "example.com",
  "findings": [
    {
      "vulnerability": "حقن SQL في نموذج تسجيل الدخول",
      "severity": "CRITICAL",
      "affected_service": "تطبيق الويب v2.1",
      "evidence": "SELECT version() أرجع إصدار قاعدة البيانات",
      "remediation": "استخدام العبارات المُعدة، التحقق من الإدخال"
    }
  ],
  "timeline": "2025-03-10T14:30:00Z",
  "tested_systems": ["web-server", "api-gateway", "database"]
}

التكوين المتقدم

إضافة موفري نماذج لغة مخصصين

{
  "providers": {
    "custom-provider": {
      "base_url": "https://your-api-endpoint.com/v1/chat/completions",
      "default_model": "your-model-name",
      "default_embedding_model": "embedding-model",
      "default_model_config": {
        "context_size": 200000,
        "max_retries": 3,
        "max_tokens": null
      }
    }
  }
}

VLLM مع نماذج مختلفة

# نموذج صغير (7B) - أسرع، ذاكرة أقل
vllm serve mistralai/Mistral-7B-Instruct-v0.2 \
  --host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.75

# نموذج كبير (123B) - أكثر قدرة
vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
  --host 0.0.0.0 --port 8000 --max-model-len 8192

# نموذج مخصص من HuggingFace
uv run hf auth login  # تسجيل الدخول إلى HF أولاً
vllm serve meta-llama/Llama-2-7b-chat-hf \
  --host 0.0.0.0 --port 8000

أوامر Makefile

# الإعداد والتثبيت
make help              # إظهار جميع الأوامر
make setup            # الإعداد الأولي الكامل
make install          # اعتماديات Python فقط
make frontend-install # اعتماديات واجهة الويب الأمامية

# إدارة Docker
make docker-build     # بناء صورة mini-kali
make docker-up        # بدء الحاوية
make docker-down      # إيقاف الحاوية
make docker-logs      # عرض السجلات

# VLLM نموذج لغة محلي
make vllm-install     # تثبيت VLLM
make vllm-serve       # بدء VLLM (123B)
make vllm-serve-small # بدء VLLM (7B)

# تشغيل BlacksmithAI
make start-cli        # وضع واجهة سطر الأوامر
make start-ui         # واجهة الويب (إظهار الإعداد)
make start-all        # بدء سريع واجهة سطر الأوامر

# الأدوات المساعدة
make status           # حالة حاوية Docker
make check-deps       # التحقق من الاعتماديات
make check-config     # التحقق من التكوين
make clean            # تنظيف الحاويات
make stop             # إيقاف جميع الخدمات

التكامل مع الأدوات الموجودة

استخدام BlacksmithAI مع أدوات OSINT

# جمع البيانات بأدوات خارجية
assetfinder -subs-only target.com > subdomains.txt

# التغذية في BlacksmithAI
# سيجري الوكلاء عمليات مسح موجهة على النطاقات الفرعية المكتشفة

نقاط التكامل

• إخراج Nmap → المُغذاة بـ Vuln Analysis لرسم خريطة الخدمة
• قوائم النطاق الفرعي → المسح الموجه بواسطة وكيل Scan/Enum
• نقاط نهاية API → اختبار الثغرات المباشر
• أنظمة المصادقة → محاولات الفرض والاستغلال

تكامل البرامج النصية المخصصة

# كتابة البرامج النصية للاستغلال المخصصة في دلائل الوكيل
# يمكن للوكلاء تنفيذ برامج Python/Go/Perl/Ruby نصية
# مثال: حمولة حقن SQL مخصصة
cat > custom_exploit.py << 'EOF'
import sys
target = sys.argv[1]
# منطق الاستغلال المخصص
EOF

# استدعاء الوكلاء: python custom_exploit.py target.com

أفضل الممارسات

تخطيط ما قبل التقييم

# تحديد النطاق كتابياً
- قائمة الهدف (المجالات/IP)
- فترة الاختبار
- الأنظمة المصرح بها وناقلات الهجوم
- متطلبات التقرير
- معالجة البيانات الحساسة

# التحقق من الترخيص القانوني
- إذن مكتوب من العميل/المالك
- قواعد الاشتباك (RoE)
- اتفاقيات NDA والسرية

الحفاظ الآمن

# التوصيات
1. استخدام بيئات اختبار معزولة إن أمكن
2. البدء بالاستطلاع فقط
3. اختبار الثغرات بالتسلسل، وليس بالتوازي
4. تجنب البيانات المفيدة المدمرة بدون موافقة صريحة
5. مراقبة سلوك النظام أثناء الاستغلال
6. الحفاظ على السجلات التفصيلية لجميع الأنشطة

جودة التقرير

# يجب أن تتضمن النتائج الشاملة:
- وصف الثغرة الواضح
- درجة CVSS/الشدة
- دليل إثبات المفهوم
- الخدمات والإصدارات المتأثرة
- تقييم التأثير على الأعمال
- خطوات العلاج ذات الأولوية
- الجدول الزمني للاستغلال

اختيار نموذج اللغة

# يؤثر اختيار النموذج على النتائج:
- نماذج أسرع: استطلاع سريع، مسح أساسي
- نماذج أكبر: تحليل معقد، اتخاذ قرارات أفضل
- VLLM محلي: التركيز على الخصوصية، بدون اعتماديات API
- OpenRouter: فعال من حيث التكلفة، خيارات متعددة الطرز

# توصية: استخدم Sonnet/GPT-4 للتقييم المعقد

الاعتبارات القانونية والأخلاقية

متطلبات التفويض

• احصل دائماً على إذن مكتوب قبل الاختبار
• حدد النطاق بوضوح في قواعد الاشتباك
• اختبر فقط الأنظمة التي تمتلكها أو لديك تفويض مكتوب صريح للاختبار
• قد تؤدي انتهاكات القانون (CFAA، GDPR، وما إلى ذلك) إلى المسؤولية المدنية/الجنائية

الإفصاح المسؤول

# بعد الاختبار:
1. توثيق جميع النتائج مع الشدة
2. إخطار مالك النظام بالثغرات
3. السماح بوقت معقول للإصلاح (عادةً 90 يوماً)
4. الحفاظ على سرية تفاصيل الثغرة
5. الإبلاغ إلى البائعين إذا تأثرت المنتجات الخارجية

حماية البيانات

• تقليل استخراج البيانات أثناء الاختبار
• تخزين آمن لجميع التقارير والأدلة
• استخدام التشفير للنتائج الحساسة
• الامتثال لأنظمة حماية البيانات (GDPR، HIPAA، إلخ)
• حذف البيانات بعد إكمال العقد

استكشاف الأخطاء

مشاكل Docker

# الحاوية لن تبدأ
docker ps  # التحقق إذا كانت قيد التشغيل
docker logs mini-kali-slim  # عرض الأخطاء

# تضارب المنفذ
lsof -i :9756  # التحقق من استخدام المنفذ
docker run -i --rm -p 9757:9756 mini-kali-slim -d  # استخدام منفذ مختلف

أخطاء مزود نموذج اللغة

# مشاكل OpenRouter
# - تحقق من مفتاح API: echo $OPENROUTER_API_KEY
# - تحقق من الحالة: https://status.openrouter.ai/

# مشاكل VLLM
curl http://localhost:8000/v1/models  # تحقق مما إذا كان VLLM قيد التشغيل
# - التحقق من الذاكرة: free -h
# - تأكد من توفر GPU: nvidia-smi

أداء الوكيل

# استجابات بطيئة
# - التبديل إلى نموذج أسرع في config.json
# - التحقق من موارد النظام (top، htop)

# الوكيل عالق في حلقة
# - تقليل التعقيد المهمة
# - التحقق من إخراج الأداة للأخطاء
# - مراجعة سجلات الوكيل للحلقات اللانهائية

# الاعتماديات المفقودة
cd blacksmithAI/blacksmithAI
uv sync  # إعادة التثبيت

الموارد

• GitHub: https://github.com/yohannesgk/blacksmith
• الإصدار المستضاف: https://bs.kahanlabs.com
• مجتمع Discord: https://discord.gg/y9Rfag3cVk
• توثيق الأدوات: blacksmithAI/tools.md
• توثيق الوكيل: blacksmithAI/agents/tools_doc/

الرخصة

• مفتوح المصدر: GPL-3.0-only (الاستخدام المجتمعي والتعديل وإعادة التوزيع)
• الترخيص التجاري: متاح للدمج المغلق المصدر
• جهة الاتصال: yohannesgk@kahanlabs.com