Versiones olvidadas de APIs: cómo detectarlas y desactivarlas de forma segura

Se denomina API en la sombra a las interfaces de red que existen y aceptan tráfico, pero que no figuran en la documentación oficial, en el catálogo de servicios, en la política de seguridad ni en los esquemas de supervisión. Las versiones olvidadas de los puntos finales son variantes antiguas de las interfaces que siguen estando disponibles en producción tras la migración a una nueva versión, aunque su ciclo de vida haya concluido. Ambos fenómenos aumentan la superficie de ataque, generan discrepancias en las políticas y afectan al control de acceso. Presento a continuación una guía práctica para detectar, gestionar y cerrar esas interfaces.

De dónde provienen las interfaces en la sombra y las versiones olvidadas

Entornos de desarrollo paralelos y pruebas de funciones. Rutas temporales para pruebas o demostraciones quedan activas después del lanzamiento y se convierten en permanentes sin registrarse en el catálogo de APIs.
Migración incompleta a una nueva versión. Se implantó el nuevo esquema, pero no se desactivaron las rutas antiguas. Los clientes siguen llamando a los endpoints obsoletos.
Eludir el gateway API centralizado. El equipo publica el servicio directamente detrás del balanceador, pasando por alto las políticas comunes de autorización, los límites de velocidad y el registro.
Generación automática de rutas por los frameworks. Rutas habilitadas por defecto para administración, depuración y métricas quedan accesibles desde el exterior por una configuración errónea.
Clústeres heredados y dominios olvidados. Los entornos archivados no se apagan y siguen atendiendo tráfico, incluso con versiones obsoletas de bibliotecas de seguridad.

Por qué es peligroso

Desajuste de las políticas de autenticación y autorización. Para una interfaz en la sombra pueden faltar las comprobaciones obligatorias del token, la verificación de la audiencia del token, la comprobación del ámbito y la validez temporal.
Falta de protección a nivel de gateway. No hay límites unificados de velocidad, comprobación de esquemas, políticas CORS ni restricciones por métodos.
Acceso no contabilizado a los datos. La interfaz devuelve campos eliminados de la versión actual o permite filtros de selección más amplios.
Registro y trazabilidad incompletos. Las solicitudes y respuestas no llegan a los sistemas centralizados de análisis de eventos y detección de anomalías.
Dependencias obsoletas. La versión antigua usa bibliotecas, algoritmos criptográficos o protocolos vulnerables.

Inventario de APIs como base de protección

El primer paso es elaborar un listado completo de las interfaces según el tráfico real y compararlo con el catálogo oficial de APIs y con las declaraciones OpenAPI.

Detección pasiva a partir del tráfico. Habilite el espejado de las solicitudes entrantes hacia un analizador. Correlacione rutas, métodos, cabeceras de autorización y formatos de cuerpo con los esquemas registrados.
Comparación con los esquemas OpenAPI. Para cada zona de dominio y servicio almacene la especificación actual. Cualquier ruta que no figure en el esquema se considera no identificada y requiere verificación.
Escaneo de routers y balanceadores. Extraiga las configuraciones de hosts virtuales, rutas escuchadas y reglas de reescritura. Compare con el catálogo de APIs.
Búsqueda de dominios y subdominios obsoletos. Revise los registros DNS, los certificados TLS y los grupos objetivo activos en los balanceadores.
Inventario de servicios en el clúster. Use herramientas de descubrimiento de servicios y etiquetas del orquestador. Correlacione puertos abiertos y anotaciones de ingress con el registro de APIs.

Política de versionado y retirada de servicio

Una estrategia de versionado fiable reduce la probabilidad de versiones olvidadas y facilita su cierre.

Formato de versión único. Opciones: prefijo de ruta como v1, v2, cabecera de versión o parámetro de consulta. El formato debe ser único para toda la organización.
Compatibilidad y matriz de soporte. Para cada versión defina el periodo de soporte, los requisitos mínimos para los clientes y las restricciones del esquema.
Procedimiento de retirada. Publique avisos, devuelva advertencias mediante la cabecera Sunset y mediante eventos internos, establezca la fecha final de desconexión y documente la ruta de migración.
Desactivación forzada tras la fecha de retirada. Tras el fin del soporte, el gateway debe bloquear las versiones obsoletas con un código de estado claro y un enlace a la documentación.

Control de acceso y políticas técnicas unificadas

Cualquier interfaz, incluida la versión antigua, debe pasar por el punto común de aplicación de políticas.

Gateway API centralizado. Todas las solicitudes entrantes deben pasar por el gateway con verificación de tokens, límites de velocidad, validación de esquemas, filtrado de métodos y selección de orígenes CORS permitidos.
Modelo de autenticación unificado. Se recomienda usar el protocolo OAuth 2.1 u OpenID Connect con verificación de audiencia, ámbito y marcas temporales. Para interacciones máquina a máquina, use autenticación mutua TLS cuando sea necesario.
Autorización basada en roles. Incluya comprobaciones de permisos en el gateway y en la aplicación. Separe los permisos por operaciones y por conjuntos de datos.
Validación del esquema de solicitud y respuesta. Alinee las cargas útiles con OpenAPI y bloquee campos desconocidos y formatos no previstos.

Monitorización y señales de detección

Las señales oportunas permiten detectar rutas en la sombra y llamadas a versiones obsoletas antes de un incidente.

Rutas anómalas. Aumento brusco de solicitudes a prefijos poco frecuentes, alta proporción de códigos 404 y 405, incremento de la diversidad de rutas con pocas repeticiones.
Inconsistencias en los tokens. Llamadas sin token, con token para una audiencia incorrecta o sin el ámbito requerido.
Orígenes inesperados. Llamadas directas a direcciones internas del servicio, eludiendo el gateway, y accesos desde redes externas a rutas de diagnóstico.
Inconsistencia de contenido. Respuestas con campos antiguos que no existen en la versión actual y desajustes de tipos en las respuestas.

Control en la canalización de entrega

Las interfaces deben verificarse antes de la publicación. Esto reduce el riesgo de rutas no contabilizadas.

Revisión del código de infraestructura. Políticas para las descripciones de rutas, ingress y balanceadores que prohíban publicar servicios fuera del gateway.
Validación de esquemas. Validación automática de OpenAPI y comparación con modelos de referencia. Cualquier discrepancia requiere aprobación.
Verificación de contratos. Use pruebas de contratos orientadas a consumidores para controlar cambios incompatibles hacia atrás.
Análisis estático de rutas en la aplicación. Recolección automática de tablas de enrutamiento en los frameworks y comparación con los registros de APIs.

Procedimiento para retirar una versión obsoleta

Fijación de la versión y plazos. Establezca la fecha de cese de recepción de solicitudes y publique el plan de migración para los clientes.
Aplicación de restricciones a nivel del gateway. Añada registro de accesos a la versión y límites de velocidad suaves.
Devolver advertencias. Añada cabeceras informativas y enlaces a la documentación en las respuestas de la versión antigua.
Bloqueo de escritura. En la fase de preparación limite las operaciones de creación, modificación y eliminación en la versión obsoleta.
Desconexión. El día señalado bloquee las rutas en el gateway y elimine las configuraciones en los balanceadores.
Archivado de esquemas y registros. Guarde las especificaciones y los registros de accesos para investigación de incidentes y auditoría.

Ejemplos técnicos

Bloqueo de rutas desconocidas en el gateway

# Pseudo-política a nivel de gateway allowed_prefixes = ["/v1/", "/v2/", "/healthz"] if not request.path.starts_with_any(allowed_prefixes): deny(status=404, body="Not Found")

Verificación obligatoria del token y del ámbito

# Verificación en el gateway jwt = verify_jwt(request.authorization) require(jwt.audience == "api-public") require("read:orders" in jwt.scopes for GET /orders) require("write:orders" in jwt.scopes for POST /orders)

Filtro de publicación de servicios a través del gateway único

# Revisión del código de infraestructura deny_if(resource.type == "ingress" and resource.annotations["bypass-gateway"] == "true") deny_if(resource.type == "load_balancer" and resource.target not in approved_backends)

Validación del esquema de solicitud y respuesta

# Comparación con OpenAPI schema = load_openapi("v2.yaml") validate_request(schema, request.path, request.method, request.headers, request.body) response = upstream_call() validate_response(schema, request.path, request.method, response.status, response.headers, response.body)

Playbook de incidentes

Primeros minutos

Redirigir el servicio del dominio al gateway si se detecta acceso directo al servicio.
Habilitar bloqueo de rutas desconocidas y verificación obligatoria de tokens.
Restringir la velocidad para prefijos y orígenes sospechosos.

La primera hora

Recopilar la lista de rutas, métodos y clientes implicados a partir de los registros del gateway.
Comparar las rutas encontradas con el catálogo de APIs y los esquemas OpenAPI.
Determinar los conjuntos de datos accesibles a través de las interfaces no registradas y evaluar el riesgo.

Las primeras 24 horas

Cerrar las vías de elusión del gateway a nivel de balanceador y cortafuegos.
Introducir reglas de enrutamiento temporales que devuelvan respuestas controladas y enlaces a la documentación de migración.
Preparar el cambio de configuración para la desactivación completa de versiones obsoletas y publicar un aviso a los clientes.

Lista de verificación de implementación

Catálogo unificado de APIs con registro obligatorio de esquemas OpenAPI y del propietario de la interfaz.
Tráfico obligatorio a través del gateway API con verificación de tokens, límite de velocidad y validación de esquemas.
Política de versionado y plazos de soporte documentados para cada versión.
Procedimiento de retirada con notificaciones, métricas y plan de desconexión.
Detección pasiva de interfaces mediante espejado de tráfico y comparación con el catálogo.
Controles en la canalización de entrega: políticas de infraestructura, validación de esquemas y verificación de contratos.
Alertas por rutas anómalas, accesos que eluden el gateway y inconsistencias en los tokens.

Recomendaciones para la organización de procesos

Asignación de un propietario de la interfaz. Cada interfaz debe tener un equipo responsable de mantener el esquema, la documentación y los plazos de retirada.
Revisión periódica de configuraciones. Compare periódicamente las configuraciones de routers, gateways y balanceadores con el catálogo de APIs.
Restricción de publicación. La publicación de nuevas rutas solo se permite mediante el proceso de registro y validación de esquemas.
Formación de los equipos. Desarrolladores y equipos de operaciones deben comprender las reglas de versionado, publicación y retirada.

Conclusión

Las APIs en la sombra y las versiones olvidadas de puntos finales surgen por la elusión de políticas comunes, un versionado descuidado y un control insuficiente de las configuraciones. La solución consiste en inventariar según el tráfico real, canalizar centralizadamente a través del gateway, un modelo unificado de autenticación y autorización, un versionado estricto, una retirada gestionada y controles en la canalización de entrega. Ese enfoque reduce la superficie de ataque, elimina discrepancias en las políticas y asegura un ciclo de vida controlado para las interfaces.