### الخطوة 2: إعداد بيئة بايثون

**Linux/macOS:**```bash
python3 -m venv venv
source venv/bin/activate
pip install -e .

### الخطوة 3: تكوين مزود الذكاء الاصطناعي

يدعم Guardian العديد من مزودي الذكاء الاصطناعي. قم بتكوين المزود المفضل لديك في `config/guardian.yaml`:```yaml
# config/guardian.yaml
ai:
  # Choose your provider: openai, claude, gemini, openrouter, or requesty
  provider: openai
  
  # OpenAI Configuration (recommended)
  openai:
    model: gpt-4o
    api_key: sk-your-api-key-here  # Or set OPENAI_API_KEY env var
  
  # Claude Configuration
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null  # Or set ANTHROPIC_API_KEY env var
  
  # Gemini Configuration
  gemini:
    model: gemini-2.5-pro
    api_key: null  # Or set GOOGLE_API_KEY env var
  
  # OpenRouter Configuration
  openrouter:
    model: anthropic/claude-3.5-sonnet
    api_key: null  # Or set OPENROUTER_API_KEY env var

  # Requesty Configuration (OpenAI-compatible gateway)
  requesty:
    model: openai/gpt-4o-mini
    api_key: null  # Or set REQUESTY_API_KEY env var

### الخطوة 4: تهيئة الإعدادات```bash
# Verify installation
python -m cli.main --help

# Check AI provider status
python -m cli.main models

### سيناريوهات الاستخدام المثال

#### 1. اختبار اختراق سريع لتطبيق ويب```bash
# Fast security check with evidence capture
python -m cli.main workflow run --name web_pentest --target https://dvwa.csalab.app

#### 3. سير عمل مخصص مع المعلمات```bash
# Run with workflow-specific parameters
# Parameters in workflow YAML override config defaults
python -m cli.main workflow run --name web_pentest --target example.com

#### 5. تبديل مزودي الذكاء الاصطناعي```bash
# Use OpenAI GPT-4
python -m cli.main workflow run --name web_pentest --target example.com --provider openai

# Use Claude
python -m cli.main workflow run --name web_pentest --target example.com --provider claude

# Use Gemini
python -m cli.main workflow run --name web_pentest --target example.com --provider gemini

# Local Ollama (no cloud)
OLLAMA_HOST=http://localhost:11434 python -m cli.main workflow run --name recon --target scanme.nmap.org --provider ollama

# Any OpenAI-compatible endpoint (vLLM, LM Studio, Together, Groq)
python -m cli.main workflow run --name web_pentest --target example.com --provider openai_compatible

تمكين توجيه المحلل في `config/guardian.yaml`:```yaml
rag:
  enabled: true
  top_k: 5

ثلاثة أدوار (داعٍ أحمر، داعٍ أزرق، حكم) يناظرون فقط النتائج الغامضة — الأحكام الواثقة تتخطى المناظرة للحد من تكلفة الرموز.

#### 8. التصنيف البصري (vision-LLM)```bash
# Captures full-page screenshots and feeds them to a vision-capable provider
python -m cli.main workflow run --name web_visual_pentest --target https://example.com --provider openai

#### 10. القياس عن بعد + المصنف المتعلم (بدون اتصال)```bash
# Anonymise sessions into JSONL (no raw targets, no commands, no secrets)
python -m cli.main telemetry export ./reports --out telemetry.jsonl

# Train the offline tool ranker
python -m cli.main telemetry train telemetry.jsonl

# Inspect what the ranker learned
python -m cli.main telemetry status

> **مستخدمو ويندوز**: استخدم `python -m cli.main` بدلاً من `guardian`

---

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

### مرجع الإعدادات الكامل

قم بتحرير `config/guardian.yaml` لتخصيص سلوك Guardian:```yaml
# AI Configuration
ai:
  provider: openai  # openai, claude, gemini, openrouter, requesty
  
  openai:
    model: gpt-4o
    api_key: sk-your-key  # Or use OPENAI_API_KEY env var
  
  claude:
    model: claude-3-5-sonnet-20241022
    api_key: null
  
  gemini:
    model: gemini-2.5-pro
    api_key: null
  
  temperature: 0.2
  max_tokens: 8000

# Penetration Testing Settings
pentest:
  safe_mode: true              # Prevent destructive actions
  require_confirmation: true   # Confirm before each step
  max_parallel_tools: 3        # Concurrent tool execution
  max_depth: 3                 # Maximum scan depth
  tool_timeout: 300            # Tool timeout in seconds

# Output Configuration
output:
  format: markdown             # markdown, html, json
  save_path: ./reports
  include_reasoning: true
  verbosity: normal            # quiet, normal, verbose, debug

# Scope Validation
scope:
  blacklist:                   # Never scan these
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
  require_scope_file: false
  max_targets: 100

# Tool Configuration (defaults)
tools:
  httpx:
    threads: 50
    timeout: 10
    tech_detect: true
  
  nuclei:
    severity: ["critical", "high", "medium"]
    templates_path: ~/nuclei-templates
  
  nmap:
    default_args: "-sV -sC"
    timing: T4

**أولوية المعاملات:**
- معاملات سير العمل **تتجاوز** معاملات التهيئة
- معاملات التهيئة **تتجاوز** الإعدادات الافتراضية للأداة
- سير عمل مكتفية ذاتيًا وقابلة لإعادة الاستخدام

---

## 📖 التوثيق

### أدلة المستخدم
- **[دليل البدء السريع](https://github.com/zakirkun/guardian-cli/blob/HEAD/QUICKSTART.md)** - ابدأ واشتغل في 5 دقائق
- **[مرجع الأوامر](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/)** - توثيق مفصل لجميع الأوامر
- **[دليل التهيئة](https://github.com/zakirkun/guardian-cli/blob/HEAD/config/guardian.yaml)** - مرجع كامل للتهيئة
- **[دليل سير العمل](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - إنشاء سير عمل مخصصة
- **[دليل التقييم](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/EVAL_GUIDE.md)** - تشغيل وتوسيع إطار التقييم
- **[دليل الإضافات](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/PLUGIN_GUIDE.md)** - شحن موفري وأدوات الطرف الثالث
- **[سجل التغييرات](https://github.com/zakirkun/guardian-cli/blob/HEAD/CHANGELOG.md)** - تاريخ الإصدارات وملاحظات الترحيل

### أدلة المطورين
- **[إنشاء أدوات مخصصة](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/TOOLS_DEVELOPMENT_GUIDE.md)** - بناء تكاملات الأدوات الخاصة بك
- **[تطوير سير العمل](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/WORKFLOW_GUIDE.md)** - إنشاء سير عمل اختبار مخصصة
- **[الأدوات المتاحة](https://github.com/zakirkun/guardian-cli/blob/HEAD/tools/README.md)** - نظرة عامة على الأدوات المدمجة

### نظرة عامة على البنية```
Guardian Architecture:
┌─────────────────────────────────────────┐
│         AI Provider Layer               │
│  (OpenAI, Claude, Gemini, OpenRouter,   │
│   Requesty)                             │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│       Multi-Agent System                │
│  Planner → Tool Agent → Analyst →      │
│            Reporter                      │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      Workflow Engine                    │
│  - Parameter Priority                   │
│  - Evidence Capture                     │
│  - Session Management                   │
└─────────────────────────────────────────┘
                 │
┌─────────────────────────────────────────┐
│      Tool Integration Layer             │
│  (19 Security Tools)                    │
└─────────────────────────────────────────┘

---

## 🆕 أحدث التحديثات

### الإصدار 4.0.0 — بحث وتطوير جديد + توسعة التغطية

**المسار أ — بحث وتطوير الذكاء الاصطناعي/الوكيل (7 عناصر)**

| المعرف | العنصر | النقاط البارزة |
|---|---|---|
| A1 | قاعدة معرفة RAG | `core/knowledge_base.py` SQLite + FTS5 + تضمينات اختيارية؛ توجيه المحلل عبر فتحة `kb_references`؛ `guardian kb {seed,update,query,status}` |
| A2 | فرز مناظرة متعددة الوكلاء | أحمر/أزرق/حكم فقط على نتائج MEDIUM-fp؛ نوع خطوة تحليل جديد `agent: debate` |
| A3 | تحليل لقطات الشاشة بواسطة Vision-LLM | `tools/playwright_screenshot.py` + `core/agents/visual_triage.py`؛ OpenAI + Claude `generate_with_images` |
| A4 | عقد المكونات الإضافية + المزوّدون المحليون | اكتشاف نقطة الدخول للمزوّدين والأدوات؛ تم تضمين مزوّدي **Ollama** + **المتوافقين مع OpenAI** |
| A5 | اختيار الأدوات المُتعلَّم (بدون اتصال) | `core/learners/tool_ranker.py` + `core/telemetry.py`؛ اشتراك اختياري عبر `ai.use_learned_ranker: true` |
| A6 | عِدَّة التقييم | `evals/{__init__,scoring,fixtures_loader,test_*}.py` + نماذج ذهبية؛ 3 مستويات (محلل، سير عمل، توجيه الوكيل) |
| A7 | ترقية نموذج الحكم | `BaseAgent.think_deeply(judge_model=...)` تبديل واستعادة؛ تحكيم النصوص بتكلفة أقل بنحو 10 مرات |

**المسار ب — توسعة تغطية الأدوات (7 عناصر)**

| المعرف | الفئة | الأدوات المضافة |
|---|---|---|
| B8 | Active Directory | crackmapexec, bloodhound, kerbrute, impacket-secretsdump |
| B9 | Mobile Android | mobsf, apkleaks, objection |
| B10 | مفحموات API | schemathesis, restler, cariddi |
| B11 | SAST + الأسرار | semgrep, trufflehog, dependency-check |
| B12 | فريق أحمر LLM | garak, pyrit, prompt_fuzz |
| B13 | جسر Burp/ZAP | zap, burp |
| B14 | مصدّرو المخرجات | SARIF v2.1.0, DefectDojo, Slack |

**معيار الجودة:**
- 296 اختبارًا ناجحًا (+93% من خط الأساس v3 البالغ 153)
- جميع تعزيزات v3 محفوظة: محددات حقن الأوامر، تنظيف المفاتيح، نطاق تحليل DNS، نقاط التفتيش الذرية، تدوير السجلات، التحميل الكسول للأدوات
- `guardian --help` زمن بدء التشغيل يبقى <500ms رغم 50 أداة
- أسطح CLI جديدة: `guardian kb`، `guardian telemetry`
- 8 سير عمل جديدة مشحونة: `web_pentest_with_debate`، `web_visual_pentest`، `ad_assessment`، `mobile_android`، `llm_redteam`، `sast_review`، `api_pentest_v2`، بالإضافة إلى سير عمل v3 الحالية

### الإصدار 3.0.0 — التعزيز + المحرك v2

- محددات حقن الأوامر (`<UNTRUSTED_TOOL_OUTPUT>`) على جميع مخرجات الأدوات
- جدولة DAG، مخططات Pydantic، نقاط تفتيش ذرية، `--resume`
- 11 غلافًا جديدًا (سحابة/حاوية/SBOM/GraphQL/JWT/OSINT)
- إعادة حساب CVSS v3.1 + كشف الانحراف
- تدوير السجلات، تنظيف المفاتيح عند الكتابة
- بوابة تأكيد موصلة للأدوات النشطة+

### الإصدار 2.0.0

- ذكاء اصطناعي متعدد المزوّدين (OpenAI، Claude، Gemini، OpenRouter، Requesty)
- ربط الأدلة عبر `execution_id`
- نظام أولوية معلمات سير العمل

---

## 🤝 المساهمة

نرحب بالمساهمات! إليك الطريقة:

### إعداد بيئة التطوير```bash
# Fork and clone
git clone https://github.com/zakirkun/guardian-cli.git
cd guardian-cli

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Format code
black .

**أخطاء مزود الذكاء الاصطناعي**```bash
# Verify API key is set
python -m cli.main models

# Check provider configuration
cat config/guardian.yaml | grep -A 5 "ai:"

**عدم تحميل سير العمل**```bash
# Check workflow file exists
ls workflows/web_pentest.yaml

# Verify YAML syntax
python -c "import yaml; yaml.safe_load(open('workflows/web_pentest.yaml'))"

لمزيد من المساعدة، [افتح مشكلة](https://github.com/zakirkun/guardian-cli/issues).

---

## 📄 الترخيص

هذا المشروع مرخص بموجب رخصة MIT - راجع ملف [LICENSE](https://github.com/zakirkun/guardian-cli/blob/HEAD/LICENSE) للتفاصيل.

---

## 🙏 شكر وتقدير

- **OpenAI** - إمكانيات GPT-4
- **Anthropic** - Claude AI
- **Google** - Gemini AI
- **LangChain** - إطار تنسيق الذكاء الاصطناعي
- **ProjectDiscovery** - أدوات أمان مفتوحة المصدر (httpx, subfinder, nuclei)
- **Nmap** - استكشاف الشبكات وتدقيق الأمان
- **مجتمع الأمان** - مطورو الأدوات والباحثون

---

## 📞 الدعم والتواصل

- **مشكلات GitHub**: [الإبلاغ عن الأخطاء أو طلب الميزات](https://github.com/zakirkun/guardian-cli/issues)
- **النقاشات**: [انضم إلى نقاشات المجتمع](https://github.com/zakirkun/guardian-cli/discussions)
- **الوثائق**: [اقرأ الوثائق](https://github.com/zakirkun/guardian-cli/blob/HEAD/docs/)
- **الأمان**: أبلغ عن الثغرات بشكل خاص إلى [email protected]

---

## 🌟 تاريخ النجوم

<a href="https://github.com/zakirkun/guardian-cli/stargazers">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zakirkun/guardian-cli&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zakirkun/guardian-cli&type=Date" />
    Star History Chart
  </picture>
</a>

---
---

<div align="center">

**Guardian** - اختبار اختراق ذكي وأخلاقي وآلي

صنع بـ ❤️ من قبل مجتمع الأمان

[⬆ العودة إلى الأعلى](#-guardian)

</div>