alufers/mitmproxy2swaggerIngeniería inversa automágica de APIs REST mediante captura de tráfico
https://user-images.githubusercontent.com/5400940/168086818-c48f60ab-3f95-42eb-b435-c8b1a6326b81.mp4
Una herramienta para convertir automáticamente capturas de mitmproxy a especificaciones OpenAPI 3.0. Esto significa que puedes realizar ingeniería inversa de APIs REST automáticamente con solo ejecutar las aplicaciones y capturar el tráfico.
🆕 ¡NUEVO!
Se ha añadido soporte para procesar archivos HAR exportados desde las herramientas de desarrollo del navegador. Consulta Uso - HAR para más detalles.
Primero necesitarás python3 y pip3.
$ pip install mitmproxy2swagger
# ... o ...
$ pip3 install mitmproxy2swagger
# ... o ...
$ git clone [email protected]:alufers/mitmproxy2swagger.git
$ cd mitmproxy2swagger
$ docker build -t mitmproxy2swagger .
Luego clona el repositorio y ejecuta mitmproxy2swagger según los ejemplos a continuación.
Para crear una especificación inspeccionando el tráfico HTTP necesitarás:
Captura el tráfico utilizando la herramienta mitmproxy. Personalmente recomiendo usar mitmweb, que es una interfaz web integrada en mitmproxy.
$ mitmweb
Web server listening at http://127.0.0.1:8081/
Proxy server listening at http://*:9999
...
IMPORTANTE
Para configurar tu cliente para que use el proxy expuesto por mitmproxy, consulta la documentación de mitmproxy para más información.
Guarda el tráfico en un archivo de flujo.
En mitmweb puedes hacerlo usando el menú 'Archivo' y seleccionando 'Guardar':
Ejecuta la primera pasada de mitmproxy2swagger:
$ mitmproxy2swagger -i <ruta_al_flujo_mitmproxy> -o <ruta_al_esquema_de_salida> -p <prefijo_api>
# ... o ...
$ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i <ruta_al_flujo_mitmproxy> -o <ruta_al_esquema_de_salida> -p <prefijo_api>
Ten en cuenta que puedes usar un esquema existente, en cuyo caso el esquema existente se ampliará con los nuevos datos. También puedes ejecutarlo varias veces con diferentes capturas de flujo; los datos capturados se fusionarán de forma segura.
<prefijo_api> es la URL base de la API que deseas aplicar ingeniería inversa. Deberás obtenerla observando las solicitudes realizadas en mitmproxy.
Por ejemplo, si una aplicación ha realizado solicitudes como estas:
https://api.example.com/v1/login
https://api.example.com/v1/users/2
https://api.example.com/v1/users/2/profile
Captura y exporta el tráfico desde las herramientas de desarrollo del navegador.
En las herramientas de desarrollo del navegador, ve a la pestaña Red y haz clic en el botón "Exportar HAR".
Continúa de la misma manera que lo harías con el volcado de mitmproxy. mitmproxy2swagger detectará automáticamente el archivo HAR y lo procesará.
Consulta los ejemplos. Allí encontrarás un esquema generado y un archivo HTML con la documentación generada (mediante redoc-cli).
Consulta el archivo HTML generado.
Este proyecto utiliza:
Para instalar las dependencias:
uv sync
Ejecutar linters:
uv run prek run --all-files
Instalar hooks de prek:
uv run prek install
Ejecutar pruebas:
uv run pytest
Ejecutar pruebas con cobertura:
uv run pytest --cov=mitmproxy2swagger
MIT
El prefijo probablemente sea https://api.example.com/v1.
Al ejecutar la primera pasada debería haberse creado una sección en el archivo de esquema como esta:
x-path-templates:
# Elimina el prefijo ignore: para generar un endpoint con su URL
# Las líneas más cercanas a la parte superior tienen prioridad, la coincidencia es voraz
- ignore:/addresses
- ignore:/basket
- ignore:/basket/add
- ignore:/basket/checkouts
- ignore:/basket/coupons/attach/{id}
- ignore:/basket/coupons/attach/104754
Debes editar el archivo de esquema con un editor de texto y eliminar el prefijo ignore: de las rutas que desees que se generen. También puedes ajustar los parámetros que aparecen en las rutas.
Ejecuta la segunda pasada de mitmproxy2swagger:
$ mitmproxy2swagger -i <ruta_al_flujo_mitmproxy> -o <ruta_al_esquema_de_salida> -p <prefijo_api> [--examples]
# ... o ...
$ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i <ruta_al_flujo_mitmproxy> -o <ruta_al_esquema_de_salida> -p <prefijo_api> [--examples]
Ejecuta el comando una segunda vez (con el mismo archivo de esquema). Tomará las líneas editadas y generará descripciones de endpoints.
Ten en cuenta que mitmproxy2swagger no sobrescribirá las descripciones de endpoints existentes; si deseas sobrescribirlas, puedes eliminarlas antes de ejecutar la segunda pasada.
Pasar --examples añadirá datos de ejemplo a las solicitudes y respuestas. Ten cuidado al usar esta opción, ya que puede añadir datos sensibles (tokens, contraseñas, información personal, etc.) al esquema.
Pasar --headers añadirá datos de cabeceras a las solicitudes y respuestas. Ten cuidado al usar esta opción, ya que puede añadir datos sensibles (tokens, contraseñas, información personal, etc.) al esquema.