Validación de esquema, entrada, salida y enumeración

1Por qué importa

La validación de entrada es la frontera de confianza de una API. Todo lo que la cruza sin comprobarse se convierte en un supuesto que la lógica de negocio da por cierto: que monto es un número, que usuario es una cadena, que no llegan campos que nadie esperaba. Cada uno de esos supuestos, si no se verifica en la puerta, es una vía para que un cuerpo inesperado provoque un comportamiento inesperado: un error 500 que filtra una traza, una operación que se ejecuta con un tipo que rompe una comprobación posterior, o un campo de más que acaba en la base de datos.

La salida importa por la razón simétrica. Una API que devuelve el registro entero "porque es cómodo" filtra los campos internos que ese registro arrastra: el hash de la contraseña, el identificador interno, marcas de estado que revelan cómo funciona el sistema por dentro. El cliente no pidió esos campos y no debería verlos, pero ahí están, en cada respuesta, esperando a que alguien los lea. Y la enumeración es la más sutil de las tres: no filtra un dato directamente, filtra la existencia de un dato, que muchas veces es justo lo que el atacante necesita para el siguiente paso.

2Conceptos

3Explicación profunda

Conviene separar dos cosas que se llaman igual. Validar la sintaxis es comprobar que el cuerpo es JSON bien formado; un cuerpo truncado o con una coma de más se rechaza con 400 antes de mirar nada. Validar el esquema es lo que viene después: el JSON parsea, pero ¿tiene los campos que este endpoint necesita, del tipo correcto, sin campos desconocidos? La mayoría de las APIs hacen lo primero de gratis, porque el parser falla solo, y se saltan lo segundo, que es justo donde vive la seguridad. Un cuerpo {"monto": "mucho"} es JSON perfectamente válido y a la vez completamente inválido para una transferencia.

Un esquema se declara, no se programa a mano. En vez de una cascada de if, se describe la forma válida —monto es un número positivo, usuario es una cadena de 3 a 32 caracteres, no se admiten campos adicionales— y una librería la aplica. La ventaja no es solo escribir menos: es que la validación es completa por defecto. Una cascada de if olvida casos; un esquema con additionalProperties: false rechaza cualquier campo que no haya declarado, incluido el que un atacante inventará mañana. Es la misma idea que la lista de campos permitidos de la lección anterior, ahora sobre la forma entera del cuerpo.

La validación de entrada tiene que ocurrir en la puerta, antes de la lógica de negocio, y tiene que ser fallo seguro: si algo no encaja, se rechaza y no se toca el estado. El error clásico es validar a medias y avanzar: comprobar que usuario existe pero no su tipo, empezar a operar, y fallar a la mitad dejando el sistema en un estado intermedio. Una petición inválida no debe producir ningún efecto lateral. O pasa entera la validación, o no pasa nada.

La salida es la otra mitad. Devolver el objeto de dominio directamente es la causa más común de fuga de datos por API: ese objeto arrastra campos que existen por razones internas y que nunca debieron viajar al cliente. La defensa es un modelo de salida explícito —un DTO de respuesta, una serialización con lista de campos públicos— de modo que añadir un campo interno al modelo de dominio no lo publique por accidente. Igual que en la entrada, lo seguro es enumerar lo que sale, no lo que se oculta.

La enumeración es más fina porque no filtra el dato, filtra su existencia. Si /login responde 404 "usuario no existe" y 401 "clave incorrecta", un atacante prueba nombres y, sin acertar ni una contraseña, obtiene la lista exacta de usuarios reales. Lo mismo con /perfil/<usuario> que devuelve 200 o 404, o con un registro que responde distinto según si el correo ya está dado de alta. La existencia de una cuenta es un dato, y a menudo el que abre el siguiente ataque: relleno de credenciales dirigido, phishing a usuarios confirmados, o simplemente saber a quién atacar. La defensa es hacer las respuestas indistinguibles: el mismo código, el mismo mensaje, y —cuando importa— el mismo tiempo de respuesta, porque un login que tarda más cuando el usuario existe es un oráculo temporal.

4Ejemplo sencillo

# El portero de un edificio

VALIDACION DE SINTAXIS
    ¿traes un papel? si no, no pasas. (¿es JSON?)

VALIDACION DE ESQUEMA
    ¿el papel es el formulario correcto, relleno, sin
    hojas de mas pegadas detras? (¿tiene la forma valida?)

# El portero que enumera sin querer

Preguntas por "Ana Torres, 4o B".
  - "aqui no vive nadie con ese nombre"   -> no existe
  - "vive aqui pero no te dejo subir"     -> existe

Sin subir a ningun piso, ya sabes quien vive en el
edificio: el portero te lo confirmo con dos respuestas
distintas. La respuesta correcta es la misma para los
dos casos: "no puedo darte esa informacion".

5Ejemplo técnico

El laboratorio deja ver los tres fallos con tres peticiones. Míralos como un mapa de lo que la API acepta de más y devuelve de más:

Escrito como riesgo con actor, vía, activo y consecuencia: "Cualquiera puede enumerar la lista completa de usuarios reales comparando los códigos de respuesta de /perfil y /login, y leer la clave de cualquier usuario en la salida de /perfil, lo que convierte una API de consulta en un directorio de credenciales."

6Diagrama

flowchart LR
    P[petición · cuerpo hostil] --> V[validar esquema]
    V -->|no encaja| E[400 uniforme]
    V -->|encaja| L[lógica]
    L --> S[filtrar salida · solo campos públicos]
    S --> O[respuesta sin clave ni id interno]

7Código

El registro del laboratorio no valida tipos y devuelve el registro entero. La validación de esquema y el filtro de salida se pueden escribir a mano y quedan claros:

# Validación de esquema en la puerta: tipos, obligatoriedad, nada de más
PUBLICOS = ("usuario", "rol")   # lo unico que puede SALIR

def validar_registro(cuerpo):
    if not isinstance(cuerpo, dict):
        return "el cuerpo debe ser un objeto"
    permitidos = {"usuario", "clave"}
    extra = set(cuerpo) - permitidos
    if extra:
        return "campos no permitidos"          # additionalProperties: false
    u, c = cuerpo.get("usuario"), cuerpo.get("clave")
    if not isinstance(u, str) or not (3 <= len(u) <= 32):
        return "usuario invalido"
    if not isinstance(c, str) or len(c) < 8:
        return "clave invalida"
    return None                            # None = valido

def solo_publicos(registro):
    return {k: registro[k] for k in PUBLICOS if k in registro}

Y la corrección de la enumeración: un cliente que no es dueño del perfil recibe siempre la misma respuesta, exista el usuario o no. Solo el dueño (probado por el token) obtiene el 200:

# Respuesta uniforme: no confirmar la existencia a quien no es dueño
def perfil(nombre, quien_llama):
    if nombre != quien_llama:
        # mismo codigo y mensaje exista o no: sin oraculo
        return 404, {"error": "no encontrado"}
    registro = USUARIOS.get(nombre)
    if registro is None:
        return 404, {"error": "no encontrado"}
    return 200, solo_publicos(registro)   # nunca la clave

La clave ya no aparece en ninguna respuesta, y "no existe" y "no es tuyo" dan la misma salida. Un atacante que pruebe nombres no aprende nada.

8Qué puede salir mal

9Cómo lo abusaría un atacante

10Cómo defenderlo

11Laboratorio

12Ejercicios

# tras reconstruir, esto no debe imprimir nada
curl -s http://localhost:8096/perfil/ana | grep -i clave \
  && echo "FALLA: aun filtra la clave" || echo "OK: sin clave"

# dentro del cliente del lab
for n in ana beto zzz tesoreria nadie; do
  code=$(curl -s -o /dev/null -w "%{http_code}" \
    -X POST http://api:8000/login -H 'Content-Type: application/json' \
    -d "{\"usuario\":\"$n\",\"clave\":\"x\"}")
  echo "$n -> $code"
done

13Preguntas de comprensión

14Reto adicional

15Resumen

16Mis notas

17Recursos