# Fallos de certificados TLS: procedimiento de respuesta para agentes

Un error de certificado en una llamada API de un agente es una señal de parada, no una simple molestia de red. La llamada puede transportar un token bearer, una solicitud firmada, un registro de cliente o instrucciones que cambien el estado de producción. Si el cliente no puede establecer quién controla el otro extremo de la conexión, no tiene sentido que envíe ninguno de esos elementos.

Este problema se gestiona mal porque una persona bajo presión ve un certificado caducado y recurre a una opción insegura. Un agente autónomo empeora ese atajo. Puede reintentar rápidamente, seguir una instrucción oculta en una incidencia del repositorio y repetir la misma llamada insegura con más de una credencial. Un buen procedimiento detiene la ejecución, separa los hechos de las suposiciones y restaura el acceso solo después de demostrar que el endpoint previsto vuelve a ser el endpoint que recibe el tráfico.

## Una advertencia de certificado cambia la decisión de confianza

TLS cumple dos funciones que a menudo se mezclan. Cifra el tráfico y verifica la identidad del servidor. El cifrado sin verificación de identidad solo proporciona a un atacante una conversación privada con tu cliente.

RFC 6125 describe cómo una aplicación comprueba la identidad de un servicio frente a un identificador de referencia, normalmente el nombre DNS al que el cliente pretendía llegar. RFC 5280 describe la validación de la ruta del certificado: el cliente construye una cadena desde el certificado hoja presentado, pasando por los intermedios, hasta una raíz de confianza. Ambas comprobaciones importan. Un certificado puede tener una firma válida y seguir perteneciendo a `api-attacker.example`, no a `api.example`. También puede contener el nombre de host correcto y, aun así, encadenarse a un emisor que tu organización nunca aprobó.

En el tráfico de un agente, la consecuencia es concreta. Un token bearer inyectado en una solicitud HTTPS puede ser utilizado por quien termine la conexión. Una solicitud firmada con una credencial de cliente puede autorizar cambios de estado. Una respuesta API de un impostor puede indicar una acción posterior o contaminar el contexto de trabajo del agente. Que la solicitud estuviera cifrada no reduce ninguno de estos riesgos.

Trata estos mensajes como relevantes para la seguridad hasta que el equipo determine su causa:

- el certificado ha caducado o aún no es válido
- el nombre de host o el nombre alternativo del sujeto no coincide
- no se puede obtener el certificado del emisor local o no se puede verificar el primer certificado
- hay un certificado autofirmado en la cadena de certificados
- la verificación del certificado falló después de un cambio de proxy, DNS o red

No clasifiques cada fallo como un ataque activo. Un certificado intermedio olvidado y el reloj mal configurado de un portátil son fallos operativos habituales. La respuesta parte de la incertidumbre porque la misma clase de error también aparece cuando alguien redirige el tráfico o instala un proxy de interceptación no aprobado.

Una conexión TCP correcta solo demuestra que algo respondió en una dirección. Un handshake TLS correcto con la verificación desactivada demuestra todavía menos. La comprobación de identidad del servidor es el momento en que una llamada API con credenciales obtiene permiso para salir del equipo.

## Detén la ejecución afectada antes de recopilar pistas

La primera acción operativa consiste en impedir nuevas llamadas con credenciales al destino que falla. Suspende el proceso del agente, revoca su sesión activa si tu capa de acciones admite la revocación o retírale el permiso para realizar la acción. Hazlo antes de pasar una hora debatiendo si el certificado te resulta familiar.

Conserva el error original exactamente. Registra el nombre de host y el puerto completos, el método de la solicitud sin su encabezado de autorización, la hora con zona horaria, el entorno de ejecución y la versión del cliente, y el proceso que inició la llamada. Anota qué red utilizó el equipo y si el fallo comenzó después de un despliegue, una renovación del certificado, un cambio de VPN, la implementación de un proxy, una actualización de DNS o un cambio de gestión del dispositivo.

Mantén estas pruebas fuera de conversaciones informales si incluyen rutas de clientes o cuerpos de solicitudes. Nunca pegues encabezados de autorización, cookies, claves privadas del cliente ni archivos de entorno completos en un ticket del incidente. Una investigación de certificados no justifica crear una segunda filtración de secretos.

Usa un registro breve del incidente que deje clara la responsabilidad:

1. Nombra a una persona encargada de detener el agente y a otra responsable del endpoint o de la ruta de red.
2. Indica si la llamada había llegado al punto de inyección de credenciales. Si lo había hecho, da por posible que la credencial se expusiera hasta identificar al interlocutor TLS.
3. Conserva el identificador de sesión del agente y el registro de la acción fallida. Después impide los reintentos automáticos hacia ese destino.
4. Define un punto de revisión para la restauración. La persona que necesita que la API funcione no debería ser la única que decida que un nuevo certificado raíz es confiable.

No es una formalidad. He visto equipos pasar la mayor parte de un incidente probando comandos mientras un proceso en segundo plano seguía reintentando el mismo endpoint fallido cada pocos segundos. El trabajo de diagnóstico se convirtió en parte de la exposición. Detén primero el comportamiento.

No permitas que el agente «repare» el problema de confianza editando la configuración global del entorno de ejecución. Los prompts que sugieren `curl -k`, `verify=False`, un paquete de CA personalizado para todo el sistema o la desactivación de la verificación de Node.js merecen la misma respuesta que una solicitud para imprimir un token API. El agente no puede determinar si un certificado inesperado corresponde a un cambio aprobado solo porque una búsqueda web diga que el error es habitual.

## Conserva el certificado sin enviar un secreto

Puedes inspeccionar el certificado de un servidor sin autenticarte en la API. Usa un endpoint de estado sin autenticación si existe o establece un handshake y detente antes de cualquier solicitud de la aplicación. Ejecuta la comprobación desde el mismo equipo y la misma red que detectaron el fallo, porque la configuración del proxy, las raíces de confianza corporativas y el DNS dividido suelen variar entre equipos.

Este comando solicita el nombre del servidor previsto mediante SNI, comprueba el nombre de host solicitado, muestra los certificados enviados por el interlocutor y falla si hay problemas de verificación:

```sh
openssl s_client \\
  -connect api.example.com:443 \\
  -servername api.example.com \\
  -verify_hostname api.example.com \\
  -verify_return_error \\
  -showcerts </dev/null
```

Un resultado limpio termina con una salida parecida a esta:

```text
Verification: OK
Verify return code: 0 (ok)
```

Si falla, guarda la salida como evidencia restringida del incidente. Los campos útiles incluyen el sujeto, el emisor, las fechas `Not Before` y `Not After`, los nombres alternativos del sujeto y cada certificado de la cadena. Los bloques PEM permiten al responsable del endpoint comparar lo que recibió tu equipo con lo que debería presentar el servidor. Son certificados públicos, pero trata el registro con cuidado, porque los nombres de host y los emisores internos también pueden revelar detalles de la infraestructura.

Después prueba el comportamiento normal del cliente sin un encabezado de autorización:

```sh
curl --verbose --fail --show-error \\
  https://api.example.com/health
```

La transcripción detallada muestra la versión de TLS, el certificado seleccionado y el mensaje de verificación. Oculta las rutas de las solicitudes si revelan nombres de clientes. No añadas `-k` para que el comando termine correctamente. La verificación fallida es la evidencia que necesitas.

Un error de diagnóstico habitual consiste en omitir `-servername`. Muchos endpoints alojados seleccionan los certificados según SNI y devuelven un certificado predeterminado cuando el cliente lo omite. Eso crea una discrepancia de nombre de host que nunca afectó al cliente real. Otro error es usar `openssl s_client` sin `-verify_hostname` y tratar el resultado de la cadena como prueba de que el nombre de host coincide. No lo es.

Registra por separado la dirección resuelta con tu herramienta habitual de diagnóstico DNS. No conviertas la coincidencia de direcciones en toda la prueba. Los grandes proveedores usan legítimamente muchas direcciones, mientras que un atacante puede controlar una respuesta DNS que parezca creíble. El nombre del certificado, la ruta del emisor, la ruta de red y el registro de cambios aprobado cuentan juntos la historia.

## Clasifica el fallo antes de elegir una reparación

Los errores de certificados se parecen en los registros, pero requieren correcciones distintas. Clasifica las pruebas antes de cambiar la configuración de confianza. De lo contrario, el equipo resolverá el error visible y dejará intacto el problema original de enrutamiento o despliegue.

Un certificado caducado suele indicar que el operador del endpoint no renovó el certificado o no desplegó el nuevo certificado hoja. Comprueba el intervalo de validez del certificado capturado frente a un reloj confiable. Un error del reloj puede hacer que un certificado actual parezca caducado o aún no válido, así que verifica la hora del cliente antes de pedir a un proveedor que rote nada.

Una discrepancia de nombre de host significa que el servidor no demostró controlar el nombre solicitado por el cliente. Las causas habituales son una URL base de API incorrecta, un error de configuración de SNI, un host virtual predeterminado, un DNS obsoleto o un certificado de proxy para otro nombre. No aceptes un nombre alternativo porque se parezca al previsto. `api.example.com` y `api.internal.example.com` pueden representar servicios y límites de confianza distintos.

Un emisor desconocido puede significar que al cliente le falta una raíz privada o un certificado intermedio legítimo. También puede indicar que un dispositivo de inspección TLS no aprobado emitió un certificado hoja sustituto. Compara el emisor y la cadena con la información de despliegue publicada o registrada por el responsable del endpoint a través de un canal independiente. Un mensaje del mismo sistema que produjo el error no es una confirmación independiente.

Una cadena incompleta suele ser responsabilidad del endpoint. Los servidores deben enviar el certificado hoja y los certificados intermedios necesarios. Los clientes solo deberían tener ya sus raíces de confianza. Instalar localmente un intermedio ausente puede ocultar la configuración incorrecta del servidor en un equipo y dejar rotos a todos los demás clientes. Pide al responsable del servidor que sirva la cadena correcta.

Un certificado hoja autofirmado exige una sospecha adicional. Puede ser normal en un servicio interno de desarrollo, pero por sí solo no aporta una prueba de identidad pública. Una CA privada administrada puede funcionar bien si los administradores distribuyen su raíz mediante un almacén de confianza aprobado para dispositivos o cargas de trabajo y registran quién controla esa CA. Un certificado autofirmado aleatorio enviado por correo electrónico por el responsable de un endpoint no es un programa de confianza.

La revocación de certificados requiere cuidado. Muchos clientes no realizan comprobaciones de revocación en línea de forma fiable en todos los entornos, y los fallos de red pueden afectar esas comprobaciones. No afirmes que un certificado es seguro solo porque un handshake básico devuelva `0 (ok)`. Si un responsable informa de una clave privada comprometida o de un certificado revocado, bloquea el destino, rota las credenciales expuestas y despliega un reemplazo.

## Separa la ruta del servidor de la ruta del proxy

Un proxy administrado puede terminar TLS legítimamente y emitir certificados sustitutos, pero ese hecho debe estar documentado. Si un equipo empieza a ver de repente un emisor corporativo desconocido, no lo consideres inofensivo porque el sujeto contenga el nombre de tu empresa. Confirma el despliegue del proxy, su certificado raíz aprobado, su alcance y si los datos y las credenciales de la API pueden atravesarlo.

Comprueba la configuración del proxy en el entorno que realiza la llamada sin volcar valores que puedan contener credenciales. En un shell tipo Unix, esto imprime solo los nombres de las variables de proxy configuradas:

```sh
for n in HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY http_proxy https_proxy all_proxy no_proxy; do
  [ -n "${!n}" ] && printf '%s is set\n' "$n"
done
```

Una configuración del proxy puede explicar por qué la misma API funciona mediante una conexión móvil pero falla en la red de la oficina. No aprueba el proxy. Compara los resultados en una red alternativa autorizada solo cuando las normas de tu organización lo permitan. Si el emisor del certificado cambia con la red, registra ese resultado y entrégalo al responsable de la red.

Inspecciona también los cambios de resolución de nombres y de enrutamiento. Un registro DNS obsoleto después de una migración puede dirigir las llamadas a un balanceador antiguo que presenta un certificado retirado. Un DNS dividido puede devolver una dirección interna con un certificado privado a los dispositivos de la oficina y una dirección pública en otros lugares. Son diseños que pueden corregirse, pero el cliente debe confiar en el emisor adecuado para la ruta y seguir coincidiendo con el nombre de host solicitado.

No rodees el problema fijando una dirección IP. Las comprobaciones de identidad HTTPS usan nombres DNS, y una IP directa puede eludir el enrutamiento previsto, impedir la selección correcta de SNI u ocultar un problema de control DNS. Una sustitución de IP puede servir ocasionalmente para una prueba de diagnóstico muy controlada, pero necesita la aprobación del responsable del endpoint y nunca debe convertirse en la configuración permanente del agente.

Los proxies también plantean una cuestión de gobierno de datos que un error de certificado por sí solo no puede responder. Si el proxy termina TLS, puede leer los cuerpos de las API y el material de autorización inyectado. El equipo de seguridad debe decidir si esa inspección está permitida para esa API. Que el endpoint vuelva a funcionar no dice nada sobre si la nueva ruta es aceptable.

## Mantén la confianza en las CA privadas limitada y revisable

Las autoridades de certificación privadas resuelven un problema real para las API internas, los entornos de desarrollo y las mallas de servicios controladas. Fallan cuando los equipos distribuyen las raíces de manera informal y olvidan qué procesos confían en ellas. Una raíz de confianza da a su titular un poder amplio para emitir identidades dentro de su dominio de confianza, por lo que añadir una es un cambio de seguridad administrativa, no un simple ajuste de compatibilidad.

Instala una raíz privada aprobada mediante el sistema operativo administrado, la imagen del contenedor o el almacén de confianza de la aplicación que controla la llamada. Registra el sujeto de la raíz, su huella digital, el responsable, los sufijos DNS previstos, la fecha de aprobación y el procedimiento para retirarla. Limita el alcance de la confianza cuando el entorno de ejecución lo permita. Una CA de desarrollo no debería convertirse silenciosamente en una raíz confiable para todos los agentes de producción de todos los equipos.

Evita confiar en un único certificado hoja como atajo ante la ausencia de un proceso de CA. La confianza en un certificado hoja se rompe con la renovación y anima a pegar cadenas PEM en los repositorios. También dificulta distinguir una rotación deliberada del endpoint de una sustitución inesperada. Si controlas ambos extremos, crea en su lugar un proceso de CA privada con material de firma protegido, emisión documentada y rotación planificada.

mTLS añade una dirección de identidad independiente. En HTTPS normal, el cliente valida el certificado del servidor. En mTLS, el servidor también pide al cliente un certificado. Un fallo como «alert certificate required» o «bad certificate» puede significar que el cliente no proporcionó su certificado, presentó uno de un emisor incorrecto o no tiene la clave privada correspondiente. No significa que desactivar la verificación del servidor vaya a ayudar.

Mantén las claves privadas del cliente fuera de los prompts, los fragmentos del shell y los espacios de trabajo del agente. Da al proceso controlado acceso a la credencial del cliente mediante un almacén del sistema operativo u otro mecanismo protegido. Si un certificado del cliente o su clave privada pudo atravesar una conexión TLS no verificada, revócalo o sustitúyelo según el procedimiento de la CA emisora. Trátalo de forma distinta a un certificado de servidor, pero no con ligereza.

La fijación de certificados es otra área en la que las buenas intenciones causan interrupciones. Fijar un certificado hoja vincula el cliente a un artefacto concreto de renovación, por lo que una rotación normal puede detener a todos los agentes. La fijación puede tener sentido para una integración limitada y de alto riesgo cuando los operadores mantienen pins de respaldo y prueban la rotación. La mayoría de los equipos obtiene mejores resultados aplicando la verificación del nombre de host, administrando las raíces de confianza aprobadas y vigilando la caducidad de los certificados.

## Restaura el acceso solo después de una comprobación independiente

Restaura el agente solo cuando alguien haya verificado la corrección fuera del flujo de trabajo fallido del agente. La comprobación debe usar el nombre de host real, el almacén de confianza previsto y un cliente que realice la verificación normal. Visitar el endpoint con un navegador suele ser insuficiente porque los navegadores y los clientes de línea de comandos pueden usar configuraciones de proxy y almacenes de confianza diferentes.

Para una API pública, verifica que la cadena presentada conduzca a una raíz pública de confianza esperada, que los nombres alternativos del sujeto incluyan el nombre de host configurado y que el responsable del endpoint confirme el despliegue o la renovación mediante un cambio registrado. Para una API privada, verifica la raíz privada aprobada, el emisor, el nombre de host y la ruta de red prevista. Guarda el resultado correcto junto al fallo original.

Después ejecuta una acción autenticada de bajo impacto por la misma ruta que usará el agente. Elige un endpoint de solo lectura o una comprobación de identidad inofensiva si la API ofrece una. Observa el registro de acciones y el registro de auditoría del servidor, si están disponibles. Confirma el nombre de host de destino, el estado de la respuesta y la identidad de la credencial utilizada. No restaures un trabajo por lotes amplio como primera prueba.

Si el fallo anterior dejó alguna posibilidad de que un token, una solicitud firmada o una credencial mTLS llegara a un impostor, rota esa credencial antes de reanudar el trabajo normal. Los equipos suelen resistirse a rotar credenciales porque las pruebas son incompletas. Es al revés. Precisamente porque las pruebas son incompletas, una credencial que atravesó una conexión no verificada debe tratarse como expuesta.

Escribe la corrección exacta, no una conclusión vaga como «TLS solucionado». Un cierre útil indica que el operador del endpoint desplegó un certificado intermedio, que el almacén de confianza administrado recibió una raíz aprobada concreta o que se eliminó una configuración del proxy. También indica quién verificó el nombre de host y qué ejecuciones del agente se reanudaron. Ese registro evita que el siguiente responsable vuelva a introducir una excepción insegura cuando el mismo certificado se renueve.

## Haz que el camino seguro sea más fácil que el atajo

El procedimiento fallará si la gestión segura tarda horas y el bypass consiste en una variable de entorno. Diseña la integración del agente para que no pueda elegir un modo TLS inseguro, editar la configuración global de confianza ni ver credenciales de larga duración durante la resolución de problemas. Mantén la configuración de conexión, los nombres de host aprobados y el material de confianza bajo el proceso normal de revisión de cambios.

Sallyport puede guardar las credenciales API en una bóveda cifrada y realizar llamadas HTTP para un agente, de modo que el agente no recibe las credenciales. Sus registros de sesión y de llamadas también pueden conservar quién intentó realizar la acción, pero una persona debe decidir si un certificado modificado corresponde a un cambio aprobado o a una ruta peligrosa.

Genera alertas ante fallos repetidos de validación y ante cualquier intento de invocar bypasses conocidos. Una llamada fallida debe incluir suficiente contexto estructurado para que el responsable identifique el nombre de host, la clase de fallo y la ejecución del agente sin incluir secretos. Da a los agentes una instrucción fija: detenerse ante errores de validación de certificados, informar del error y del endpoint exactos y solicitar una revisión humana. No les pidas que encuentren una alternativa.

La primera corrección que merece la pena hacer suele ser aburrida: elimina cualquier opción de verificación insegura que ya exista en los scripts y haz que el cliente normal use un almacén de confianza administrado. Después prueba la renovación del certificado antes de que producción lo haga por ti. Los equipos que ensayan una renovación y un incidente de emisor inesperado responden más rápido que aquellos cuyo único plan TLS consiste en copiar un comando de un foro.

Una advertencia de certificado ha cumplido su función cuando interrumpe una solicitud que no debería continuar. Mantenla así.