Metadata-Version: 2.4
Name: GuardianUnivalle-Benito-Yucra
Version: 1.1.45
Summary: Middleware y detectores de seguridad (SQLi, XSS, CSRF, DoS) para Django/Flask
Author-email: Andres Benito Calle Yucra <benitoandrescalle035@gmail.com>
License: MIT
Project-URL: Homepage, https://pypi.org/project/guardianunivalle-benito-yucra/
Project-URL: Bug_Tracker, https://github.com/Andyyupy/guardianunivalle-benito-yucra/issues
Keywords: security,django,flask,sqli,xss,csrf,middleware
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Django
Classifier: Framework :: Flask
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: redis>=4.0
Requires-Dist: django>=3.2
Dynamic: license-file

<!-- Información de la librería -->
<table align="center" style="width: 100%; text-align: center; border-collapse: collapse; background-color: #f4f4f9; border-radius: 15px; box-shadow: 0 4px 10px rgba(0, 0, 0, 0.1); padding: 20px;">
  <tr>
    <td style="border: none; padding: 10px 20px;">
      <img src="https://res.cloudinary.com/dsbgmboh1/image/upload/v1780406241/Andres_rsoit1.png"
           alt="Univalle Logo" width="300"
           style="transition: transform 0.3s ease-in-out;"
           onmouseover="this.style.transform='scale(1.1)'"
           onmouseout="this.style.transform='scale(1)'">
    </td>
    <td style="border: none; padding: 10px 20px; text-align: center;">
      <h1 style="font-size: 50px; margin: 0; color: #c62828; font-family: 'Arial', sans-serif; text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.3);">
        Guardian Univalle Benito Yucra
      </h1>
      <p style="margin: 5px 0 0 0; font-size: 18px; color: #444; font-family: 'Segoe UI', sans-serif;">
        Librería de seguridad web para Django basada en detección heurística, scoring de riesgo y bloqueo adaptativo.
      </p>
    </td>
    <td style="border: none; padding: 10px 20px;">
      <img src="https://res.cloudinary.com/dsbgmboh1/image/upload/v1761864884/GuardianUnivalle_imeegq.png"
           alt="Guardian Logo" width="300"
           style="transition: transform 0.3s ease-in-out;"
           onmouseover="this.style.transform='scale(1.1)'"
           onmouseout="this.style.transform='scale(1)'">
    </td>
  </tr>
</table>

`GuardianUnivalle-Benito-Yucra` es una **librería de seguridad para aplicaciones web desarrollada en Python**, distribuida como paquete a través de PyPI y diseñada para fortalecer aplicaciones Django frente a amenazas comunes como **SQL Injection (SQLi)**, **Cross-Site Scripting (XSS)**, **Cross-Site Request Forgery (CSRF)**, **Denegación de Servicio (DoS)** y **scraping automatizado**.

A diferencia de muchas soluciones tradicionales que únicamente validan o sanitizan datos, Guardian Univalle implementa una arquitectura basada en **detección heurística**, **análisis multicapa**, **puntuación de riesgo (Threat Score)** y **bloqueo adaptativo**, funcionando como una capa de protección.

Cada petición HTTP es analizada en tiempo real antes de llegar a la lógica de negocio. El sistema inspecciona cabeceras, parámetros, cuerpos de solicitudes, metadatos y patrones de comportamiento para identificar actividades sospechosas, registrar eventos de auditoría y aplicar medidas de mitigación automáticas cuando el nivel de riesgo supera los umbrales configurados.

---

# Arquitectura General

Guardian Univalle está construido bajo una arquitectura modular basada en middlewares especializados.

Cada middleware:

- Intercepta solicitudes HTTP durante `process_request`.
- Analiza cabeceras, cuerpo y metadatos.
- Evalúa señales de riesgo mediante reglas heurísticas.
- Calcula un score de amenaza.
- Registra evidencias del ataque detectado.
- Permite auditoría centralizada.
- Puede bloquear automáticamente solicitudes maliciosas.

El objetivo es proporcionar una defensa proactiva y extensible capaz de adaptarse a distintos entornos académicos, empresariales y gubernamentales.

---

# Características Principales

✅ Detección heurística de amenazas web.

✅ Sistema de puntuación de riesgo (Threat Score).

✅ Bloqueo adaptativo configurable.

✅ Análisis de cabeceras HTTP.

✅ Inspección de payloads GET, POST y JSON.

✅ Registro y auditoría de incidentes.

✅ Arquitectura modular basada en middlewares.

✅ Integración nativa con Django.

✅ Compatibilidad conceptual con Flask y otros frameworks WSGI.

✅ Diseño extensible para investigación y enseñanza de ciberseguridad.

---

# Módulos de Defensa

## 1. CSRFDefenseMiddleware

### Defensa contra Cross-Site Request Forgery (CSRF)

Detecta intentos de falsificación de solicitudes verificando:

- Cabeceras Origin.
- Cabeceras Referer.
- Tokens CSRF.
- Cookies de sesión.
- Formularios HTML.
- Solicitudes JSON.
- Métodos POST, PUT, PATCH y DELETE.

### Técnicas utilizadas

- Validación semántica del origen.
- Comparación de dominios confiables.
- Correlación entre cabeceras y cookies.
- Evaluación heurística de inconsistencias.

### Resultado

Genera un score de riesgo y registra los detalles del incidente para auditoría o bloqueo automático.

---

## 2. XSSDefenseMiddleware

### Defensa contra Cross-Site Scripting (XSS)

Analiza parámetros y contenido enviado por el usuario para detectar:

- Etiquetas `<script>`.
- `javascript:`
- `vbscript:`
- `data:text/html`
- `eval()`
- Eventos HTML peligrosos.
- Payloads ofuscados.
- Codificación hexadecimal o URL Encoding malicioso.

### Técnicas utilizadas

- Expresiones regulares avanzadas.
- Heurísticas ponderadas.
- Sanitización comparativa opcional mediante Bleach.
- Scoring adaptativo según severidad.

### Resultado

Genera:

```python
request.xss_attack_info
```

con:

- IP de origen.
- Payload detectado.
- Tipo de ataque.
- Score.
- Evidencias encontradas.

---

## 3. SQLIDefenseMiddleware

### Defensa contra SQL Injection

Analiza parámetros GET, POST y JSON para identificar:

- UNION SELECT.
- DROP TABLE.
- INSERT.
- UPDATE.
- DELETE.
- Comentarios SQL (`--`, `#`, `/* */`).
- Subconsultas sospechosas.
- Concatenaciones maliciosas.
- Operadores lógicos utilizados para evasión.

### Técnicas utilizadas

- Análisis sintáctico.
- Correlación contextual.
- Heurísticas de palabras reservadas.
- Scoring basado en patrones combinados.

### Resultado

Genera:

```python
request.sql_injection_info
```

incluyendo:

- Parámetros afectados.
- Evidencias.
- Nivel de riesgo.
- Score final.

---

## 4. DOSDefenseMiddleware

### Defensa contra Denegación de Servicio (DoS)

Supervisa continuamente la actividad por dirección IP para detectar:

- Frecuencia excesiva de solicitudes.
- Picos de tráfico.
- Comportamientos repetitivos.
- Accesos automatizados.
- Sobrecarga de endpoints específicos.

### Técnicas utilizadas

- Sliding Window.
- Rate Limiting adaptativo.
- Detección de patrones repetitivos.
- Correlación de actividad temporal.

### Capacidades

- Bloqueo temporal.
- Lista blanca de IPs confiables.
- Umbrales configurables.
- Registro de incidentes.

---

## 5. ScrapingDefenseMiddleware

### Defensa contra Scraping Automatizado

Detecta bots y sistemas de extracción masiva mediante:

- User-Agent anómalo.
- Ausencia de cabeceras humanas.
- Navegación excesivamente rápida.
- Accesos secuenciales repetitivos.
- Patrones compatibles con crawlers.

### Técnicas utilizadas

- Análisis estadístico.
- Correlación de cabeceras.
- Heurísticas de comportamiento.
- Integración con el detector DoS.

---

# Sistema de Scoring de Amenazas

Uno de los componentes más importantes de Guardian Univalle es su sistema de puntuación de riesgo.

Cada indicador detectado aporta una ponderación específica al score global.

Ejemplo:

| Indicador            | Score |
| -------------------- | ----- |
| Script Tag           | 0.30  |
| javascript:          | 0.40  |
| eval()               | 0.50  |
| UNION SELECT         | 0.70  |
| Origen CSRF inválido | 0.60  |
| Exceso de peticiones | 0.80  |

El score acumulado permite:

- Clasificar amenazas.
- Reducir falsos positivos.
- Aplicar bloqueos automáticos.
- Priorizar incidentes de seguridad.

---

# Instalación

```bash
pip install guardian-univalle
```

---

# Configuración en Django

```python
MIDDLEWARE = [
    "GuardianUnivalle_Benito_Yucra.detectores.detector_dos.DOSDefenseMiddleware",
    "GuardianUnivalle_Benito_Yucra.detectores.detector_sql.SQLIDefenseMiddleware",
    "GuardianUnivalle_Benito_Yucra.detectores.detector_xss.XSSDefenseMiddleware",
    "GuardianUnivalle_Benito_Yucra.detectores.detector_csrf.CSRFDefenseMiddleware",
    "users.middleware.AuditoriaMiddleware",
    "users.auditoria_servidor.AuditoriaServidorMiddleware",
]
```

```python
ALLOWED_HOSTS = [
    "127.0.0.1",
    "localhost",
    "192.168.0.3",
]
```

---

# Configuración Avanzada

```python
# DoS Defense

DOS_LIMITE_PETICIONES = 120
DOS_VENTANA_SEGUNDOS = 60
DOS_PESO = 0.6
DOS_LIMITE_ENDPOINTS = 80
DOS_TIEMPO_BLOQUEO = 300
DOS_TRUSTED_IPS = ["127.0.0.1", "192.168.0.3"]

DOS_PESO_BLACKLIST = 0.3
DOS_PESO_HEURISTICA = 0.1
DOS_UMBRAL_BLOQUEO = 0.8

DOS_DEFENSE_MAX_REQUESTS = 100
DOS_DEFENSE_BLOCK_TIME = 300
DOS_DEFENSE_TRUSTED_IPS = ["127.0.0.1", "192.168.0.3"]

# SQL Injection

SQLI_DEFENSE_TRUSTED_IPS = [
    "127.0.0.1",
    "192.168.0.3"
]

# XSS

XSS_DEFENSE_TRUSTED_IPS = [
    "127.0.0.1",
    "192.168.0.3"
]

XSS_DEFENSE_SANITIZE_INPUT = False
XSS_DEFENSE_BLOCK = True
XSS_DEFENSE_EXCLUDED_PATHS = [
    "/health",
    "/internal"
]

# CSRF

CSRF_DEFENSE_TRUSTED_IPS = [
    "127.0.0.1",
    "192.168.0.3"
]

CSRF_DEFENSE_BLOCK = True
CSRF_DEFENSE_LOG = True
```

---

# Auditoría de Eventos

Ejemplo de incidente registrado:

```python
request.xss_attack_info = {
    "ip": "192.168.1.10",
    "tipos": ["XSS"],
    "descripcion": ["Etiqueta <script> detectada"],
    "payload": {
        "field": "comentario",
        "snippet": "<script>alert(1)</script>"
    },
    "score": 0.92,
    "url": "/comentarios/enviar/"
}
```

La auditoría permite:

- Correlación de eventos.
- Análisis forense.
- Métricas de seguridad.
- Reportes institucionales.
- Seguimiento histórico de incidentes.

---

# Filosofía del Proyecto

Guardian Univalle Benito Yucra busca proporcionar una capa adicional de seguridad para aplicaciones web modernas mediante:

- Detección heurística.
- Análisis semántico de cabeceras.
- Inspección profunda de payloads.
- Correlación de múltiples señales.
- Scoring adaptativo.
- Bloqueo automático basado en riesgo.

Su enfoque combina principios de los sistemas IDS, IPS y WAF, pero integrados directamente en la aplicación web.

---

# Estructura del Paquete

```bash
GuardianUnivalle_Benito_Yucra/
│
├── detectores/
│   ├── detector_csrf.py
│   ├── detector_xss.py
│   ├── detector_sql.py
│   ├── detector_dos.py
│   ├── detector_scraping.py
│
├── auditoria/
│   └── auditoria_middleware.py
│
├── configuracion/
│
└── __init__.py
```

---

# Clasificación Técnica

GuardianUnivalle-Benito-Yucra puede clasificarse como:

✅ Paquete Python (Python Package)

✅ Librería de seguridad web

✅ Conjunto de middlewares de seguridad

✅ Sistema de detección heurística de amenazas

✅ Mini WAF integrado a nivel de aplicación

✅ Framework modular de defensa para Django

---

# Licencia

Licencia MIT.

Uso, modificación y distribución permitidos con atribución correspondiente.

---

📘 Universidad Privada del Valle – Sede La Paz

👨‍💻 Desarrollado por: Andres Benito Calle Yucra

📅 Año: 2025

🔐 Guardian Univalle Benito Yucra — Seguridad inteligente para aplicaciones web mediante detección heurística, scoring de amenazas y bloqueo adaptativo.
