Define defensas contra CSRF para cambios de estado autenticados en navegador usando diseño de solicitudes same-site, tokens o encabezados validados por el servidor, verificaciones de origen, métodos seguros y pruebas para casos límite de inicio de sesión y cross-origin.
Estado del paquete: contexto de referencia listo para revisión humana. El contrato y los escenarios de prueba están completos, pero no se afirma que una implementación adoptante los haya superado.
Decisión
Para mutaciones autenticadas por cookie en navegador, se requiere una señal anti-CSRF verificable por el servidor que un atacante no pueda enviar cross-site. Usar cookies SameSite y verificaciones de Origin como defensa en profundidad, no como el único control universal.
Alcance
- Clases de solicitudes protegidas, atributos de cookies, patrón token/encabezado, validación de origen, CORS, CSRF en inicio de sesión, excepciones API, rotación y pruebas.
- Solicitudes de navegador donde las credenciales ambientales autentican al usuario.
- Evidencia de configuración de framework y proxy.
Fuera de este bloque
- Prevención de cross-site scripting; XSS puede derrotar muchos controles CSRF y requiere defensas separadas.
- Añadir tokens CSRF a clientes bearer-token no navegador que no usan credenciales ambientales.
Contrato
- Los métodos seguros no cambian estado; cada método inseguro autenticado por cookie usa el control token/encabezado seleccionado.
- El token está ligado a una sesión o criptográficamente asociado a ella, validado en servidor, es impredecible y no aparece en logs ni URLs.
- La validación de Origin o Referer usa un origen objetivo configurado estrictamente y reconstrucción confiable por proxy.
- Las cookies de sesión usan Secure, HttpOnly donde corresponde, y una política SameSite explícita compatible con flujos reales de inicio de sesión.
- CORS nunca combina orígenes arbitrarios con solicitudes con credenciales, y APIs con encabezados personalizados permiten solo orígenes confiables.
- Inicio de sesión, cierre de sesión, carga, GraphQL, sobreescritura de método y variaciones de tipo de contenido están incluidas en inventario de endpoints y pruebas.
Guía de implementación
- Preferir implementación de token sincronizador mantenido por framework o doble envío firmado sobre criptografía personalizada.
- Rechazar tipos de contenido cross-site simples para endpoints de mutación JSON y requerir un encabezado personalizado.
- Inventariar mutaciones desde metadatos de rutas en CI para detectar adiciones no protegidas.
- Rotar tokens ligados a sesión en cambios de autenticación manejando deliberadamente múltiples pestañas.
Manejo de fallos y salvaguardas
- Señales faltantes o inválidas deniegan la mutación con respuesta genérica y emiten telemetría de seguridad con limitación de tasa.
- Si Origin está ausente, aplicar la política explícita de respaldo; nunca tratar un substring arbitrario de Referer como coincidencia.
- Si un callback de inicio de sesión federado necesita cookies cross-site, aislarlo y validarlo con estado/nonce en lugar de debilitar todos los endpoints.
Verificación y operaciones
- Medir denegaciones CSRF por endpoint/razón, Origin faltante, desajuste de token y casos de soporte falso positivo sin registrar tokens.
- Ejecutar pruebas de navegador cross-origin contra configuraciones de cookies, proxy y CORS similares a producción.
- Revisar inventario de rutas cada vez que cambie el transporte de autenticación.
Los ejemplos con apariencia ejecutable en este paquete son fixtures y contratos de aceptación. Ejecutar
python tools/validate.py desde la raíz de la colección para verificar estructura y metadatos del paquete; luego
implementar y ejecutar los escenarios en el repositorio objetivo.
Suposiciones para adopción
- Nombres y valores numéricos en
example.yamlson un perfil de adopción, no valores predeterminados universales. - El equipo adoptante debe mapear actores, clases de datos, vocabulario de errores y propiedad a su sistema.