- **دعم متعدد الخوادم**: اكتشاف وتحصين Apache وNginx وIIS
- **المسح المتزامن**: تجمّع خيوط + تحديد معدل لإجراء عمليات فحص سريعة ومحترمة
- **جمع الأدلة**: يتم الحفاظ على استجابات HTTP والترويسات ومحتويات الملفات
- **معالجة مرنة للأخطاء**: التعامل الموثوق مع حالات انتهاء المهلة وفشل DNS ورفض الاتصال

### 🤖 أدلة التحصين المدعومة بالذكاء الاصطناعي

اختر مزوّد الذكاء الاصطناعي الذي يناسب احتياجاتك:

| المزوّد             | الأفضل لـ         | السرعة          | التكلفة          | الخصوصية         |
| -------------------- | ------------------ | --------------- | ------------- | --------------- |
| **OpenAI GPT-4**     | جودة إنتاجية       | ⚡ سريع (35 ثانية) | 💰 $0.25/مسح | 🔒 قياسي     |
| **Anthropic Claude** | تركيز على الخصوصية | ⚡ سريع (45 ثانية) | 💰 $0.30/مسح | 🔒 محسّن     |
| **Ollama (محلي)**    | خصوصية كاملة       | 🐢 بطيء (28 دقيقة) | 💰 مجاني       | 🔐 100% دون اتصال |

**وضعان للتحليل:**

- **تقني**: مقاطع إعدادات Apache/Nginx، أوامر CLI، تحصين خطوة بخطوة
- **تنفيذي**: تقييم مخاطر بلغة مبسطة لأصحاب المصلحة والإدارة

### 📊 التقارير الاحترافية

**تقارير JSON** (قابلة للقراءة آليًا)```json
{
  "tool": "hephaestus",
  "version": "0.2.0",
  "target": "https://example.com",
  "mode": "safe",
  "summary": {
    "critical": 3,
    "high": 2,
    "medium": 5,
    "low": 3,
    "info": 0
  },
  "findings": [...],
  "diff": {...}
}

### 💾 استمرارية قاعدة البيانات

قاعدة بيانات SQLite **مشتركة مع مجموعة Argos** (`~/.argos/argos.db`):

- **سجل الفحص**: التاريخ، المدة، عدد النتائج، توزيع الخطورة
- **مستودع النتائج**: قاعدة بيانات ثغرات قابلة للبحث (أكثر من 1159 نتيجة مخزنة)
- **النطاقات الموثّقة**: تتبع رموز الموافقة مع تاريخ الانتهاء
- **التكامل بين الأدوات**: يعمل بسلاسة مع Argus وPythia والأدوات المستقبلية```bash
# Query recent scans
sqlite3 ~/.argos/argos.db "SELECT * FROM scans WHERE tool='hephaestus' ORDER BY scan_id DESC LIMIT 10"

# Find critical issues
sqlite3 ~/.argos/argos.db "SELECT * FROM findings WHERE severity='critical' AND tool='hephaestus'"

**2. (اختياري) قم بتثبيت `venv` إذا لم يكن متوفرًا بالفعل**```bash
# Debian/Ubuntu
sudo apt update && sudo apt install -y python3-venv

# Fedora/RHEL
sudo dnf install python3-virtualenv

# macOS (via Homebrew)
brew install [email protected]

**4. ترقية pip**```bash
python -m pip install --upgrade pip

**6. تكوين مفاتيح API (إذا كنت تستخدم الذكاء الاصطناعي السحابي)**```bash
# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

### أول فحص لك```bash
# Basic scan (safe mode, no consent required)
python -m heph --target https://example.com

# With HTML report
python -m heph --target https://example.com --html

# With AI hardening guide (requires consent)
python -m heph --target https://example.com --use-ai --html

### المسح المتقدم```bash
# Control scan speed (1-20 req/s)
python -m heph --target https://example.com --rate 10

# Control concurrency (1-20 threads)
python -m heph --target https://example.com --threads 8

# Custom timeout (useful for slow servers)
python -m heph --target https://example.com --timeout 60

# Custom output directory
python -m heph --target https://example.com --report-dir ./my-reports

# Custom User-Agent
python -m heph --target https://example.com --user-agent "MyBot/1.0"

# Disable SSL verification (testing only)
python -m heph --target https://self-signed.badssl.com --no-verify-ssl

**الخطوة 2: اختبر إعدادك**```bash
# Verify AI provider works
python -m heph.core.ai openai

### الوضع العدواني (يتطلب الموافقة)```bash
# Step 1: Generate consent token
python -m heph --gen-consent example.com
# Output: Token: verify-a3f9b2c1d8e4...

# Step 2: Place token on your server
# Create: https://example.com/.well-known/verify-a3f9b2c1d8e4.txt
# Content: verify-a3f9b2c1d8e4

# Step 3: Verify consent
python -m heph --verify-consent http \
  --domain example.com \
  --token verify-a3f9b2c1d8e4

# Step 4: Run aggressive scan (deeper checks, higher rate limit)
python -m heph --target https://example.com --aggressive

#### Anthropic Claude

**الأفضل لـ: خصوصية معززة**

- ⭐ الجودة: ممتازة (5/5)
- ⚡ السرعة: ~45 ثانية
- 💰 التكلفة: ~$0.30 لكل فحص
- 🔒 الخصوصية: معززة (نهج Anthropic القائم على الخصوصية أولاً)```bash
export ANTHROPIC_API_KEY="sk-ant-..."
python -m pip install langchain-anthropic==1.0.0

### الخصوصية والأمان

**التنظيف التلقائي**

قبل الإرسال إلى مزودي الذكاء الاصطناعي، يزيل Hephaestus تلقائيًا:

- ✅ رموز الموافقة
- ✅ مفاتيح API وبيانات الاعتماد
- ✅ المفاتيح الخاصة والشهادات
- ✅ عناوين IP الداخلية
- ✅ بيانات اعتماد قاعدة البيانات

**الاشتراك الاختياري فقط**

- يتطلب تحليل الذكاء الاصطناعي علامة `--use-ai` صريحة
- يتطلب الفحص العدواني رمز موافقة موثّق
- أنت تتحكم في أي مزود يرى بياناتك

**للخصوصية القصوى**: استخدم Ollama محليًا.

---

## 🧪 مختبرات الاختبار الآمنة

**⚠️ لا تفحص أبدًا المواقع الإنتاجية دون إذن كتابي!**

استخدم مختبرات Docker الخاصة بنا للتدرب بأمان:

### إعداد بيئة الاختبار

### الخيار 1: السكربت التفاعلي (موصى به)```bash
# Run the interactive deployment script
cd docker && ./deploy.sh

**الماسح الضوئي للإنتاج:**```bash
# Start Hephaestus scanner service
docker compose -f docker/compose.yml up -d

# Run a scan
docker compose -f docker/compose.yml exec hephaestus heph --target https://example.com

# View reports
ls -lh docker/reports/

### افحص المختبرات```bash
# Scan Apache lab (from host)
python -m heph --target http://localhost:8080 --html

# Scan Nginx lab (from host)
python -m heph --target http://localhost:8081 --html

# AI-powered analysis (requires OPENAI_API_KEY)
python -m heph --target http://localhost:8080 --use-ai --html

# OR from inside production container (using container name)
docker compose -f docker/compose.yml exec hephaestus python -m heph --target http://hephaestus-vulnerable-apache --html

**إزالة كل شيء (تحذير: يحذف البيانات والتقارير):**```bash
# Using script (with confirmation)
cd docker && ./deploy.sh  # Choose option 5 (Remove All)

# OR manually
docker compose -f docker/compose.yml down -v
docker compose -f docker/compose.testing.yml down -v
rm -rf docker/data docker/reports

**مختبر الاختبار (الخوادم القابلة للاختراق):**```bash
# Start Apache + Nginx vulnerable servers
docker compose -f docker/compose.testing.yml up -d

# Scan from host
python -m heph --target http://localhost:8080 --html

# Stop lab
docker compose -f docker/compose.testing.yml down

### الخيار 2: تشغيل Docker المباشر

**بناء الصورة:**```bash
docker build -f docker/Dockerfile -t hephaestus:0.2.0 .

**مع تحليل الذكاء الاصطناعي:**```bash
docker run --rm \
  -v $(pwd)/docker/reports:/reports \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  hephaestus:0.2.0 \
  --target https://example.com \
  --use-ai \
  --ai-tone both \
  --html

---
## 📊 فهم التقارير

### بنية التقرير```
~/.hephaestus/
├── reports/
│   ├── hephaestus_report_example_20251021_143022.json
│   └── hephaestus_report_example_20251021_143022.html
└── (shared with Argos)
    ~/.argos/
    ├── argos.db          # Shared database
    └── logs/
        └── hephaestus.log

### تصنيف الخطورة

- **CRITICAL**: .env مكشوف، .git قابل للوصول، phpinfo، server-status، تفريغات SQL
- **HIGH**: الكشف عن إصدار الخادم، TLS ضعيف، TLS مفقود، طرق HTTP غير آمنة
- **MEDIUM**: فقدان ترويسات مهمة (HSTS، CSP، X-Frame-Options)، سرد الدليل، كشف صفحة الخطأ
- **LOW**: ترويسات ثانوية (X-Content-Type-Options، Referrer-Policy، Permissions-Policy)
- **INFO**: نتائج معلوماتية (تم اكتشاف الخادم، TLS 1.2 سليم)

---

## 📁 هيكل المشروع```
hephaestus-server-forger/
│
├── heph/                       # Main application package
│   ├── checks/                 # Security check modules (13 phases)
│   │   ├── __init__.py
│   │   ├── api_discovery.py    # Phase 11: Swagger/OpenAPI/GraphQL exposure
│   │   ├── config.py           # Phase 5: Directory listing detection
│   │   ├── config_file.py      # Phase 14: Offline httpd.conf/nginx.conf parser
│   │   ├── cookies.py          # Phase 12: HttpOnly/Secure/SameSite analysis
│   │   ├── cors.py             # Phase 8: CORS wildcard & reflection probes
│   │   ├── files.py            # Phase 2: 70+ sensitive file paths
│   │   ├── headers.py          # Phase 4: Security headers analysis
│   │   ├── http_methods.py     # Phase 3: Unsafe HTTP methods (PUT/DELETE/TRACE)
│   │   ├── phpinfo.py          # Phase 13: phpinfo() dangerous settings
│   │   ├── ports.py            # Phase 7: 37-port scanner with banner grabbing
│   │   ├── robots.py           # Phase 9: robots.txt disallowed path analysis
│   │   ├── server_info.py      # Phase 1: Apache/Nginx/IIS fingerprinting
│   │   ├── tls.py              # Phase 6: Deep TLS/SSL + CVE correlation
│   │   └── waf.py              # Phase 10: 13 WAF signatures detection
│   │
│   ├── core/                   # Core infrastructure
│   │   ├── __init__.py
│   │   ├── ai.py               # LangChain AI (GPT-4/Claude/Ollama) + cost tracking
│   │   ├── config.py           # Configuration loader
│   │   ├── consent.py          # Consent token system (HTTP + DNS)
│   │   ├── cve_lookup.py       # NVD CVE API integration
│   │   ├── db.py               # SQLite — shared with Argos suite (~/.argos/argos.db)
│   │   ├── diff.py             # Scan diff engine (--diff last / --diff <id>)
│   │   ├── http_client.py      # Token-bucket rate-limited HTTP client
│   │   ├── logging.py          # Structured logging
│   │   ├── owasp.py            # HEPH-* code → OWASP Top 10 2021 mapper
│   │   └── report.py           # JSON + HTML report generation
│   │
│   ├── __init__.py             # Package metadata
│   ├── __main__.py             # Entry point
│   ├── cli.py                  # CLI (30+ flags incl. --use-ai, --diff, --config-file)
│   └── scanner.py              # Orchestrator — 13 parallel phases
│
├── assets/
│   └── ascii.txt               # Hephaestus braille ASCII art
│
├── config/                     # Configuration files
│   ├── defaults.yaml           # Default settings
│   └── prompts/                # AI prompt templates
│       ├── technical.txt       # Technical hardening prompt
│       └── non_technical.txt   # Executive summary prompt
│
├── db/
│   └── migrate.sql             # Shared database schema (Argos suite)
│
├── docker/                     # Docker deployment
│   ├── vulnerable-apache/      # Vulnerable Apache lab (port 8080/8443)
│   │   └── docker-entrypoint.sh
│   ├── vulnerable-nginx/       # Vulnerable Nginx lab (port 8081/8444)
│   │   └── docker-entrypoint.sh
│   ├── compose.yml             # Production stack
│   ├── compose.testing.yml     # Vulnerable lab stack
│   ├── deploy.sh               # Interactive deployment script
│   └── Dockerfile              # Production image
│
├── docs/                       # Documentation
│   ├── media/                  # README visual assets
│   │   ├── hephaestus-banner.webp  # Banner 1280×400
│   │   ├── hephaestus-hero.webp    # Hero 1600×640
│   │   ├── console.webp            # Terminal scan output
│   │   ├── report_html.webp        # HTML report header
│   │   └── report_findings.webp    # Findings table with CVE badges
│   ├── AI_INTEGRATION.md       # AI providers setup guide
│   ├── CONSENT.md              # Consent system details
│   ├── DATABASE_GUIDE.md       # Shared database reference
│   ├── ETHICS.md               # Ethical use guidelines
│   ├── REPORT_FORMAT.md        # JSON/HTML report specification
│   ├── ROADMAP.md              # v0.3.0 tickets and priorities
│   └── TESTING_GUIDE.md        # Safe testing practices
│
├── schema/
│   └── report.schema.json      # JSON report schema (OWASP + CVE fields)
│
├── scripts/
│   └── cli-examples.md         # CLI usage examples
│
├── templates/
│   └── report.html.j2          # HTML report template — forge theme
│
├── CHANGELOG.md                # Version history
├── CODE_OF_CONDUCT.md          # Community guidelines
├── CONTRIBUTING.md             # Contribution guide
├── LICENSE                     # MIT License
├── README.md                   # This file
├── requirements.txt            # Python dependencies
└── setup.py                    # Package installer

### الإبلاغ عن المشكلات

وجدت خطأ؟ لديك طلب ميزة؟

**افتح مشكلة**: https://github.com/rodhnin/hephaestus-server-forger/issues

يرجى تضمين:

- إصدار Hephaestus (`python -m heph --version`)
- إصدار Python (`python --version`)
- نظام التشغيل
- خطوات إعادة الإنتاج (للأخطاء)
- السلوك المتوقع مقابل السلوك الفعلي

---

## 📚 التوثيق

توثيق شامل متاح في دليل `docs/`:

| المستند                                    | الوصف                               |
| ------------------------------------------- | ----------------------------------------- |
| [AI_INTEGRATION.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/AI_INTEGRATION.md) | دليل إعداد الذكاء الاصطناعي الكامل (جميع المزوّدين الثلاثة) |
| [CONSENT.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/CONSENT.md)               | التفاصيل التقنية لنظام رمز الموافقة    |
| [DATABASE_GUIDE.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/DATABASE_GUIDE.md) | مخطط SQLite والاستعلامات والإدارة        |
| [ETHICS.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/ETHICS.md)                 | الإطار القانوني والمبادئ الأخلاقية    |
| [REPORT_FORMAT.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/REPORT_FORMAT.md)   | مخطط JSON ومواصفات HTML       |
| [TESTING_GUIDE.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/TESTING_GUIDE.md)   | الاختبار الآمن باستخدام مختبرات Docker             |
| [ROADMAP.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/ROADMAP.md)               | الميزات المستقبلية وخطط التطوير     |

### روابط سريعة

- **سجل التغييرات**: [CHANGELOG.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/CHANGELOG.md)
- **الترخيص**: [LICENSE](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/LICENSE)
- **أمثلة CLI**: [scripts/cli-examples.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/scripts/cli-examples.md)

---

## ⚖️ الترخيص

هذا المشروع مرخص بموجب **رخصة MIT** - راجع ملف [LICENSE](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/LICENSE) للحصول على التفاصيل.```
MIT License

Copyright (c) 2026 Rodney Dhavid Jimenez Chacin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.