Aseguramiento de API

Adjunta un documento OpenAPI a un caso de prueba y cada ejecución que lo use se convierte en evidencia de contrato. Autonomy atribuye el tráfico que el recorrido produjo a las operaciones que documentaste, valida las respuestas contra el esquema y deriva un veredicto para la ejecución.

El objetivo es la separación de responsabilidades. Una aserción generada por un modelo dice "la respuesta parecía correcta". Una comprobación de contrato dice "esta respuesta viola el esquema que publicaste" — y ese veredicto no puede ser anulado por un modelo.

Revisiones de contrato

Un documento OpenAPI 3 o Swagger 2 aceptado — JSON o YAML — se compila en una revisión de contrato: un artefacto canónico y determinista con las referencias locales resueltas, los ejemplos eliminados, las operaciones normalizadas y el conjunto hasheado.

Las revisiones son inmutables y deduplicadas por digest:

• Un caso de prueba enlaza a una revisión.
• Una ejecución captura la revisión que usó.
• Reimportar un documento modificado crea una nueva revisión. Nunca muta la anterior ni reinterpreta una ejecución histórica.

Esa inmutabilidad es lo que hace que la evidencia sea defendible seis meses después. El veredicto de la ejecución del trimestre pasado sigue refiriéndose al contrato tal como existía ese día.

La compilación es estricta con las referencias. Los valores $ref locales se resuelven; las referencias externas, de archivos hermanos y colgantes se rechazan directamente en lugar de debilitarse silenciosamente. Los esquemas recursivos o de profundidad limitada se marcan como tales, y la validación los reporta como indeterminados — una rama sin resolver nunca puede reportarse como aprobada.

Adjuntar un contrato

Sube el documento como adjunto cuando crees un caso de prueba con Describe the flow — el selector de archivos acepta OpenAPI / Swagger (.yaml, .json). Se escanea de seguridad como cualquier otra subida, se compila y la revisión resultante se vincula al caso.

Dos cosas se derivan de tener un contrato adjunto:

• Autonomy puede redactar aserciones de red junto con los pasos de UI, porque sabe lo que la API debe hacer.
• Cada ejecución de ese caso produce un informe de aseguramiento.

Qué deriva una ejecución

Cuando una ejecución alcanza un estado terminal, un paso de aseguramiento idempotente produce:

• Cobertura de operaciones — cuántas operaciones documentadas ejercitó realmente el recorrido, y cuáles nunca tocó.
• Deriva, en ambas direcciones — tráfico que no coincide con ninguna operación documentada, y operaciones documentadas que nunca aparecen en el tráfico.
• Hallazgos de contrato — violaciones deterministas de estado, content-type, cabeceras requeridas y esquema de respuesta.
• Documentos de OpenAPI Overlay — parches de solo revisión y sin valores que describen el cambio que la evidencia implica, vinculados al digest de origen y descargables desde la ejecución.
• Líneas base de forma de respuesta y latencia, con deltas respecto a ejecuciones anteriores.
• Un veredicto de puerta: passing, failed o indeterminate, con razones explícitas.

El espacio de evidencia de la ejecución muestra esto como una fila de datos: el estado de la puerta, n/m operations observed, fallos de contrato e indeterminados, y conteos de hallazgos desglosados por aislamiento, multicanal y sondeos de fuzz. Los parches de overlay inferidos se listan con su justificación y pueden descargarse como JSON.

indeterminate es una respuesta real, no un fallo suave. Significa que la evidencia no pudo probar el contrato en ninguna dirección — una rama de esquema sin resolver, o captura de red que la plataforma no pudo observar de forma fiable. Trátalo como "desconocido", no como "correcto".

Seguridad de la evidencia

El tráfico en tiempo de ejecución contiene credenciales, datos personales e identificadores de tenant, por lo que las observaciones son estructurales por diseño. Una observación registra el método, la forma canónica de la ruta, los nombres de los parámetros de consulta y cabeceras, el estado, el tipo de contenido, tiempos y tamaños acotados, huellas de forma JSON, la identidad verificada de la operación y códigos fijos de problemas de validación.

Nunca registra un nombre de host, una ruta o valor de consulta sin procesar, un valor de cabecera, una cookie, un cuerpo, una muestra de esquema, una credencial ni un dato personal. La captura sin procesar permanece dentro del proceso del runner y está acotada allí. Ninguna petición de cliente se reenvía jamás.

Credenciales y sondeos multi-identidad

Los planes almacenan referencias a credenciales, nunca valores. Un perfil obtiene una credencial de una variable de entorno del runner o de un valor extraído anteriormente en la misma ejecución, y los valores sensibles de los pasos usan marcadores explícitos como {{env.API_TOKEN}}. El runner los resuelve dentro de su límite de despacho — los valores resueltos nunca entran en el contexto del modelo, las trazas, las observaciones ni los argumentos de funciones del backend.

Esto es lo que hace posibles los sondeos de autorización. Un sondeo BOLA/IDOR debe referenciar un paso mutante anterior que creó un recurso, usar dos perfiles de identidad distintos, y demostrar antes del despacho que los dos principales genuinamente difieren. Si no puede demostrarlo — tokens opacos, claims faltantes, principales iguales — el sondeo reporta indeterminado en lugar de declarar un aprobado.

En pull requests

Cuando un caso de prueba tiene un contrato adjunto, el resultado de aseguramiento se añade al comentario de pull request de Autonomy junto con la matriz de ejecución, y se integra en la conclusión del check run. Consulta la GitHub App.

Solución de problemas

La cobertura es cero

El recorrido no produjo tráfico que Autonomy pudiera atribuir. Confirma que la ejecución usó una plataforma con captura de red soportada y que las rutas de servidor documentadas coinciden con el objetivo que la ejecución realmente alcanzó.

Todo es indeterminado

Normalmente un esquema irresoluble. Comprueba que el compilador no rechazó nada en la importación y busca definiciones recursivas o de profundidad limitada en las operaciones involucradas.

El contrato cambió pero las ejecuciones siguen citando el anterior

Las revisiones son inmutables por diseño. Reimporta el documento para crear una nueva revisión y vincula el caso de prueba a ella; las ejecuciones históricas seguirán citando la revisión con la que se ejecutaron.