theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/seguridad-django/SKILL.md

@@ -0,0 +1,648 @@
+---
+name: seguridad-django
+description: Buenas prácticas de seguridad en Django — autenticación, autorización, protección CSRF, prevención de inyección SQL y XSS, subida segura de archivos y configuraciones de despliegue en producción.
+---
+
+# Buenas prácticas de seguridad en Django
+
+Guías de seguridad integrales para proteger aplicaciones Django contra las vulnerabilidades más comunes.
+
+## Cuándo activarla
+
+- Configurar autenticación y autorización en Django
+- Implementar permisos y roles de usuario
+- Configurar los settings de seguridad de producción
+- Revisar una aplicación Django en busca de problemas de seguridad
+- Desplegar aplicaciones Django a producción
+
+## Settings de seguridad esenciales
+
+### Configuración de producción
+
+```python
+# settings/production.py
+import os
+
+DEBUG = False  # CRÍTICO: nunca uses True en producción
+
+ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', '').split(',')
+
+# Cabeceras de seguridad
+SECURE_SSL_REDIRECT = True
+SESSION_COOKIE_SECURE = True
+CSRF_COOKIE_SECURE = True
+SECURE_HSTS_SECONDS = 31536000  # 1 año
+SECURE_HSTS_INCLUDE_SUBDOMAINS = True
+SECURE_HSTS_PRELOAD = True
+SECURE_CONTENT_TYPE_NOSNIFF = True
+SECURE_BROWSER_XSS_FILTER = True
+X_FRAME_OPTIONS = 'DENY'
+
+# HTTPS y cookies
+SESSION_COOKIE_HTTPONLY = True
+CSRF_COOKIE_HTTPONLY = True
+SESSION_COOKIE_SAMESITE = 'Lax'
+CSRF_COOKIE_SAMESITE = 'Lax'
+
+# Clave secreta (obligatoria vía variable de entorno)
+SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')
+if not SECRET_KEY:
+    raise ImproperlyConfigured('La variable de entorno DJANGO_SECRET_KEY es obligatoria')
+
+# Validación de contraseñas
+AUTH_PASSWORD_VALIDATORS = [
+    {
+        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+        'OPTIONS': {
+            'min_length': 12,
+        }
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
+    },
+]
+```
+
+## Autenticación
+
+### Modelo de usuario personalizado
+
+```python
+# apps/users/models.py
+from django.contrib.auth.models import AbstractUser
+from django.db import models
+
+class User(AbstractUser):
+    """Modelo de usuario personalizado para mayor seguridad."""
+
+    email = models.EmailField(unique=True)
+    phone = models.CharField(max_length=20, blank=True)
+
+    USERNAME_FIELD = 'email'  # Usa el email como nombre de usuario
+    REQUIRED_FIELDS = ['username']
+
+    class Meta:
+        db_table = 'users'
+        verbose_name = 'User'
+        verbose_name_plural = 'Users'
+
+    def __str__(self):
+        return self.email
+
+# settings/base.py
+AUTH_USER_MODEL = 'users.User'
+```
+
+### Hashing de contraseñas
+
+```python
+# Django usa PBKDF2 por defecto. Para mayor seguridad:
+PASSWORD_HASHERS = [
+    'django.contrib.auth.hashers.Argon2PasswordHasher',
+    'django.contrib.auth.hashers.PBKDF2PasswordHasher',
+    'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+    'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
+]
+```
+
+### Gestión de sesiones
+
+```python
+# Configuración de sesiones
+SESSION_ENGINE = 'django.contrib.sessions.backends.cache'  # O 'db'
+SESSION_CACHE_ALIAS = 'default'
+SESSION_COOKIE_AGE = 3600 * 24 * 7  # 1 semana
+SESSION_SAVE_EVERY_REQUEST = False
+SESSION_EXPIRE_AT_BROWSER_CLOSE = False  # Mejor UX, pero menos seguro
+```
+
+## Autorización
+
+### Permisos
+
+```python
+# models.py
+from django.db import models
+from django.contrib.auth.models import Permission
+
+class Post(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    author = models.ForeignKey(User, on_delete=models.CASCADE)
+
+    class Meta:
+        permissions = [
+            ('can_publish', 'Puede publicar posts'),
+            ('can_edit_others', 'Puede editar posts de otros'),
+        ]
+
+    def user_can_edit(self, user):
+        """Comprueba si el usuario puede editar este post."""
+        return self.author == user or user.has_perm('app.can_edit_others')
+
+# views.py
+from django.contrib.auth.mixins import LoginRequiredMixin, PermissionRequiredMixin
+from django.views.generic import UpdateView
+
+class PostUpdateView(LoginRequiredMixin, PermissionRequiredMixin, UpdateView):
+    model = Post
+    permission_required = 'app.can_edit_others'
+    raise_exception = True  # Devuelve 403 en lugar de redirigir
+
+    def get_queryset(self):
+        """Permite editar solo los posts propios."""
+        return Post.objects.filter(author=self.request.user)
+```
+
+### Permisos personalizados
+
+```python
+# permissions.py
+from rest_framework import permissions
+
+class IsOwnerOrReadOnly(permissions.BasePermission):
+    """Solo el propietario puede editar objetos."""
+
+    def has_object_permission(self, request, view, obj):
+        # Lectura permitida para cualquier request
+        if request.method in permissions.SAFE_METHODS:
+            return True
+
+        # Escritura solo para el propietario
+        return obj.author == request.user
+
+class IsAdminOrReadOnly(permissions.BasePermission):
+    """Los admins pueden todo; el resto, solo lectura."""
+
+    def has_permission(self, request, view):
+        if request.method in permissions.SAFE_METHODS:
+            return True
+        return request.user and request.user.is_staff
+
+class IsVerifiedUser(permissions.BasePermission):
+    """Solo permite usuarios verificados."""
+
+    def has_permission(self, request, view):
+        return request.user and request.user.is_authenticated and request.user.is_verified
+```
+
+### Control de acceso basado en roles (RBAC)
+
+```python
+# models.py
+from django.contrib.auth.models import AbstractUser, Group
+
+class User(AbstractUser):
+    ROLE_CHOICES = [
+        ('admin', 'Administrador'),
+        ('moderator', 'Moderador'),
+        ('user', 'Usuario regular'),
+    ]
+    role = models.CharField(max_length=20, choices=ROLE_CHOICES, default='user')
+
+    def is_admin(self):
+        return self.role == 'admin' or self.is_superuser
+
+    def is_moderator(self):
+        return self.role in ['admin', 'moderator']
+
+# Mixins
+class AdminRequiredMixin:
+    """Mixin que exige rol de administrador."""
+
+    def dispatch(self, request, *args, **kwargs):
+        if not request.user.is_authenticated or not request.user.is_admin():
+            from django.core.exceptions import PermissionDenied
+            raise PermissionDenied
+        return super().dispatch(request, *args, **kwargs)
+```
+
+## Prevención de inyección SQL
+
+### Protección del ORM de Django
+
+```python
+# BIEN: el ORM de Django escapa los parámetros automáticamente
+def get_user(username):
+    return User.objects.get(username=username)  # Seguro
+
+# BIEN: usar parámetros con raw()
+def search_users(query):
+    return User.objects.raw('SELECT * FROM users WHERE username = %s', [query])
+
+# MAL: nunca interpoles entrada del usuario directamente
+def get_user_bad(username):
+    return User.objects.raw(f'SELECT * FROM users WHERE username = {username}')  # ¡VULNERABLE!
+
+# BIEN: filter con escapado correcto
+def get_users_by_email(email):
+    return User.objects.filter(email__iexact=email)  # Seguro
+
+# BIEN: objetos Q para consultas complejas
+from django.db.models import Q
+def search_users_complex(query):
+    return User.objects.filter(
+        Q(username__icontains=query) |
+        Q(email__icontains=query)
+    )  # Seguro
+```
+
+### Seguridad adicional con raw()
+
+```python
+# Si debes usar SQL crudo, usa siempre parámetros
+User.objects.raw(
+    'SELECT * FROM users WHERE email = %s AND status = %s',
+    [user_input_email, status]
+)
+```
+
+## Prevención de XSS
+
+### Escapado en plantillas
+
+```django
+{# Django auto-escapa las variables por defecto - SEGURO #}
+{{ user_input }}  {# HTML escapado #}
+
+{# Marca como safe solo el contenido de confianza #}
+{{ trusted_html|safe }}  {# Sin escapar #}
+
+{# Usa filtros de plantilla para HTML seguro #}
+{{ user_input|escape }}  {# Igual que el comportamiento por defecto #}
+{{ user_input|striptags }}  {# Elimina todas las etiquetas HTML #}
+
+{# Escapado de JavaScript #}
+<script>
+    var username = {{ username|escapejs }};
+</script>
+```
+
+### Manejo seguro de strings
+
+```python
+from django.utils.safestring import mark_safe
+from django.utils.html import escape
+
+# MAL: nunca marques como safe la entrada del usuario sin escapar
+def render_bad(user_input):
+    return mark_safe(user_input)  # ¡VULNERABLE!
+
+# BIEN: escapa primero, luego marca como safe
+def render_good(user_input):
+    return mark_safe(escape(user_input))
+
+# BIEN: usa format_html para HTML con variables
+from django.utils.html import format_html
+
+def greet_user(username):
+    return format_html('<span class="user">{}</span>', escape(username))
+```
+
+### Cabeceras HTTP
+
+```python
+# settings.py
+SECURE_CONTENT_TYPE_NOSNIFF = True  # Evita el sniffing de MIME
+SECURE_BROWSER_XSS_FILTER = True  # Activa el filtro XSS
+X_FRAME_OPTIONS = 'DENY'  # Evita el clickjacking
+
+# Middleware personalizado
+from django.conf import settings
+
+class SecurityHeaderMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        response['X-Content-Type-Options'] = 'nosniff'
+        response['X-Frame-Options'] = 'DENY'
+        response['X-XSS-Protection'] = '1; mode=block'
+        response['Content-Security-Policy'] = "default-src 'self'"
+        return response
+```
+
+## Protección CSRF
+
+### Protección CSRF por defecto
+
+```python
+# settings.py - CSRF viene habilitado por defecto
+CSRF_COOKIE_SECURE = True  # Solo se envía por HTTPS
+CSRF_COOKIE_HTTPONLY = True  # Bloquea el acceso desde JavaScript
+CSRF_COOKIE_SAMESITE = 'Lax'  # Mitiga CSRF en algunos casos
+CSRF_TRUSTED_ORIGINS = ['https://example.com']  # Dominios de confianza
+
+# Uso en plantillas
+<form method="post">
+    {% csrf_token %}
+    {{ form.as_p }}
+    <button type="submit">Enviar</button>
+</form>
+
+# Peticiones AJAX
+function getCookie(name) {
+    let cookieValue = null;
+    if (document.cookie && document.cookie !== '') {
+        const cookies = document.cookie.split(';');
+        for (let i = 0; i < cookies.length; i++) {
+            const cookie = cookies[i].trim();
+            if (cookie.substring(0, name.length + 1) === (name + '=')) {
+                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
+                break;
+            }
+        }
+    }
+    return cookieValue;
+}
+
+fetch('/api/endpoint/', {
+    method: 'POST',
+    headers: {
+        'X-CSRFToken': getCookie('csrftoken'),
+        'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(data)
+});
+```
+
+### Eximir vistas (usar con cuidado)
+
+```python
+from django.views.decorators.csrf import csrf_exempt
+
+@csrf_exempt  # ¡Úsalo solo cuando sea absolutamente necesario!
+def webhook_view(request):
+    # Webhook de un servicio externo
+    pass
+```
+
+## Seguridad en subida de archivos
+
+### Validación de archivos
+
+```python
+import os
+import magic  # pip install python-magic
+from django.core.exceptions import ValidationError
+
+ALLOWED_MIMES = {
+    'image/jpeg', 'image/png', 'image/gif', 'application/pdf',
+}
+
+MIME_TO_EXTENSIONS = {
+    'image/jpeg': {'.jpg', '.jpeg'},
+    'image/png': {'.png'},
+    'image/gif': {'.gif'},
+    'application/pdf': {'.pdf'},
+}
+
+def validate_file_type(value):
+    """Valida el tipo de archivo por magic bytes y contrasta la extensión."""
+    mime = magic.from_buffer(value.read(2048), mime=True)
+    value.seek(0)
+
+    if mime not in ALLOWED_MIMES:
+        raise ValidationError('Tipo de archivo no admitido.')
+
+    ext = os.path.splitext(value.name)[1].lower()
+    if ext not in MIME_TO_EXTENSIONS.get(mime, set()):
+        raise ValidationError('La extensión no coincide con el contenido del archivo.')
+
+def validate_file_size(value):
+    """Valida el tamaño del archivo (máx. 5 MB)."""
+    if value.size > 5 * 1024 * 1024:
+        raise ValidationError('Archivo demasiado grande. El máximo es 5 MB.')
+
+# models.py
+class Document(models.Model):
+    file = models.FileField(
+        upload_to='documents/',
+        validators=[validate_file_type, validate_file_size]
+    )
+
+```
+
+En entornos donde instalar libmagic sea difícil (p. ej., contenedores mínimos),
+usa el paquete puro-Python `filetype` como alternativa:
+
+```python
+import os
+from django.core.exceptions import ValidationError
+
+import filetype  # pip install filetype
+
+ALLOWED_MIMES = {
+    'image/jpeg', 'image/png', 'image/gif', 'application/pdf',
+}
+
+MIME_TO_EXTENSIONS = {
+    'image/jpeg': {'.jpg', '.jpeg'},
+    'image/png': {'.png'},
+    'image/gif': {'.gif'},
+    'application/pdf': {'.pdf'},
+}
+
+def validate_file_type(value):
+    """Valida el tipo de archivo por magic bytes."""
+    kind = filetype.guess(value.read(2048))
+    value.seek(0)
+
+    if kind is None or kind.mime not in ALLOWED_MIMES:
+        raise ValidationError('Tipo de archivo no admitido.')
+
+    ext = os.path.splitext(value.name)[1].lower()
+    if ext not in MIME_TO_EXTENSIONS.get(kind.mime, set()):
+        raise ValidationError('La extensión no coincide con el contenido del archivo.')
+```
+
+### Almacenamiento seguro de archivos
+
+```python
+# settings.py
+MEDIA_ROOT = '/var/www/media/'
+MEDIA_URL = '/media/'
+
+# Usa un dominio separado para media en producción
+MEDIA_DOMAIN = 'https://media.example.com'
+
+# No sirvas las subidas de usuarios directamente
+# Usa whitenoise o un CDN para archivos estáticos
+# Usa un servidor separado o S3 para archivos de media
+```
+
+## Seguridad de API
+
+### Limitación de tasa
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    'DEFAULT_THROTTLE_CLASSES': [
+        'rest_framework.throttling.AnonRateThrottle',
+        'rest_framework.throttling.UserRateThrottle'
+    ],
+    'DEFAULT_THROTTLE_RATES': {
+        'anon': '100/day',
+        'user': '1000/day',
+        'upload': '10/hour',
+    }
+}
+
+# Throttle personalizado
+from rest_framework.throttling import UserRateThrottle
+
+class BurstRateThrottle(UserRateThrottle):
+    scope = 'burst'
+    rate = '60/min'
+
+class SustainedRateThrottle(UserRateThrottle):
+    scope = 'sustained'
+    rate = '1000/day'
+```
+
+### Autenticación para API
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    'DEFAULT_AUTHENTICATION_CLASSES': [
+        'rest_framework.authentication.TokenAuthentication',
+        'rest_framework.authentication.SessionAuthentication',
+        'rest_framework_simplejwt.authentication.JWTAuthentication',
+    ],
+    'DEFAULT_PERMISSION_CLASSES': [
+        'rest_framework.permissions.IsAuthenticated',
+    ],
+}
+
+# views.py
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import IsAuthenticated
+
+@api_view(['GET', 'POST'])
+@permission_classes([IsAuthenticated])
+def protected_view(request):
+    return Response({'message': 'Estás autenticado'})
+```
+
+## Cabeceras de seguridad
+
+### Content Security Policy
+
+```python
+# settings.py
+CSP_DEFAULT_SRC = "'self'"
+CSP_SCRIPT_SRC = "'self' https://cdn.example.com"
+CSP_STYLE_SRC = "'self' 'unsafe-inline'"
+CSP_IMG_SRC = "'self' data: https:"
+CSP_CONNECT_SRC = "'self' https://api.example.com"
+
+# Middleware
+class CSPMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        response['Content-Security-Policy'] = (
+            f"default-src {CSP_DEFAULT_SRC}; "
+            f"script-src {CSP_SCRIPT_SRC}; "
+            f"style-src {CSP_STYLE_SRC}; "
+            f"img-src {CSP_IMG_SRC}; "
+            f"connect-src {CSP_CONNECT_SRC}"
+        )
+        return response
+```
+
+## Variables de entorno
+
+### Gestión de secretos
+
+```python
+# Usa python-decouple o django-environ
+import environ
+
+env = environ.Env(
+    # tipado y valor por defecto
+    DEBUG=(bool, False)
+)
+
+# lectura del archivo .env
+environ.Env.read_env()
+
+SECRET_KEY = env('DJANGO_SECRET_KEY')
+DATABASE_URL = env('DATABASE_URL')
+ALLOWED_HOSTS = env.list('ALLOWED_HOSTS')
+
+# Archivo .env (nunca lo subas al repositorio)
+DEBUG=False
+SECRET_KEY=tu-clave-secreta-aqui
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+ALLOWED_HOSTS=example.com,www.example.com
+```
+
+## Registro de eventos de seguridad
+
+```python
+# settings.py
+LOGGING = {
+    'version': 1,
+    'disable_existing_loggers': False,
+    'handlers': {
+        'file': {
+            'level': 'WARNING',
+            'class': 'logging.FileHandler',
+            'filename': '/var/log/django/security.log',
+        },
+        'console': {
+            'level': 'INFO',
+            'class': 'logging.StreamHandler',
+        },
+    },
+    'loggers': {
+        'django.security': {
+            'handlers': ['file', 'console'],
+            'level': 'WARNING',
+            'propagate': True,
+        },
+        'django.request': {
+            'handlers': ['file'],
+            'level': 'ERROR',
+            'propagate': False,
+        },
+    },
+}
+```
+
+## Lista rápida de verificación de seguridad
+
+| Verificación | Descripción |
+|--------------|-------------|
+| `DEBUG = False` | Nunca ejecutes con DEBUG en producción |
+| Solo HTTPS | Fuerza SSL y cookies seguras |
+| Secretos robustos | Usa variables de entorno para SECRET_KEY |
+| Validación de contraseñas | Activa todos los validadores |
+| Protección CSRF | Habilitada por defecto, no la desactives |
+| Prevención de XSS | Django auto-escapa; no uses `&#124;safe` con entrada del usuario |
+| Inyección SQL | Usa el ORM; nunca concatenes strings en consultas |
+| Subida de archivos | Valida tipo y tamaño |
+| Limitación de tasa | Aplica throttling a los endpoints de API |
+| Cabeceras de seguridad | CSP, X-Frame-Options, HSTS |
+| Logging | Registra los eventos de seguridad |
+| Actualizaciones | Mantén Django y sus dependencias al día |
+
+Recuerda: la seguridad es un proceso, no un producto. Revisa y actualiza tus prácticas de seguridad con regularidad.
+
+## Skills relacionadas
+
+- `patrones-django` — Arquitectura y estructura de proyecto
+- `tdd-django` — Testing de permisos y flujos de autenticación
+- `revision-seguridad` — Revisión de seguridad de cambios pendientes