Documentación en las API
Generalmente, las APIs están documentadas para que los desarrolladores sepan cómo utilizarlas e integrarlas correctamente.
Esta documentación puede encontrarse tanto en formatos legibles por humanos como legibles por máquinas.
- Documentación legible por humanos: Está diseñada para que los desarrolladores comprendan la lógica de la API. Suele incluir explicaciones detalladas, ejemplos de peticiones y diversos escenarios de uso.
- Documentación legible por máquinas: Está estructurada para que el software pueda procesarla y automatizar tareas como la integración, pruebas y validación. Se escribe en formatos como
JSONoXMLy sigue esquemas como OpenAPI (Swagger).
La documentación suele estar disponible de forma pública, especialmente si la API está orientada a desarrolladores externos. En estos casos, se recomienda siempre comenzar el análisis de seguridad revisando a fondo la documentación.
Descubrimiento
Incluso si la documentación de una API no es pública, es posible acceder a ella explorando las aplicaciones que la consumen o mediante técnicas de Fuzzing (descubrimiento de archivos y directorios).
Para esta fase, puedes apoyarte en el Burp Suite Scanner (Crawler) o intentar acceder directamente a rutas y recursos típicos donde se suele alojar la documentación, por ejemplo:
/api/swagger/index.html/openapi.json/api/v1/docs
Otra opción efectiva es utilizar Wordlists especializadas en APIs para encontrar archivos de definición expuestos.
Laboratorio: Exploiting an API endpoint using documentation
Objetivo del laboratorio
Para resolver este laboratorio, debes localizar la documentación de la API y utilizar la información encontrada para eliminar al usuario carlos.
PoC
[1] En primera instancia, iniciamos sesión con las credenciales proporcionadas por el laboratorio.
[2] A priori no hay ningún indicio claro de la API. Sin embargo, al cambiar la dirección de correo electrónico de nuestra cuenta, podemos interceptar una petición que revela un nuevo endpoint y hace referencia directa a una API.
Posteriormente, tomamos la ruta base de la API (/api/) e intentamos descubrir el recurso de documentación, probando con nombres comunes como openapi.json. Gracias a esto, logramos visualizar la definición completa de la API.
[3] Una vez obtenida la documentación, identificamos el endpoint que permite la gestión de usuarios y verificamos los métodos permitidos.
En el esquema de la documentación, observamos que existe un método DELETE para la ruta /user/{user.username}:
"paths":{
"/user/{user.username}":{
"get":{
"parameters":[
{
"name":"user.username",
"in":"path",
"required":true,
"schema":{
"type":"string"
}
}
],
"responses":{ ... }
},
"delete":{
"parameters":[
{
"name":"user.username",
"in":"path",
"required":true,
"schema":{
"type":"string"
}
}
]
}
}
}
[4] Finalmente, enviamos la petición HTTP utilizando el método DELETE contra el endpoint identificado para eliminar al usuario carlos, logrando resolver el laboratorio.
Documentación legible por máquinas
Puedes utilizar diversas herramientas automatizadas para analizar cualquier documentación de API legible por máquina que encuentres durante tu auditoría.
El Burp Scanner es excelente para identificar y rastrear archivos de OpenAPI o definiciones en formato JSON y YAML. También es muy útil la extensión OpenAPI Parser (disponible en la BApp Store) para procesar estos archivos directamente en Burp.
Además de Burp, herramientas especializadas como Postman o SoapUI son perfectamente válidas para importar estas definiciones y realizar las pruebas de forma más cómoda.