theus-cli 0.2.83 → 0.2.85

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

@@ -1,648 +0,0 @@
----
-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