StackPractices
advanced Por Mathias Paulenko

Guía Completa de Seguridad de APIs

Asegura tus APIs de punta a punta: rate limiting, autenticación, validación de entrada, CORS, prevención de inyección, gateway y tests.

Introducción

Las APIs son la principal superficie de ataque de las aplicaciones modernas — cada endpoint es un punto de entrada que un atacante puede alcanzar sin tocar tu frontend. El OWASP API Security Top 10 existe precisamente porque las brechas de API dominan los reportes de incidentes: la autorización rota a nivel de objeto (BOLA) está detrás de buena parte de las filtraciones, y basta un parámetro user_id que olvidaste verificar.

La verdad incómoda de la seguridad de APIs: ningún control aislado te salva. El rate limiting no frena a un atacante con token válido rascando los registros 1 a 1.000.000. La validación de entrada no impide que un usuario autenticado edite un campo que nunca debería ver. La seguridad funciona por capas — cada control caza lo que el anterior dejó pasar — y esta guía cubre la pila de abajo a arriba: transporte y CORS, autenticación, rate limiting, validación de entrada, prevención de inyección, mass assignment, patrones de gateway, paginación, audit logging y cómo probar todo. Los ejemplos usan FastAPI + Pydantic v2 porque los conceptos se trasladan a cualquier stack.

Defensa en Profundidad

Piensa la seguridad de APIs como puertas concéntricas, no como un muro:

Defensa en profundidad para APIs: una petición pasa por CORS y comprobaciones de transporte, autenticación y validación de API key, rate limiting, validación de entrada y esquemas, y luego el handler con autorización y protección contra mass assignment; el audit logging y los tests de seguridad envuelven todas las capas.

Dos propiedades hacen que las capas funcionen. Primera, cada capa falla cerrada: una clave caducada, un origen desconocido, un body malformado — todo devuelve error antes de llegar a tu lógica de negocio. Segunda, las capas son independientes: saltarse el rate limiter no ayuda al atacante si la validación y la autorización se mantienen. Cuando audites tu API, recorre las capas en orden y pregunta “¿qué confía esta capa sobre la anterior?” — la respuesta debería ser “nada que no haya verificado”.

Modelo de Amenazas: Contra Qué Protegerse

El abuso de APIs se agrupa en unas pocas formas:

  • Ataques de enumeración — iterar IDs (/users/1, /users/2) para rascar datos. Defensa: checks de autorización a nivel de objeto (BOLA), rate limiting, topes de paginación.
  • Credential stuffing y fuerza bruta — martillear endpoints de auth con contraseñas filtradas. Defensa: límites estrictos en rutas de auth, MFA donde importa, logging de intentos fallidos.
  • Inyección — SQL, comandos, plantillas a través de parámetros. Defensa: queries parametrizadas, validación por esquema, listas blancas para valores dinámicos.
  • Escrituras con privilegios excesivos — mass assignment, escalada de privilegios editando campos role/is_admin. Defensa: esquemas de petición explícitos que excluyen campos sensibles.
  • Agotamiento de recursos — bodies enormes, size=999999, queries caras. Defensa: límites de tamaño, topes de página, timeouts de query.
  • Exposición de datos — devolver objetos completos cuando bastan tres campos, errores verbosos filtrando stack traces. Defensa: DTOs de respuesta, payloads de error genéricos.

No necesitas un modelo de amenazas perfecto para empezar — necesitas las capas en su sitio y luego afinar a tus endpoints reales.

Anatomía de una Brecha de API

La mayoría de brechas reales de API no parecen un asedio — parecen tráfico normal que toca el objeto equivocado. Recorre un incidente típico de BOLA (autorización rota a nivel de objeto): el atacante crea una cuenta gratuita, obtiene un token real y llama GET /api/orders/1 — le devuelve su pedido. Cambia el 1 por un 2. Le devuelve el pedido de otro cliente. Sin inyección, sin cadena de exploit, sin alerta: cada petición estaba autenticada, cada respuesta fue 200. Cuando un socio descubre sus datos en un foro, el atacante ya recorrió todos los IDs numéricos de pedidos, facturas y tickets de soporte.

Lo que falló no fue la autenticación — fue la capa que todos olvidan: verificar que el objeto pedido pertenece al principal autenticado. El middleware validó el token; nada validó que el pedido #2 perteneciera al dueño de ese token. El rate limiting solo habría ralentizado el rastreo, no detenido — 100 peticiones por minuto siguen siendo 144.000 registros al día.

Las lecciones se generalizan: enumera tus identificadores de objeto (pedidos, usuarios, documentos, carritos) y para cada endpoint pregunta “¿quién es dueño de este recurso y dónde se comprueba?” Si la respuesta es “el frontend solo muestra los suyos” — ese es el bug. BOLA es el #1 del OWASP API precisamente porque es invisible en el tráfico y trivial de probar: cada endpoint de objeto necesita un test que pida el recurso de otro usuario y espere un 404 o un 403.

Rate Limiting

Sin límite, cualquier endpoint es una granja de load-testing gratuita y un canal de scraping. Los tres algoritmos que realmente despliegas: token bucket (con ráfagas pero acotado — el default general), sliding window (preciso, más estricto — endpoints de pago y auth) y fixed window (el más barato, propenso a ráfagas en los bordes). En memoria vale para una instancia; en cuanto escalas horizontalmente necesitas un almacén compartido como Redis.

Token Bucket Rate Limiter

import time
from collections import defaultdict
from threading import Lock

class TokenBucketRateLimiter:
    def __init__(self, capacity: int, refill_rate: float):
        self.capacity = capacity
        self.refill_rate = refill_rate  # tokens per second
        self.buckets: dict[str, dict] = defaultdict(lambda: {
            "tokens": capacity,
            "last_refill": time.time()
        })
        self.lock = Lock()
    
    def allow_request(self, key: str) -> bool:
        with self.lock:
            bucket = self.buckets[key]
            now = time.time()
            
            # Refill tokens
            elapsed = now - bucket["last_refill"]
            bucket["tokens"] = min(
                self.capacity,
                bucket["tokens"] + elapsed * self.refill_rate
            )
            bucket["last_refill"] = now
            
            if bucket["tokens"] >= 1:
                bucket["tokens"] -= 1
                return True
            return False

# Usage: 100 requests per minute per IP
rate_limiter = TokenBucketRateLimiter(capacity=100, refill_rate=100/60)

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.middleware("http")
async def rate_limit_middleware(request: Request, call_next):
    client_ip = request.client.host
    if not rate_limiter.allow_request(client_ip):
        raise HTTPException(
            status_code=429,
            detail="Rate limit exceeded",
            headers={"Retry-After": "60"}
        )
    response = await call_next(request)
    response.headers["X-RateLimit-Limit"] = "100"
    response.headers["X-RateLimit-Remaining"] = str(int(rate_limiter.buckets[client_ip]["tokens"]))
    return response

Dos cautelas de producción: los buckets en memoria se resetean al reiniciar y no comparten estado entre réplicas — vale para un proceso único, mal para autoscaling. Y usa como clave la identidad autenticada (API key, user id) donde puedas: los límites por IP castigan a todos los usuarios tras un NAT y el atacante rota IPs igualmente.

Rate Limiter Distribuido con Redis

import redis
import time

class RedisRateLimiter:
    def __init__(self, redis_client: redis.Redis):
        self.redis = redis_client
    
    def sliding_window(self, key: str, limit: int, window: int) -> bool:
        """Sliding window rate limiter using Redis sorted sets."""
        now = time.time()
        window_start = now - window
        
        pipe = self.redis.pipeline()
        # Remove old entries
        pipe.zremrangebyscore(key, 0, window_start)
        # Add current request
        pipe.zadd(key, {str(now): now})
        # Count current window
        pipe.zcard(key)
        # Set expiry on key
        pipe.expire(key, window)
        
        results = pipe.execute()
        count = results[2]
        
        return count <= limit

# Usage: 1000 requests per hour per API key
def check_rate_limit(api_key: str, redis_client: redis.Redis) -> bool:
    limiter = RedisRateLimiter(redis_client)
    return limiter.sliding_window(
        key=f"rate_limit:{api_key}",
        limit=1000,
        window=3600
    )

Rate Limiting por Niveles

class TieredRateLimiter:
    TIERS = {
        "free": {"limit": 100, "window": 3600},       # 100/hour
        "pro": {"limit": 10000, "window": 3600},      # 10k/hour
        "enterprise": {"limit": 100000, "window": 3600}  # 100k/hour
    }
    
    def __init__(self, redis_limiter: RedisRateLimiter):
        self.limiter = redis_limiter
    
    def check(self, api_key: str, tier: str) -> dict:
        config = self.TIERS.get(tier, self.TIERS["free"])
        allowed = self.limiter.sliding_window(
            key=f"rate_limit:{tier}:{api_key}",
            limit=config["limit"],
            window=config["window"]
        )
        
        return {
            "allowed": allowed,
            "limit": config["limit"],
            "window": config["window"],
            "tier": tier
        }

Validación de Entrada

La validación es donde el input no confiable se convierte en datos tipados y acotados. Hazla en la capa de esquema — un dict llegando a tu handler es un fallo. Pydantic v2 (los snippets de abajo usan su API: constraints de Field y field_validator, que reemplazan los deprecados constr/validator de v1) hace la frontera declarativa:

Validación por Esquema

from pydantic import BaseModel, Field, field_validator
from typing import Optional

class CreateUserRequest(BaseModel):
    username: str = Field(min_length=3, max_length=50, pattern=r'^[a-zA-Z0-9_]+$')
    email: str = Field(min_length=5, max_length=255, pattern=r'^[^@]+@[^@]+\.[^@]+$')
    password: str = Field(min_length=12, max_length=128)
    age: int = Field(ge=13, le=120)
    bio: Optional[str] = Field(default=None, max_length=500)
    
    @field_validator("password")
    @classmethod
    def validate_password_strength(cls, v: str) -> str:
        if not any(c.isupper() for c in v):
            raise ValueError("Password must contain uppercase")
        if not any(c.islower() for c in v):
            raise ValueError("Password must contain lowercase")
        if not any(c.isdigit() for c in v):
            raise ValueError("Password must contain digits")
        if not any(c in "!@#$%^&*()_+-=[]{}|;:,.<>?" for c in v):
            raise ValueError("Password must contain special characters")
        return v

@app.post("/api/users")
async def create_user(request: CreateUserRequest):
    # Pydantic validates automatically — invalid data raises 422
    user = User(
        username=request.username,
        email=request.email,
        password_hash=hash_password(request.password),
        age=request.age,
        bio=request.bio
    )
    db.add(user)
    db.commit()
    return {"id": user.id, "username": request.username}

Validación de Subida de Archivos

import magic

ALLOWED_MIME_TYPES = {
    "image/jpeg": {"jpg", "jpeg"},
    "image/png": {"png"},
    "image/webp": {"webp"},
    "application/pdf": {"pdf"},
}

MAX_FILE_SIZE = 10 * 1024 * 1024  # 10 MB

def validate_file_upload(file_bytes: bytes, filename: str) -> str:
    # Check file size
    if len(file_bytes) > MAX_FILE_SIZE:
        raise ValueError(f"File exceeds {MAX_FILE_SIZE // 1024 // 1024}MB limit")
    
    # Check file extension
    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
    
    # Detect actual MIME type from content (not from extension)
    mime = magic.from_buffer(file_bytes, mime=True)
    
    if mime not in ALLOWED_MIME_TYPES:
        raise ValueError(f"File type {mime} not allowed")
    
    if ext not in ALLOWED_MIME_TYPES[mime]:
        raise ValueError(f"Extension .{ext} does not match MIME type {mime}")
    
    # Check for embedded scripts in images
    if mime.startswith("image/"):
        if b"<script" in file_bytes.lower() or b"<?php" in file_bytes.lower():
            raise ValueError("File contains embedded scripts")
    
    return mime

@app.post("/api/upload")
async def upload_file(file: UploadFile = File(...)):
    content = await file.read()
    mime_type = validate_file_upload(content, file.filename)
    
    # Never trust the user-supplied name — generate your own
    import secrets, os
    ext = os.path.splitext(file.filename)[1].lower()
    safe_filename = f"{secrets.token_hex(8)}{ext}"
    filepath = f"/uploads/{safe_filename}"
    
    with open(filepath, "wb") as f:
        f.write(content)
    
    return {"filename": safe_filename, "mime_type": mime_type}

El patrón que importa: valida el contenido, no las afirmaciones. python-magic lee los magic bytes, así que un malware.exe renombrado photo.jpg queda cazado; generar tu propio nombre de archivo mata el path traversal (../../etc/passwd) sin lista negra. Si los archivos se sirven de vuelta, guárdalos fuera del web root o en object storage, y considera un servicio de escaneo para lo no trivial.

Configuración de CORS

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Strict CORS — only allow specific origins
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://stackpractices.com",
        "https://www.stackpractices.com",
        "https://app.stackpractices.com"
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
    allow_headers=[
        "Authorization",
        "Content-Type",
        "X-Requested-With",
        "X-CSRF-Token"
    ],
    expose_headers=["X-Request-ID", "X-RateLimit-Remaining"],
    max_age=3600  # Cache preflight for 1 hour
)

# Never use allow_origins=["*"] with allow_credentials=True
# This is a security vulnerability — browsers will reject it

CORS es un control del lado del navegador, no una guardia del servidor — impide que otros sitios web llamen a tu API con las credenciales del visitante, pero un atacante directo con curl lo ignora por completo. Errores comunes: origin comodín + credentials (los navegadores lo rechazan, pero muchos lo “arreglan” reflejando el header Origin — peor), permitir * en endpoints que aceptan cookies, y olvidar que los preflights OPTIONS saltan tu middleware de auth, así que no los bloquees.

Prevención de Inyección SQL

La inyección sobrevive porque las queries construidas con strings siguen apareciendo. La regla no ha cambiado en veinte años: los datos nunca se concatenan en SQL — entran como parámetros, siempre.

# VULNERABLE: String concatenation
def get_user_vulnerable(name: str):
    query = f"SELECT * FROM users WHERE name = '{name}'"
    # Attack: name = "'; DROP TABLE users; --"
    return db.execute(query)

# SAFE: Parameterized queries
def get_user_safe(name: str):
    query = "SELECT * FROM users WHERE name = :name"
    return db.execute(query, {"name": name})

# SAFE: ORM with parameterized queries
def get_user_orm(name: str):
    return db.query(User).filter(User.name == name).first()

# SAFE: SQLAlchemy with explicit parameters
from sqlalchemy import text

def search_users(search_term: str):
    query = text("""
        SELECT id, username, email 
        FROM users 
        WHERE username ILIKE :pattern 
        ORDER BY created_at DESC
        LIMIT 50
    """)
    return db.execute(query, {"pattern": f"%{search_term}%"})

# SAFE: Input sanitization for dynamic queries
def safe_order_by(column: str, allowed_columns: set) -> str:
    """Validate column name for ORDER BY clause."""
    if column not in allowed_columns:
        raise ValueError(f"Invalid sort column: {column}")
    return column

# Usage
allowed = {"username", "email", "created_at", "updated_at"}
sort_column = safe_order_by(request.args.get("sort", "created_at"), allowed)
query = f"SELECT * FROM users ORDER BY {sort_column} DESC"

El último patrón importa más de lo que parece: los parámetros no pueden enlazar identificadores (nombres de columna, tabla, dirección de orden), así que donde te tiente interpolarlos — ORDER BY, filtros dinámicos — hace falta una lista blanca explícita, igual que safe_order_by arriba. El ORM tampoco te salva aquí; getattr(User, user_column) en un filter es primo de mass assignment.

Protección contra Mass Assignment

Mass assignment — aceptar los campos que mande el cliente y escribirlos en el modelo — es el #3 del OWASP API y el bug de escalada de privilegios más fácil de embarcar: un "role": "admin" extra en el JSON y el usuario se edita su propio rol.

# VULNERABLE: Mass assignment
@app.put("/api/users/{user_id}")
async def update_user(user_id: int, body: dict = Body(...)):
    user = db.query(User).filter(User.id == user_id).first()
    for key, value in body.items():
        setattr(user, key, value)  # Attacker can set role=admin!
    db.commit()
    return user

# SAFE: Explicit field mapping with Pydantic
class UpdateUserRequest(BaseModel):
    username: Optional[str] = Field(default=None, min_length=3, max_length=50)
    email: Optional[str] = Field(default=None, max_length=255)
    bio: Optional[str] = Field(default=None, max_length=500)
    # Note: 'role', 'is_admin', 'password_hash' are NOT included

@app.put("/api/users/{user_id}")
async def update_user(
    user_id: int,
    request: UpdateUserRequest,
    current_user: User = Depends(get_current_user)
):
    if current_user.id != user_id and current_user.role != "admin":
        raise HTTPException(403, "Access denied")
    
    user = db.query(User).filter(User.id == user_id).first()
    
    # Only update allowed fields that were actually sent
    update_data = request.model_dump(exclude_unset=True)
    for key, value in update_data.items():
        setattr(user, key, value)
    
    db.commit()
    return {"id": user.id, "username": user.username}

model_dump(exclude_unset=True) es la segunda mitad del patrón: incluye solo los campos que el cliente envió explícitamente, así que una actualización parcial no anula campos omitidos. El propio esquema es la lista blanca — los campos extra del payload se rechazan o ignoran antes de llegar a setattr.

Seguridad en el API Gateway

Un middleware de gateway es el sitio natural para imponer las capas externas — tamaño de petición, API keys, rate limits, security headers — una sola vez, en vez de por endpoint. Fíjate en la firma: @app.middleware("http") decora una función que toma (request, call_next). (Para una clase middleware ASGI pura la firma es __call__(scope, receive, send) — no son intercambiables.)

import uuid
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.middleware("http")
async def api_gateway_middleware(request: Request, call_next):
    # 1. Request size limit
    content_length = request.headers.get("content-length")
    if content_length and int(content_length) > 10 * 1024 * 1024:  # 10MB
        return JSONResponse(status_code=413, content={"detail": "Request too large"})
    
    # 2. API key validation (skip public endpoints)
    if request.url.path.startswith("/api/"):
        api_key = request.headers.get("X-API-Key")
        if not api_key:
            return JSONResponse(status_code=401, content={"detail": "Missing API key"})
        
        key_info = validate_api_key(api_key)
        if not key_info:
            return JSONResponse(status_code=401, content={"detail": "Invalid API key"})
        
        # 3. Rate limiting
        rate_check = check_rate_limit(api_key, key_info["tier"])
        if not rate_check["allowed"]:
            return JSONResponse(
                status_code=429,
                content={"detail": "Rate limit exceeded"},
                headers={
                    "Retry-After": str(rate_check["window"]),
                    "X-RateLimit-Limit": str(rate_check["limit"])
                }
            )
    
    # 4. Request ID for tracing
    request_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())
    request.state.request_id = request_id
    
    # 5. Process request
    response = await call_next(request)
    
    # 6. Add security headers
    response.headers["X-Request-ID"] = request_id
    response.headers["X-Content-Type-Options"] = "nosniff"
    response.headers["X-Frame-Options"] = "DENY"
    response.headers["Strict-Transport-Security"] = "max-age=31536000"
    
    # 7. Remove sensitive headers from response
    response.headers.pop("Server", None)
    response.headers.pop("X-Powered-By", None)
    
    return response

def validate_api_key(api_key: str) -> dict | None:
    # Look up API key in database — compare hashes, never plaintext
    key_record = db.query(APIKey).filter(
        APIKey.key_hash == hash_api_key(api_key),
        APIKey.is_active == True
    ).first()
    if key_record:
        return {"tier": key_record.tier, "user_id": key_record.user_id}
    return None

Dos detalles que conviene copiar: guarda las API keys como hashes en la base de datos — una tabla filtrada no filtra nada usable — y devuelve un 401 genérico tanto para clave ausente como inválida, para que no se pueda sondear su existencia. Si tu API es pública, considera hacer todo esto en un gateway real (Kong, Envoy, NGINX) en vez del middleware de la app, por las razones del patrón gatekeeper.

Seguridad en Paginación

La paginación sin tope es un DoS autoinfligido: ?size=1000000 es una petición legal que devuelve tu tabla entera por llamada.

# VULNERABLE: No limit on page size
@app.get("/api/users")
async def list_users(page: int = 1, size: int = 1000):
    # Attacker can request size=1000000 and overwhelm the server
    offset = (page - 1) * size
    return db.query(User).offset(offset).limit(size).all()

# SAFE: Enforce maximum page size
MAX_PAGE_SIZE = 100

@app.get("/api/users")
async def list_users(
    page: int = Query(1, ge=1),
    size: int = Query(20, ge=1, le=MAX_PAGE_SIZE)
):
    offset = (page - 1) * size
    users = db.query(User).offset(offset).limit(size).all()
    total = db.query(User).count()
    
    return {
        "data": [user_to_dict(u) for u in users],
        "pagination": {
            "page": page,
            "size": size,
            "total": total,
            "total_pages": (total + size - 1) // size
        }
    }

# SAFE: Cursor-based pagination (better for large datasets)
import base64
from fastapi import HTTPException

@app.get("/api/users/cursor")
async def list_users_cursor(
    cursor: str | None = Query(default=None),
    size: int = Query(20, ge=1, le=MAX_PAGE_SIZE)
):
    query = db.query(User).order_by(User.id.desc())
    
    if cursor:
        try:
            last_id = int(base64.b64decode(cursor).decode())
        except Exception:
            raise HTTPException(400, "Invalid cursor")
        query = query.filter(User.id < last_id)
    
    users = query.limit(size + 1).all()  # Fetch one extra to check has_more
    has_more = len(users) > size
    users = users[:size]
    
    next_cursor = None
    if has_more and users:
        next_cursor = base64.b64encode(str(users[-1].id).encode()).decode()
    
    return {
        "data": [user_to_dict(u) for u in users],
        "next_cursor": next_cursor,
        "has_more": has_more
    }

Dos arreglos sobre la versión ingenua: el decode del cursor va envuelto para que un cursor malformado devuelva 400 en vez de reventar la petición, y los cursores codifican una posición, no un permiso — los IDs en base64 son trivialmente falsificables, lo cual va bien siempre que cada fila siga pasando autorización. Si el cursor gobierna algo sensible, fírmalo (HMAC) en vez de codificarlo.

Audit Logging

Cuando ocurre una brecha, la primera pregunta es “¿qué tocaron?” — y la mayoría de equipos descubre que no puede responder. Registra los eventos relevantes de seguridad con contexto suficiente para reconstruir, nunca con secretos que agraven la fuga: loguea el prefijo de la API key, nunca la clave; el user id, nunca el token.

import json
import logging
import time
from datetime import datetime

class AuditLogger:
    def __init__(self):
        self.logger = logging.getLogger("audit")
        handler = logging.StreamHandler()
        handler.setFormatter(logging.Formatter('%(message)s'))
        self.logger.addHandler(handler)
        self.logger.setLevel(logging.INFO)
    
    def log_api_call(self, request: Request, response, user_id: str | None):
        self.logger.info(json.dumps({
            "timestamp": datetime.now().isoformat(),
            "request_id": getattr(request.state, "request_id", None),
            "method": request.method,
            "path": request.url.path,
            "status_code": response.status_code,
            "user_id": user_id,
            "ip": request.client.host,
            "user_agent": request.headers.get("user-agent", ""),
            "api_key": request.headers.get("x-api-key", "")[:8] + "..." if request.headers.get("x-api-key") else None,
            "response_time_ms": getattr(request.state, "response_time", None)
        }))
    
    def log_security_event(self, event: str, details: dict):
        self.logger.warning(json.dumps({
            "timestamp": datetime.now().isoformat(),
            "event": event,
            "details": details
        }))

audit = AuditLogger()

@app.middleware("http")
async def audit_middleware(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    elapsed_ms = (time.time() - start) * 1000
    
    request.state.response_time = round(elapsed_ms, 2)
    
    # Get user from JWT if present
    user_id = None
    auth_header = request.headers.get("authorization", "")
    if auth_header.startswith("Bearer "):
        try:
            payload = jwt_service.verify_token(auth_header[7:])
            user_id = payload["sub"]
        except Exception:
            pass
    
    audit.log_api_call(request, response, user_id)
    
    # Log suspicious activity
    if response.status_code == 401:
        audit.log_security_event("auth_failure", {
            "ip": request.client.host,
            "path": request.url.path,
            "method": request.method
        })
    elif response.status_code == 403:
        audit.log_security_event("access_denied", {
            "ip": request.client.host,
            "path": request.url.path,
            "user_id": user_id
        })
    
    return response

Una ráfaga de eventos auth_failure desde una IP es tu alarma de credential stuffing; un usuario acumulando access_denied en recursos distintos es la sonda de enumeración antes de la brecha. Dirige los eventos de seguridad a algún sitio con alertas, no solo a stdout.

Tests de Seguridad de la API

Los controles que no pruebas son controles que esperas que funcionen. La buena noticia: la mayoría de los tests son pequeños, rápidos y corren en CI contra tu test client normal — las regresiones de seguridad se cazan como cualquier otro bug.

import pytest

class TestAPISecurity:
    def test_sql_injection_in_login(self, client):
        # Test SQL injection in login
        response = client.post("/api/login", json={
            "username": "admin' OR '1'='1",
            "password": "anything"
        })
        assert response.status_code == 401
        assert "token" not in response.json()
    
    def test_mass_assignment(self, client, auth_headers):
        # Test mass assignment protection
        response = client.put("/api/users/me", json={
            "username": "newname",
            "role": "admin",  # Should be ignored
            "is_admin": True   # Should be ignored
        }, headers=auth_headers)
        assert response.status_code == 200
        assert response.json()["role"] != "admin"
    
    def test_rate_limiting(self, client):
        # Test rate limiting
        for i in range(101):
            response = client.get("/api/data")
            if i < 100:
                assert response.status_code == 200
            else:
                assert response.status_code == 429
    
    def test_cors_headers(self, client):
        # Test CORS configuration
        response = client.options(
            "/api/data",
            headers={
                "Origin": "https://evil.com",
                "Access-Control-Request-Method": "GET"
            }
        )
        # Should not allow evil.com
        assert "access-control-allow-origin" not in response.headers or \
               response.headers["access-control-allow-origin"] != "https://evil.com"
    
    def test_authentication_required(self, client):
        # Test that protected endpoints require auth
        response = client.get("/api/users/me")
        assert response.status_code == 401
    
    def test_invalid_token_rejected(self, client):
        # Test invalid JWT
        response = client.get(
            "/api/users/me",
            headers={"Authorization": "Bearer invalid.token.here"}
        )
        assert response.status_code == 401
    
    def test_expired_token_rejected(self, client):
        # Test expired JWT
        expired_token = generate_expired_token()
        response = client.get(
            "/api/users/me",
            headers={"Authorization": f"Bearer {expired_token}"}
        )
        assert response.status_code == 401
    
    def test_pagination_limit_enforced(self, client, auth_headers):
        # Test that page size is capped
        response = client.get(
            "/api/users?size=10000",
            headers=auth_headers
        )
        data = response.json()
        assert len(data["data"]) <= 100  # MAX_PAGE_SIZE

Checklist de Seguridad

Checklist de Seguridad de API:

Autenticación:
  [ ] Todos los endpoints requieren autenticación (salvo los públicos)
  [ ] JWT validado (firma, expiración, issuer, audience)
  [ ] API keys hasheadas en la base de datos (nunca en claro)
  [ ] Intentos de auth fallidos registrados y monitorizados
  [ ] Expiración de tokens aplicada

Autorización:
  [ ] Control de acceso por roles en cada endpoint
  [ ] Propiedad del recurso verificada (el usuario solo accede a sus datos)
  [ ] Endpoints de admin requieren rol admin
  [ ] Mass assignment prevenido (mapeo explícito de campos)

Validación de Entrada:
  [ ] Todos los inputs validados con esquema (Pydantic, Zod, Joi)
  [ ] Subidas validadas (tipo MIME, tamaño, contenido)
  [ ] Queries SQL parametrizadas (sin concatenación de strings)
  [ ] Parámetros de URL validados
  [ ] Tamaño del body limitado

Rate Limiting:
  [ ] Rate limiting en todos los endpoints
  [ ] Límites por niveles según plan de la API
  [ ] Respuesta 429 con header Retry-After
  [ ] Rate limiting distribuido (Redis) en multi-instancia

CORS:
  [ ] Orígenes específicos permitidos (sin comodín con credentials)
  [ ] Métodos permitidos restringidos
  [ ] Headers permitidos restringidos
  [ ] Caché de preflight configurada

Logging:
  [ ] Todas las llamadas registradas con request ID
  [ ] Fallos de auth registrados
  [ ] Violaciones de acceso registradas
  [ ] Tiempos de respuesta medidos
  [ ] Datos sensibles redactados en logs

Headers:
  [ ] X-Content-Type-Options: nosniff
  [ ] X-Frame-Options: DENY
  [ ] Strict-Transport-Security
  [ ] Header Server eliminado
  [ ] X-Powered-By eliminado

Autenticación en la Práctica

Dos credenciales dominan el auth de APIs, y son complementarias, no competidoras. Las API keys son secretos opacos de larga vida para máquinas: llamadas servidor-a-servidor, service accounts, CI. Hay que tratarlas como contraseñas — generadas con 128+ bits de entropía, guardadas hasheadas (la base de datos guarda sha256(key), nunca la clave), con scope limitado a lo que el llamante necesita, y rotadas. En cuanto emites una API key, asume que acabará filtrándose por logs, un screenshot o un .env commiteado — así que haz la fuga superable: scopes, expiraciones, listas de IPs permitidas para niveles sensibles.

Los JWT son para usuarios: tokens firmados que llevan claims (sub, roles, exp) y permiten autorizar sin consultar la base de datos en cada petición. Los bordes afilados están todos en la validación — acepta solo los algoritmos que decidiste soportar (nunca alg: none, y fija RS256/HS256 en vez de negociar), verifica exp, iss y aud, y mantén tokens de vida corta con rotación de refresh. Un JWT que no puedes revocar es una contraseña que no puedes cambiar — para acciones de alto riesgo, consulta una lista de revocación o re-verifica en el servidor.

El ítem del checklist “JWT validado (firma, expiración, issuer, audience)” no es pedantería: la confusión de firma (downgrade HS256-vs-RS256) es una clase de ataque real donde la clave pública se convierte en el secreto HMAC.

Errores y Fuga de Información

Las respuestas de error son un canal de reconocimiento. Un 500 que imprime psycopg2.errors.UndefinedTable: relation "users" does not exist le dice al atacante el ORM, la base de datos y los nombres de tabla — tres piezas gratis de tu esquema. El manejo de errores en producción devuelve mensajes genéricos con ID de incidente: {"error": "internal_error", "request_id": "..."} mientras el stack trace real va a tus logs privados con el mismo ID.

Mismo principio en los fallos de validación: un 422 debe decir qué está mal en el input, no qué más existe — “username already taken” en endpoints de registro es un vector de enumeración de emails registrados (se arregla con respuestas uniformes más flujos de verificación por email). Y audita tus payloads buscando fuga de forma: si /api/users/me devuelve el objeto user completo porque la serialización era cómoda, estás filtrando password_hash, role y lo que el modelo acumule el año que viene. Los DTOs de respuesta — esquemas explícitos de salida, igual que de entrada — son el control; también son el item de revisión más barato: haz grep de tus endpoints buscando return db.query que se salte el DTO.

Versionado y Seguridad de la Deprecación

Las versiones viejas son superficie de ataque olvidada. Cuando /v1/users sigue corriendo código escrito antes de que existiera tu middleware de auth, el endurecimiento de v2 no protege a nadie — el atacante simplemente entra por /v1. Tres reglas:

  • Los endpoints versionados llevan los mismos controles que los actuales. Rate limits, auth, validación aplican por versión — nunca asumas “ya nadie usa v1” sin logs que lo prueben. La típica historia de brecha empieza con un endpoint legado anterior a la capa de seguridad.
  • La deprecación necesita un sunset, no una borrado. Publica el header de deprecación (Deprecation + Sunset RFC 8594), avisa a los consumidores, monitoriza el tráfico y luego retira. Borrar sin telemetría no te dice quién seguía dependiendo — y a menudo resucita el endpoint por presión de soporte.
  • Nunca versiones la semántica de seguridad. Si v1 y v2 difieren sobre qué significa “admin”, una de ellas está mal por definición — comparte la lógica de autorización entre versiones; solo el formato del wire y las features difieren.

Cuando mantienes versiones paralelas vivas, los tests de seguridad de arriba deberían correr contra cada versión activa, no solo la más nueva — un fix desplegado en v2 que no se backporta a v1 es documentado como brecha en espera.

Buenas Prácticas

  • Valida en la frontera con esquemas — nunca dejes que un dict crudo llegue al handler
  • Guarda API keys como hashes y rótalas; loguea solo prefijos, nunca credenciales completas
  • Usa model_dump(exclude_unset=True) en actualizaciones parciales — el esquema es la lista blanca
  • Usa identidad (API key/usuario) como clave de rate limit, no solo IP — NATs y proxies la hacen poco fiable
  • Falla cerrado: clave ausente, origen malo, body malformado devuelven error antes de la lógica
  • Devuelve payloads mínimos — si el cliente necesita 3 campos, envía 3 campos
  • Pon topes de tamaño de página en todas partes — un size sin límite es un DoS gratis
  • Quita Server/X-Powered-By y fija nosniff/DENY/HSTS en cada respuesta
  • Escribe un test de seguridad por control — corren en el mismo CI que el resto

Errores Comunes

  • CORS comodín con credentials — los navegadores lo rechazan y el “arreglo” (reflejar Origin) abre robo de sesión; enumera orígenes reales
  • Validar por extensión o tipo declarado — comprueba los magic bytes; evil.exe renombrado photo.jpg es el truco más viejo
  • Guardar API keys en claro — un volcado de tabla y todas las claves quedan vivas; hashéalas como contraseñas
  • Confiar en el user_id de la petición — deriva la identidad del token verificado, no del body o la ruta
  • Dejar entrar dicts crudos a handlers de update — mass assignment; la lista blanca vive en el esquema de petición
  • Loguear tokens/claves completas — tu agregador de logs se convierte en el almacén de credenciales; solo prefijos
  • Pensar que CORS es un firewall — es una regla del navegador para scripts cross-site; a curl le da igual

See Also

Lecturas Recomendadas

Preguntas frecuentes

¿Cómo elijo entre API keys y JWT para autenticación?

Usa API keys para comunicación servidor-a-servidor y acceso de larga duración (service accounts, pipelines CI/CD). Usa JWT para aplicaciones de cara al usuario donde los tokens expiran y se refrescan. Las API keys son más simples pero no pueden codificar claims ni expirar solas. Los JWT llevan contexto de usuario (roles, permisos) y expiran, pero requieren gestión de refresh tokens. Para APIs públicas, ofrece ambos: API keys para desarrolladores y OAuth2/JWT para auth de usuarios finales.

¿Cuál es el mejor algoritmo de rate limiting?

Token bucket es el más flexible — permite ráfagas hasta la capacidad del bucket manteniendo una tasa media. Sliding window da el conteo más preciso pero usa más memoria. Fixed window es el más simple pero permite ráfagas en los bordes de ventana. Usa token bucket para APIs de cara al usuario (permite ráfagas cortas), sliding window para límites estrictos (APIs de pago) y Redis para rate limiting distribuido entre instancias.

¿Cómo prevengo vulnerabilidades de mass assignment?

Nunca uses setattr u Object.assign con input crudo del usuario. Define esquemas de petición explícitos (Pydantic, DTOs) que solo incluyan campos que el usuario puede actualizar. Excluye campos sensibles como role, is_admin, password_hash, balance de los esquemas de update. Usa model_dump(exclude_unset=True) para actualizar solo campos explícitamente enviados. Prueba mass assignment enviando campos extra en las peticiones y verificando que se ignoran.

¿Debería usar paginación por cursor o por offset?

Usa paginación por cursor para datasets grandes y feeds en tiempo real. Es más rápida (sin query COUNT) y evita saltarse items cuando se insertan datos nuevos. Usa offset para datasets pequeños donde necesites conteo total de páginas y acceso aleatorio. Pon siempre un tope de tamaño de página (p. ej. 100 items) independientemente del método para prevenir denegación de servicio.

¿Cómo aseguro las subidas de archivos?

Valida el tipo MIME real inspeccionando el contenido (python-magic, comando file), no la extensión del archivo. Limita el tamaño (p. ej. 10MB). Guarda las subidas fuera del web root o en object storage (S3, GCS). Genera nombres nuevos — nunca uses el nombre del usuario. Escanea scripts embebidos en imágenes. Usa un servicio dedicado si procesas archivos (antivirus, resize). Pon Content-Disposition: attachment en la descarga para evitar ejecución inline.

¿Qué security headers debería devolver mi API?

Pon X-Content-Type-Options: nosniff para evitar MIME sniffing. Pon Strict-Transport-Security para forzar HTTPS. Pon X-Frame-Options: DENY si tu API sirve HTML. Quita Server y X-Powered-By para evitar fingerprinting. Añade Cache-Control: no-store en respuestas autenticadas. Añade X-Request-ID para trazado. No pongas Access-Control-Allow-Origin: * con credentials.