NuReaper — Escáner de Seguridad de Paquetes NuGet

⚠️ Trabajo en Progreso — El proyecto está en desarrollo activo. El motor de escaneo principal es funcional; la persistencia de base de datos, el almacenamiento en caché y la cobertura completa de pruebas están planificados para próximas iteraciones.

NuReaper es una API backend .NET 8 que analiza automáticamente la seguridad de paquetes NuGet. Proporcionas un enlace a cualquier paquete NuGet, y el sistema descarga recursivamente todo su árbol de dependencias, descompila el código compilado y escanea cada método en busca de patrones maliciosos, devolviendo un informe detallado de amenazas.

🔍 Para lectores no técnicos: Piensa en ello como instalar una aplicación en tu teléfono. Junto con ella, se instalan docenas de bibliotecas más pequeñas automáticamente. NuReaper inspecciona cada una de ellas — examinando el código binario compilado real — y detecta si alguna intenta conectarse a servidores sospechosos, ejecutar código oculto u ocultar su verdadero comportamiento.

---

🎯 ¿Qué hace NuReaper?

Envía una sola solicitud HTTP con una URL de paquete NuGet, y NuReaper:

1. Construye el árbol de dependencias completo — obtiene y mapea recursivamente todos los paquetes de los que depende el objetivo (hasta 20 niveles de profundidad), detectando dependencias circulares en el proceso
2. Descarga y verifica cada paquete — obtiene el archivo .nupkg y calcula su hash SHA-256
3. Analiza el código IL compilado — descompila ensamblados .NET y escanea cada método de cada clase en busca de patrones sospechosos
4. Puntúa el nivel de amenaza — basado en patrones detectados, número de hallazgos, diversidad de tipos, puntuaciones de confianza y profundidad de ofuscación
5. Devuelve un informe completo — con hallazgos por paquete, trazas de flujo de código y el gráfico de dependencias completo

---

🔬 Patrones de Código Malicioso Detectados

El motor analiza el código a nivel de instrucciones IL (Lenguaje Intermedio) y reconoce 7 patrones característicos de software malicioso:

#	Patrón	Descripción
1	Llamada Directa a API	Cadena sospechosa usada inmediatamente en una llamada de red
2	Cadena Asignada	URL asignada a una variable, luego pasada a una llamada de red
3	Construcción de Cadena	URL construida por concatenación ("http://" + var + "/path") — técnica de ofuscación
4	Interpolación de Cadena	URL ensamblada mediante interpolación ($"{part1}{part2}")
5	Interpolación Solo Caracteres	URL construida carácter por carácter desde un array de caracteres — ofuscación avanzada
6	DefaultInterpolatedStringHandler	Mecanismo de interpolación de bajo nivel usado para ocultar cadenas del análisis estático
7	Llamadas API Desnudas	Llamadas de red directas sin cadenas explícitas (TcpClient.Connect, Socket.Connect, Process.Start)

Tipos de Amenazas Detectadas

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

Puntuación del Nivel de Amenaza (0–100)

El algoritmo de puntuación tiene en cuenta:

• Nivel máximo de peligro de cualquier hallazgo individual
• Número total de hallazgos (hasta +30 pts)
• Diversidad de tipos de amenazas detectadas (hasta +15 pts)
• Puntuación media de confianza entre hallazgos (+5 pts si >90%)
• Presencia de ofuscación — construcción de cadenas multi-salto (+10 pts)

---

📡 API

POST /api/PackageScan

Escanea el paquete NuGet dado junto con su árbol de dependencias completo.

Request:

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

Response:

{
  "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": [...]
  }
}

---

🏗️ Arquitectura

Construido sobre Arquitectura Limpia con una estricta separación de preocupaciones:

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

Stack y Patrones

Área	Tecnología / Patrón
Arquitectura	Clean Architecture
Comunicación entre capas	CQRS + MediatR
Análisis de código IL	dnlib
Validación de entrada	FluentValidation + MediatR Pipeline Behavior
Mapeo de objetos	AutoMapper
Registro	Serilog (console + rolling daily file)
Documentación de API	Swagger / OpenAPI
Base de datos	Entity Framework Core + MySQL (Pomelo)
HTTP	IHttpClientFactory with connection pooling
Contenerización	Docker + Docker Compose
Pruebas	xUnit + Moq

---

⚙️ Cómo Funciona el Motor de Escaneo

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

---

📦 Dependencias Clave