Crea un mapa automático por API en minutos: qué puede hacer Vespasian

Vespasian – herramienta de código abierto para descubrir endpoints de API y generar automáticamente especificaciones a partir del tráfico HTTP real. El proyecto soporta tres tipos de interfaces: REST, GraphQL y SOAP. Vespasian genera OpenAPI 3.0, GraphQL SDL o WSDL, según el tipo de interfaz que detecte en el tráfico capturado.

La herramienta es desarrollada por la empresa Praetorian. Vespasian forma parte del conjunto de herramientas ofensivas de código abierto de la compañía y está pensado para tareas que surgen en las pruebas de penetración y en el análisis de la superficie de ataque de aplicaciones. El proyecto se publica por separado en un repositorio abierto y se distribuye bajo la licencia Apache 2.0.

Resumen del proyecto

Vespasian resuelve un problema práctico conocido por casi todos los especialistas en seguridad de API. Durante una prueba de penetración la documentación del API a menudo está ausente, obsoleta o cubre solo parte de los endpoints. El análisis estático del código tampoco siempre ayuda, porque las aplicaciones web modernas y los clientes móviles construyen las solicitudes en tiempo de ejecución, en lugar de almacenarlas como una lista simple de rutas.

Vespasian propone otro enfoque. En vez de intentar adivinar la estructura del API a partir del código fuente, la herramienta observa lo que la aplicación realmente envía por la red. Luego Vespasian separa las solicitudes útiles del ruido de fondo, determina el tipo de interfaz y genera una especificación legible por máquina. Este enfoque es especialmente útil cuando el rastreo habitual de páginas o la búsqueda de /swagger.json no arrojan resultados.

Cómo funciona Vespasian

Vespasian se basa en un esquema de dos fases.

1. En la primera fase la herramienta captura el tráfico. Para ello ejecuta un rastreo de la aplicación con un navegador sin cabeza que ejecuta JavaScript, o bien importa tráfico ya recogido desde Burp Suite, HAR o mitmproxy.
2. En la segunda fase Vespasian analiza las solicitudes capturadas, identifica el tipo de interfaz, elimina duplicados, realiza solicitudes adicionales si es necesario y, finalmente, construye la especificación resultante.

Esta separación ofrece varias ventajas prácticas. La captura se puede realizar una vez y la generación repetirse tantas veces como se necesite. El archivo de tráfico puede analizarse por separado, pasarse a un colega o utilizarse más tarde sin volver a rastrear el objetivo. La documentación del proyecto destaca que este enfoque facilita la depuración y permite analizar el tráfico sin acceso a la red.

Vespasian resulta más útil en escenarios de trabajo que en la descripción arquitectónica. El orden típico de acciones según la documentación es:

1. El especialista indica la dirección de la aplicación o importa el tráfico ya capturado desde un proxy.
2. Vespasian captura todas las solicitudes HTTP que la aplicación envía durante su ejecución, incluyendo las generadas por JavaScript en tiempo de ejecución.
3. La herramienta separa las solicitudes a la API de imágenes, hojas de estilo, scripts, llamadas analíticas y otro tráfico de fondo.
4. Tras la clasificación, Vespasian agrupa rutas iguales, convierte segmentos dinámicos en parámetros y construye la descripción de los endpoints.
5. En la etapa final la herramienta complementa la información mediante consultas de solo lectura seguras y genera la especificación, que puede entregarse a otras herramientas de análisis.

Para REST eso significa construir OpenAPI 3.0 con rutas, métodos, parámetros y esquemas de respuesta. Para GraphQL Vespasian intenta obtener el esquema mediante un auto-sondeo por etapas; si el esquema está deshabilitado, extrae la estructura de las consultas y respuestas ya observadas. Para servicios SOAP la herramienta intenta obtener el WSDL desde la URL del servicio y, si el documento no está disponible, reconstruye la descripción a partir del contenido de las solicitudes y respuestas.

Dónde es útil la herramienta

• Pruebas de penetración sin documentación del API. Vespasian ayuda a recopilar rápidamente un mapa de endpoints, parámetros y formatos de respuesta cuando la documentación falta o está desactualizada.
• Análisis de tráfico ya recogido. La herramienta puede procesar datos desde Burp Suite, HAR y mitmproxy, por lo que el trabajo manual previo no se pierde.
• Revisión de aplicaciones móviles. Un navegador sin cabeza no captura las llamadas de un cliente móvil, pero Vespasian puede procesar tráfico desde un proxy y generar una especificación a partir de él.
• Preparación de datos para la siguiente fase de pruebas. La documentación indica la integración con Hadrian, donde la especificación generada se usa para la comprobación automatizada de autorización.
• Mapeo de la superficie de ataque de una aplicación web. Tras la ejecución de JavaScript la herramienta muestra no solo una lista de URL, sino la estructura de la interfaz disponible para análisis posteriores.

Cómo distingue Vespasian entre tipos de API

Para REST Vespasian normaliza las rutas. Por ejemplo, direcciones como /users/42 y /users/87 se reducen al patrón /users/{id}. Al mismo tiempo, rutas literales conocidas, como /users/me o /users/self, se conservan sin reemplazo. Para GraphQL la herramienta usa un esquema de auto-sondeo en tres etapas para sortear filtros que bloquean las consultas habituales al esquema. Para SOAP, Vespasian primero intenta obtener un WSDL listo y, si no existe, construye la descripción a partir del intercambio observado de mensajes.

Comparación entre Vespasian y Burp Suite

En esencia, las herramientas no se excluyen mutuamente. La documentación de Vespasian propone el escenario en el que el especialista primero trabaja con Burp Suite y luego exporta el tráfico para pasarlo a Vespasian y generar la especificación. Burp Suite tiene otro papel: el conjunto oficial de PortSwigger se centra en la intercepción de tráfico, comprobaciones manuales, reenvío de solicitudes y ataques configurables a través de módulos como Proxy, Repeater e Intruder.

Instalación y ejecución

La documentación del proyecto ofrece tres opciones:

• instalar desde el código fuente con go install;
• descargar un binario ya compilado desde la página de releases;
• compilar desde el código fuente con make build.

Un inicio básico es:

vespasian scan https://app.example.com -o api.yaml

Si se necesita el modo de dos fases, primero se captura el tráfico:

vespasian crawl https://app.example.com -o capture.json

o se importan datos ya recogidos:

vespasian import burp traffic.xml -o capture.json

y luego se genera la especificación:

vespasian generate rest capture.json -o api.yaml

La documentación describe por separado parámetros útiles: pasar cabeceras de autorización, enrutar el tráfico a través de un proxy, seleccionar el ámbito del rastreo, ajustar el umbral de confianza de la clasificación y activar la salida detallada de las solicitudes detectadas.

Limitaciones y seguridad

Los desarrolladores formulan la principal limitación de forma explícita: la herramienta funciona de manera probabilística. Solo ve los endpoints que han aparecido efectivamente en el tráfico capturado. Si una aplicación accede a una interfaz solo tras una secuencia de acciones rara, Vespasian puede no detectarla. Lo mismo aplica a tipos de parámetros y a la exhaustividad del esquema. A partir del conjunto observado de datos la herramienta infiere la estructura, pero no puede garantizar una cobertura absoluta.

Hay una segunda limitación: Vespasian no sustituye el análisis manual. Reúne bien el mapa de la interfaz y alivia la reconstrucción rutinaria del API, pero no verifica automáticamente la lógica de negocio, no toma decisiones por el especialista y no convierte el tráfico capturado en un informe definitivo sobre seguridad.

En la documentación hay dos aclaraciones importantes sobre seguridad. La primera trata de las comprobaciones activas. Durante el sondeo adicional Vespasian bloquea por defecto las solicitudes a direcciones privadas y a la propia máquina. Para objetivos internos esa protección puede desactivarse con un parámetro, pero está activada por defecto. La segunda aclara el uso en entornos productivos. Los autores indican que la fase de rastreo y las solicitudes adicionales se diseñan como operaciones de solo lectura. No obstante, la documentación recomienda acordar las pruebas con el propietario del objetivo y, cuando sea posible, usar un entorno intermedio en lugar del sistema en producción. La documentación de Burp Suite también advierte que las funciones de las herramientas de pruebas de seguridad pueden dañar los sistemas objetivo si se usan sin la debida precaución.

Conclusión

Vespasian no es un escáner de vulnerabilidades ni un rastreador de páginas más. Es una herramienta especializada que ayuda a reconstruir rápidamente la estructura real del API a partir del tráfico que la aplicación ya genera en ejecución. El escenario de uso más potente es una prueba de penetración o el análisis de la superficie de ataque sin documentación actualizada, especialmente cuando parte del tráfico ya está disponible en Burp Suite o mitmproxy.

La principal ventaja de Vespasian es el ahorro práctico de tiempo en la fase de mapeo de la interfaz. La limitación principal también es evidente: la herramienta no sabe más de lo que se vio en la captura. Por eso es mejor entender a Vespasian como un medio para reconstruir APIs y preparar datos para comprobaciones posteriores, no como una solución única para un análisis completo de seguridad.