---

## 🖥️ واجهة إدارة المستخدم

يتضمن BlockGuard **تطبيق سطح مكتب WPF** لإدارة الملفات والمجلدات المحمية عبر واجهة مرئية — لا حاجة لتحرير `appsettings.json` يدويًا.

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12349/51a9b7894117382666d869cee59860a33698f666133bd23c6b6cd48b225d942c.png" alt="واجهة BlockGuard" width="640" />
</p>

### الميزات

- **لوحة البيانات** — نظرة عامة على حالة الحماية (إجمالي الملفات، المجلدات، حالة التشفير)
- **الملفات المحمية** — إضافة/إزالة الملفات والمجلدات لحمايتها من وصول الذكاء الاصطناعي عبر مربعات حوار مستعرض الملفات
- **سجل النشاط** — سجل فوري لجميع تغييرات التكوين
- **الإعدادات** — عرض مسار ملف التكوين ومعلومات الوكيل
- **حالة الوكيل** — مؤشر مباشر يوضح ما إذا كانت خدمة وكيل BlockGuard قيد التشغيل

### كيفية تشغيل الواجهة```powershell
# From the project root
dotnet run --project src/BlockGuard.UI

---

## 🚀 بداية سريعة

### 1. استنساخ المستودع```powershell
git clone [email protected]:m2l33k/BlockGuard.git
cd BlockGuard

### 3. بناء الحل```powershell
dotnet build BlockGuard.sln --configuration Release

### 4. تكوين المسارات المحمية والقواعد

قم بتعديل `src/BlockGuard.Agent/appsettings.json` لتحديد **الملفات التي يجب حمايتها** و **العمليات المصرح بها**:```json
{
  "BlockGuard": {
    "ProtectedPaths": [
      "C:\\Secrets\\ai-model-keys",
      "C:\\Secrets\\api-credentials.json"
    ],
    "AuthorizedProcesses": [
      {
        "RuleName": "AI-Model-Inference-Engine",
        "ExecutablePath": "C:\\Program Files\\MyAI\\inference.exe",
        "MinimumIntegrityLevel": "Medium",
        "RequireSignature": false
      }
    ]
  }
}

---

## ⚙️ الإعدادات

جميع الإعدادات موجودة في `src/BlockGuard.Agent/appsettings.json` ضمن قسم `"BlockGuard"`.

### المسارات المحمية

مصفوفة من الملفات أو المجلدات المراد حمايتها. تحمي المجلدات جميع الملفات بشكل متكرر.```json
"ProtectedPaths": [
  "C:\\Secrets\\ai-model-keys",
  "C:\\Secrets\\api-credentials.json",
  "D:\\Confidential\\reports"
]

**مثال: قاعدة تستند إلى التوقيع (لأي أداة إدارة موقعة)**```json
{
  "RuleName": "Signed-Management-Tool",
  "ExecutablePath": null,
  "ExpectedFileHash": null,
  "ExpectedSignerSubject": "CN=Contoso Security",
  "MinimumIntegrityLevel": "High",
  "RequireSignature": true
}

### خيارات أخرى

| الخيار | الافتراضي | الوصف |
|---|---|---|
| `IdentityCacheTtlSeconds` | `30` | المدة (بالثواني) التي تبقى فيها هوية العملية الموثقة في الذاكرة المؤقتة |
| `HandleTimeoutSeconds` | `60` | الحد الأقصى للمدة (بالثواني) لمنح ACL المؤقت |
| `AuditLogPath` | `C:\ProgramData\BlockGuard\Logs\audit.json` | مسار ملف سجل التدقيق بتنسيق JSON |
| `EnableDpapiEncryption` | `true` | تشفير الملفات المحمية في حالة السكون باستخدام DPAPI |
| `DpapiScope` | `LocalMachine` | نطاق DPAPI: `LocalMachine` أو `CurrentUser` |

---

## 🏃 تشغيل الوكيل

### الخيار أ: وضع التطوير (وحدة التحكم)

الأفضل للاختبار والتصحيح. قم بتشغيله من **PowerShell بصلاحيات مرتفعة (مسؤول)**:```powershell
dotnet run --project src/BlockGuard.Agent --configuration Release

اضغط `Ctrl+C` للإيقاف.

### الخيار ب: التثبيت كخدمة ويندوز (إنتاج)```powershell
# 1. Publish a self-contained build
dotnet publish src/BlockGuard.Agent -c Release -r win-x64 --self-contained -o C:\BlockGuard

# 2. Create the Windows Service
sc.exe create BlockGuard binPath= "C:\BlockGuard\BlockGuard.Agent.exe" start= auto obj= "NT AUTHORITY\SYSTEM" DisplayName= "BlockGuard Security Agent"

# 3. Set the service description
sc.exe description BlockGuard "Process-based file access security agent (DLP)"

# 4. Start the service
sc.exe start BlockGuard

---

## ✅ التحقق من عمله

اتبع هذه الخطوات لتأكيد أن BlockGuard يحمي الملفات بشكل صحيح.

### الاختبار 1: التحقق من البناء```powershell
# From the project root directory
dotnet build BlockGuard.sln

# Expected: Build succeeded with 0 Error(s)

**✅ المخرجات المتوقعة:**
- رسالة `BlockGuard Security Agent Starting`
- لا توجد أخطاء `CRITICAL` أو `FATAL`
- `ETW file trace session started successfully`
- `BlockGuard is now actively protecting X path(s)`

**❌ إذا رأيت `ETW session — insufficient privileges`:**
- أنت لا تعمل كمسؤول. انقر بزر الماوس الأيمن على PowerShell → 'تشغيل كمسؤول'

### الاختبار 3: التحقق من قفل قوائم التحكم في الوصول (ACL)

بعد بدء الوكيل، تحقق من أن الملفات المحمية مقفلة:```powershell
# Create a test protected file
New-Item -Path "C:\Secrets" -ItemType Directory -Force
Set-Content -Path "C:\Secrets\api-credentials.json" -Value '{"api_key": "secret123"}'

# Start the agent (it will lock down the file)
dotnet run --project src/BlockGuard.Agent

# In ANOTHER non-admin terminal, try to read the file:
Get-Content "C:\Secrets\api-credentials.json"
# Expected: Access Denied error

### اختبار 5: فحص سجل التدقيق

بعد تشغيل الوكيل لفترة، تحقق من سجل التدقيق:```powershell
# View the last 10 audit entries
Get-Content "C:\ProgramData\BlockGuard\Logs\audit.json" | Select-Object -Last 10

### الاختبار 6: التحقق من التقاط أحداث ETW

افتح محطة طرفية ثانية وحاول الوصول إلى ملف محمي أثناء تشغيل الوكيل:```powershell
# Terminal 1: Agent is running with console output
dotnet run --project src/BlockGuard.Agent

# Terminal 2: Try reading a protected file with notepad
notepad.exe "C:\Secrets\api-credentials.json"

### اختبار 7: التحقق من منع الوصول غير المصرح به (نموذج الذكاء الاصطناعي)

عندما تحاول إحدى العمليات (مثل نموذج ذكاء اصطناعي غير مصرح به) قراءة مجلد أو ملف محمي، يقوم الوكيل فورًا برفض الوصول. سيتلقى الذكاء الاصطناعي خطأ **تم رفض الوصول** صارمًا، ويتم تسجيل المحاولة:

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12349/d2a2e20c0fc60e8b3a5f614b0a53c6c7275b634e93b1ce0b9fe4440c38215fac.png" alt="تم رفض الوصول غير المصرح به" width="600" />
</p>

### اختبار 8: التحقق من تشفير DPAPI```powershell
# Check that the .enc file was created
Test-Path "C:\Secrets\api-credentials.json.enc"
# Expected: True

# Check that the original plaintext file was securely deleted
Test-Path "C:\Secrets\api-credentials.json"
# Expected: False (if EnableDpapiEncryption is true)

### اختبار 10: التحقق من دليل السجلات```powershell
# Check both log locations
Get-ChildItem "C:\ProgramData\BlockGuard\Logs\"

# Expected files:
# audit.json              (structured JSON audit log)
# blockguard-20260305.log (daily rolling application log)

---

## 🔬 كيف يعمل

### تسلسل بدء التشغيل (5 مراحل)```
Phase 1: ACL Lockdown
  └─ Strip all permissions from protected files
  └─ Grant access only to SYSTEM + Administrators
  └─ Disable ACL inheritance

Phase 2: DPAPI Encryption (optional)
  └─ Encrypt each protected file at rest
  └─ Securely delete plaintext (overwrite with random data)
  └─ Store ciphertext as .enc files

Phase 3: Event Subscription
  └─ Register handler for file access events

Phase 4: ETW Monitoring
  └─ Start kernel-level file trace session
  └─ Filter events by protected paths
  └─ Emit FileAccessEvent for each match

Phase 5: Integrity Check Loop
  └─ Every 60 seconds, verify ACLs are intact
  └─ Auto-remediate if tampering detected

### التحقق من العمليات (6 فحوصات)

عندما تصل عملية إلى ملف محمي، يتحقق BlockGuard منها من خلال:

1. **مسار الملف التنفيذي** — يحل المسار الكامل ويقوم بتوحيده (يمنع اجتياز المسار)
2. **تجزئة SHA-256** — يحسب تجزئة الملف الثنائي على القرص (يكشف استبدال الملف)
3. **توقيع Authenticode** — يتحقق من سلسلة التوقيع الرقمي (يكشف الملفات الثنائية غير الموقعة أو المعدلة)
4. **SID مالك العملية** — يستعلم عن الرمز المميز لتحديد الحساب الجاري
5. **مستوى التكامل** — يقرأ التصنيف الإلزامي (غير موثوق/منخفض/متوسط/عالي/النظام)
6. **معرّف العملية الأصلية** — يتتبع سلسلة إنشاء العملية (يكشف الحقن)

جميع الفحوصات **تفشل-مغلقة**: إذا فشلت أي خطوة تحقق، يتم **رفض** الوصول.

---

## 🛠️ استكشاف الأخطاء وإصلاحها

### "جلسة ETW — صلاحيات غير كافية"

**السبب:** الوكيل لا يعمل بصلاحيات المسؤول/النظام.

**الحل:**```powershell
# Right-click PowerShell → "Run as Administrator"
dotnet run --project src/BlockGuard.Agent

### أخطاء البناء بعد الاستنساخ

**الحل:** استعادة حزم NuGet:```powershell
dotnet restore BlockGuard.sln
dotnet build BlockGuard.sln

---

## 🔒 اعتبارات الأمان

### ما يمكن لهذا الوكيل فعله
- ✅ منع العمليات غير المصرح بها من **قراءة** الملفات المحمية عبر تطبيق ACL
- ✅ كشف و**تدقيق** جميع محاولات الوصول إلى الملفات في الوقت الفعلي عبر ETW
- ✅ تشفير الملفات **أثناء التخزين** باستخدام DPAPI
- ✅ كشف و**إصلاح تلقائي** للتلاعب بـ ACL

### ما لا يمكن لهذا الوكيل فعله
- ❌ **حظر قراءات الملفات أثناء التنفيذ** — هذا وكيل وضع المستخدم؛ الحظر الحقيقي أثناء التنفيذ يتطلب برنامج تشغيل kernel minifilter
- ❌ **إيقاف هجمات مستوى النواة** — يمكن لبرنامج تشغيل ضار للنواة تجاوز NTFS ACLs
- ❌ **منع المسؤولين من التجاوز** — يمكن لحسابات المسؤول إزالة ACLs (يتم تخفيف ذلك عن طريق كشف التلاعب)

### توصيات للإنتاج

1. **التشغيل كـ `NT AUTHORITY\SYSTEM`** — استخدم خدمة Windows، وليس تطبيق وحدة تحكم
2. **توقيع الملف الثنائي للوكيل** بشهادة Authenticode لمنع التلاعب الذاتي
3. **تفعيل BitLocker** على وحدة التخزين للتشفير الكامل للقرص (يكمل DPAPI)
4. **إعادة توجيه سجلات التدقيق إلى SIEM** للمراقبة المركزية
5. **تفعيل Secure Boot + Driver Signature Enforcement** لمنع الاختراق على مستوى النواة

---

## 🤝 المساهمة

1. انسخ المستودع (Fork)
2. أنشئ فرع ميزة: `git checkout -b feature/my-feature`
3. قم بتثبيت تغييراتك: `git commit -m "Add my feature"`
4. ادفع إلى الفرع: `git push origin feature/my-feature`
5. افتح طلب سحب (Pull Request)

### أسلوب الكود
- اتبع اصطلاحات التسمية في C# (PascalCase للأعضاء العامة)
- أضف تعليقات توثيق XML لجميع واجهات برمجة التطبيقات العامة
- كل عملية تحقق يجب أن **تفشل مغلقة** (رفض عند الخطأ)
- تخلص صراحة من جميع المقابض الأصلية في كتل `finally`
- امسح مخازن الذاكرة الحساسة بعد الاستخدام

---

## 📄 الترخيص

هذا المشروع مرخص بموجب رخصة MIT. انظر [LICENSE](https://github.com/m2l33k/blockguard/blob/HEAD/LICENSE) للتفاصيل.

---

<p align="center">
  <b>بني على مبادئ الأمان أولاً لحماية ملفات Windows.</b>
  <br/>
  <sub>BlockGuard — لأن بياناتك تستحق حارسًا، وليس مجرد قفل.</sub>
</p>