django-image-sec-validator 0.1.1

# Django Image Security Validator

حزمة أمنية خفيفة وقوية لإطار عمل **Django**، تهدف إلى حماية الخوادم من هجمات البايلودات والملفات التنفيذية المخفية خلف صيغ الصور، من خلال الفحص المزدوج لترويسات الملفات والتحقق من البكسلات، مع إمكانية التحويل التلقائي الآمن إلى صيغة **WebP**.

---

## 🛠️ المميزات الرئيسية

1. **التحقق من Magic Bytes (عبر مكتبة filetype):** للتأكد من أن الامتداد والترويسة الفعلية للملف متطابقان ومنعان تزوير الملفات التنفيذية (PE files).
2. **التحقق من سلامة البكسلات (عبر Pillow):** فحص عميق للتأكد من أن الملف عبارة عن صورة سليمة وغير تالفة أو ملغومة.
3. **التطهير التلقائي (Auto WebP Conversion):** إعادة بناء الصورة وتحويلها إلى صيغة WebP لإزالة أي بيانات وصفية (Metadata) أو شيفرات مرفقة.
4. **متوافقة مع النماذج (Django Validators):** سهلة الربط المباشر مع `ImageField`.

---

## 📦 التثبيت

يمكنك تثبيت الحزمة محلياً باستخدام **Poetry** أو **pip**:

```bash
# باستخدام pip من مسار الحزمة محلياً
pip install path/to/django-image-sec-validator

# أو عبر Poetry في مشروعك الآخر
poetry add path/to/django-image-sec-validator

🚀 طريقة الاستخدام

1. استخدام الموثق (Validator) في النماذج (models.py)

يمكنك ربط دالة validate_image_security مباشرة بـ ImageField لمنع رفع أي ملفات مشبوهة أو مزيفة:

from django.db import models
from django_image_sec_validator import validate_image_security, process_and_convert_to_webp

class UserProfile(models.Model):
    avatar = models.ImageField(
        upload_to='avatars/',
        validators=[validate_image_security]
    )

    def save(self, *args, **kwargs):
        # التحويل التلقائي إلى WebP عند الحفظ لتطهير الصورة نهائياً
        if self.avatar and not self.avatar.name.endswith('.webp'):
            self.avatar = process_and_convert_to_webp(self.avatar)
        super().save(*args, **kwargs)

2. الاستخدام المباشر للدوال في الـ Views أو Forms

إذا كنت ترغب في معالجة الملفات برمجياً قبل حفظها:

from django.core.exceptions import ValidationError
from django_image_sec_validator import validate_image_security, process_and_convert_to_webp

def my_upload_view(request):
    if request.method == 'POST':
        uploaded_file = request.FILES.get('image')
        
        try:
            # 1. التحقق من أمان الملف
            validate_image_security(uploaded_file)
            
            # 2. معالجة وتحويل الصورة إلى WebP آمنة
            clean_image = process_and_convert_to_webp(uploaded_file, quality=85)
            
            # ... تابع حفظ الملف أو استخدامه ...
            
        except ValidationError as e:
            # التعامل مع الملف المرفق المرفوض
            print(e.message)

🛡️ متطلبات التشغيل

dependencies = [ "pillow (>=12.3.0,<13.0.0)", "filetype (>=1.2.0,<2.0.0)", "django (>=5.2.17,<6.0.0)", ]

📄 الترخيص

هذا المشروع مرخص تحت رخصة MIT.