NuReaper — ماسح أمان حزم NuGet

⚠️ قيد العمل — المشروع قيد التطوير النشط. محرك الفحص الأساسي قيد إعادة البناء

NuReaper هو واجهة برمجية خلفية (backend API) مبنية على .NET 8 تقوم بتحليل أمان حزم NuGet تلقائيًا. تقوم بتزويده برابط لأي حزمة NuGet، فيقوم النظام بتنزيل شجرة التبعيات بالكامل بشكل تكراري، وفك تجميع الكود المُترجم، وفحص كل دالة بحثًا عن أنماط خبيثة — ثم يعيد تقريرًا مفصلاً عن التهديدات.

🔍 للقُرّاء غير التقنيين: تخيّل الأمر كما لو كنت تُثبّت تطبيقًا على هاتفك. يُثبَّت معه تلقائيًا العشرات من المكتبات الأصغر. يقوم NuReaper بفحص كل واحدة منها — بالنظر إلى الكود الثنائي المُترجم الفعلي — ويكتشف ما إذا كان أي منها يحاول الاتصال بخوادم مشبوهة، أو تنفيذ كود مخفي، أو إخفاء سلوكه الحقيقي.

---

🎯 ماذا يفعل NuReaper؟

أرسل طلب HTTP واحدًا يحتوي على رابط حزمة NuGet، وسيقوم NuReaper بـ:

1. بناء شجرة التبعيات الكاملة — يجلب ويُخطّط جميع الحزم التي تعتمد عليها الحزمة الهدف بشكل تكراري (حتى عمق 20 مستوى)، مع اكتشاف التبعيات الدائرية أثناء ذلك
2. تنزيل كل حزمة والتحقق منها — يجلب ملف .nupkg ويحسب تجزئته SHA-256
3. تحليل كود IL المُترجم — يفك تجميع تجميعات .NET ويفحص كل دالة في كل صنف بحثًا عن أنماط مشبوهة
4. تقييم مستوى التهديد — بناءً على الأنماط المكتشفة، وعدد النتائج، وتنوع الأنواع، ودرجات الثقة، وعمق الإخفاء
5. إعادة تقرير كامل — مع النتائج لكل حزمة، وتتبّع مسار الكود، ومخطط التبعيات الكامل

---

🔬 أنماط الكود الخبيث المكتشفة

يحلّل المحرك الكود على مستوى تعليمات IL (اللغة الوسيطة) ويتعرّف على 7 أنماط مميزة للبرمجيات الخبيثة:

#	النمط	الوصف
1	استدعاء API مباشر	سلسلة نصية مشبوهة تُستخدم فورًا في استدعاء شبكي
2	سلسلة نصية مُعيَّنة	رابط URL يُعيَّن لمتغير، ثم يُمرَّر إلى استدعاء شبكي
3	بناء سلسلة نصية	رابط URL يُبنى بالدمج ("http://" + var + "/path") — تقنية إخفاء
4	إقحام السلاسل النصية	رابط URL يُجمَّع عبر الإقحام ($"{part1}{part2}")
5	إقحام الأحرف فقط	رابط URL يُبنى حرفًا بحرف من مصفوفة أحرف — إخفاء متقدم
6	DefaultInterpolatedStringHandler	آلية إقحام منخفضة المستوى تُستخدم لإخفاء السلاسل النصية عن التحليل الساكن
7	استدعاءات API مجرّدة	استدعاءات شبكية مباشرة دون سلاسل نصية صريحة (TcpClient.Connect، Socket.Connect، Process.Start)

أنواع التهديدات المكتشفة

Network:      HttpClient, WebClient, DNS, TcpClient, WebSocket
Execution:    Process.Start, Assembly.Load, Activator.CreateInstance
Low-level:    DllImport, VirtualAlloc, CreateThread, NtCreateThreadEx
System:       ManagementObjectSearcher (WMI)
String-based: Concatenation, CharArray, Interpolation, StringBuilder
Suspicious:   URL, IP address, .onion address, Base64

درجة مستوى التهديد (0–100)

تراعي خوارزمية التقييم ما يلي:

• أقصى مستوى خطورة لأي نتيجة منفردة
• العدد الإجمالي للنتائج (حتى +30 نقطة)
• تنوع أنواع التهديدات المكتشفة (حتى +15 نقطة)
• متوسط درجة الثقة عبر النتائج (+5 نقاط إذا >90%)
• وجود الإخفاء — بناء سلاسل نصية متعدد القفزات (+10 نقاط)

---

📡 واجهة API

POST /api/PackageScan

يفحص حزمة NuGet المحددة مع شجرة تبعياتها الكاملة.

الطلب:

{
  "url": "https://www.nuget.org/packages/System.Net.Http/4.3.4"
}

الاستجابة:

{
  "rootPackageName": "System.Net.Http",
  "rootPackageVersion": "4.3.4",
  "totalPackages": 12,
  "totalFindingsFromAllPackages": 5,
  "threatLevelAllPackages": 47.5,
  "scannedTimeAllPackages": "2026-03-25T12:00:00Z",
  "packages": [
    {
      "packageName": "System.Net.Http",
      "version": "4.3.4",
      "sha256Hash": "abc123...",
      "threatLevel": 35.0,
      "totalFindings": 3,
      "findings": [
        {
          "type": "HttpClientCall",
          "confidenceScore": 95.0,
          "dangerLevel": 60.0,
          "evidence": "http://example.com/payload",
          "location": "MyClass::SendData",
          "hopDepth": 0,
          "flowTrace": "[Pattern1] Direct API call using string..."
        }
      ]
    }
  ],
  "dependencyGraph": {
    "rootPackage": "[email protected]",
    "nodes": [...],
    "edges": [...],
    "cycles": [...]
  }
}

---

🏗️ البنية المعمارية

مبني على Clean Architecture مع فصل صارم للمسؤوليات:

NuReaperBackend/
├── NuReaper.Api/               # API layer — controllers, middleware, startup
├── NuReaper.Application/       # Application layer — commands, interfaces, DTOs, validation
├── NuReaper.Domain/            # Domain core — entities, enums, abstractions
├── NuReaper.Infrastructure/    # Implementations — scanners, parsers, repositories
│   └── Repositories/
│       ├── Scanners/           # IL analysis engine
│       │   ├── Analysis/       # ScanModule, ScanMethod, NetworkApiCallScan
│       │   ├── Detectors/      # 7 pattern detectors (Pattern1–Pattern7)
│       │   ├── Patterns/       # PatternRegistry (regex: URL, IP, .onion, Base64)
│       │   ├── RiskCalculation/# Threat scoring algorithm
│       │   ├── Finders/        # Locating API calls within IL instructions
│       │   ├── VariableAnalysis/# Tracking variable values across IL
│       │   └── StringAnalysis/ # Reconstructing strings from fragments
│       ├── Parsers/            # .nuspec file parsing
│       ├── GraphBuilders/      # Dependency graph construction (BFS + recursion)
│       └── FileHelpers/        # Download, extract, SHA-256
└── Docker/
    ├── Dockerfile
    └── docker-compose.yml

التقنيات والأنماط

المجال	التقنية / النمط
البنية المعمارية	Clean Architecture
التواصل بين الطبقات	CQRS + MediatR
تحليل كود IL	dnlib
التحقق من المدخلات	FluentValidation + MediatR Pipeline Behavior
تعيين الكائنات	AutoMapper
التسجيل	Serilog (console + rolling daily file)
توثيق API	Swagger / OpenAPI
قاعدة البيانات	Entity Framework Core + MySQL (Pomelo)
HTTP	IHttpClientFactory with connection pooling
الحاويات	Docker + Docker Compose
الاختبار	xUnit + Moq

---

⚙️ كيف يعمل محرك الفحص

Package URL
    │
    ▼
DependencyGraphBuilder          ← builds dependency graph from .nuspec files
    │  (recursion + BFS, cycle detection)
    ▼
List of unique packages
    │
    ▼  (parallel, SemaphoreSlim — CPU-1 threads)
NetworkApiCallScan per package
    ├── DownloadPackageAsync     ← fetches .nupkg
    ├── CalculateSha256          ← integrity verification
    ├── ExtractNupkgAsync        ← unpacks the archive
    └── GetAssemblyFiles         ← lists .dll files
            │
            ▼  (Parallel.ForEachAsync)
        ScanModule (per .dll)
            │
            ▼  (Parallel.ForEach — all types and methods)
        ScanMethod (per method)
            │
            ▼  (7 pattern detectors)
        Pattern1..7 → FindingSummaryDto
            │
            ▼
    CalculateThreatLevel         ← score 0–100
    │
    ▼
ScanPackageResultResponse

---

📦 التبعيات الرئيسية

الحزمة	الغرض
dnlib	فك تجميع وتحليل .NET IL
MediatR	CQRS — خط أنابيب الأوامر/الاستعلامات
FluentValidation	التحقق من الطلبات
AutoMapper	تعيين الكائنات عبر الطبقات
Serilog	التسجيل المُهيكل
Pomelo.EntityFrameworkCore.MySql	MySQL ORM
Swashbuckle.AspNetCore	Swagger UI
xUnit + Moq	اختبار الوحدات

---

📄 الترخيص

هذا المشروع متاح بموجب ترخيص PolyForm Noncommercial License 1.0.0، ويُحظر الاستخدام التجاري. للحصول على ترخيص تجاري أو للاستفسارات، تواصل عبر: [email protected]