VPC AtlasNadie mantiene al día el diagrama de red de AWS. He hecho una herramienta para eso
VPC Atlas lee una cuenta de AWS con llamadas de solo lectura y dibuja su red en draw.io y Lucidchart. Alfa, licencia MIT.
En todos los equipos a los que me he incorporado, lo primero que pedían era lo mismo: el diagrama de red. El que muestra cada VPC, cómo se conectan las VPC entre sí a través de Transit Gateways, peerings, VPN y Direct Connect, y qué hay en el borde, delante de ellas. Y todas las veces, el diagrama que existía estaba desactualizado.
El diagrama que nadie mantiene
Un diagrama de red dibujado a mano está mal una semana después. Alguien añade un attachment, alguien comparte un Transit Gateway por AWS RAM, aparece un peering con otra cuenta, y el dibujo se queda como estaba.
La alternativa es reconstruirlo desde la consola: abrir cada VPC, leer las tablas de rutas, seguir los attachments, revisar los endpoints y, después, dibujarlo. En una cuenta real eso lleva días. Yo quería apuntar una herramienta a la cuenta, tener el diagrama en minutos y repetirlo la semana siguiente para comparar.
Qué hace VPC Atlas
vpcatlas se conecta a una cuenta de AWS con permisos de auditor y mapea su red: cuentas, regiones, VPC, subredes, enrutamiento, gateways, endpoints, balanceadores, firewalls, el resolver de DNS y los recursos compartidos. También lee la capa de DNS y borde (Route 53, CloudFront, WAF, ACM, Shield), el cómputo, los almacenes de datos y los servicios de cuenta.
Es de solo lectura por diseño. Llama a las API Describe*, Get*, List* y Search* y nunca crea, cambia ni borra nada. Trae la política mínima que necesita, así que puedes leer lo que pide antes de concedérselo.
Una ejecución produce tres tipos de salida:
- Diagramas. Una página global, una página por región y una página por VPC, como ficheros
.drawioy.lucid, dibujados con los AWS Architecture Icons y siguiendo la disposición de la referencia de red multicuenta (landing zone) de AWS Managed Services. - Un inventario. JSON, Markdown y HTML, con cada recurso cuenta por cuenta y una sección por cada cuenta externa vinculada a la tuya.
- Un panel.
vpcatlas servemuestra los mismos diagramas en el navegador, guarda un historial de escaneos y dibuja la diferencia entre dos de ellos: lo añadido en verde, lo que cambió en naranja.
El resultado en bruto se guarda también como vpcatlas-graph.json, para que puedas volver a dibujar más tarde sin llamar a AWS otra vez.
Las grabaciones y los diagramas de este artículo salen de una cuenta de AWS simulada, así que los identificadores son de ejemplo. Este es el panel sobre esa cuenta:
Y una página de región:
Cómo funciona
Un pipeline de solo lectura con cuatro etapas: recolección, grafo, disposición y exportación. Cada etapa tiene una entrada y una salida.
Recolección. Un colector por servicio, todos paginados. Las regiones se procesan en paralelo; dentro de una región los colectores van uno detrás de otro, para mantener bajo el throttling de la API. Una llamada que falla con AccessDenied se registra y se salta. Nunca detiene la ejecución.
Grafo. Los resultados se convierten en un grafo dirigido de networkx envuelto en modelos de Pydantic. Las aristas tienen tipo (contains, routes_to, attached_to, peered_with, shared_from) y las cuentas externas también son nodos.
Disposición. Las posiciones se calculan una sola vez, como una cuadrícula determinista: nube, región, VPC, zona de disponibilidad, subred. Los dos exportadores de diagramas consumen la misma disposición. La misma entrada da el mismo dibujo, así que nada se mueve entre dos ejecuciones salvo que se haya movido la red, y una diferencia significa algo.
Exportación. XML de mxGraph con las formas mxgraph.aws4 para draw.io, un paquete Lucid Standard Import para Lucid, y el inventario en JSON, Markdown y HTML.
Las decisiones que llevaron tiempo
Flujos numerados. Todas las flechas son del mismo gris, y unos discos numerados distinguen el tráfico. Cada tipo de tráfico conserva su número en todas las páginas: 1 entrada desde Internet, 2 salida por NAT, 3 attachment de Transit Gateway, 4 Direct Connect o VPN, 5 peering de VPC, 6 lista de prefijos compartida o RAM. Una leyenda enumera los que usa cada página. Los números salen del tipo de cada arista, no del tráfico observado: muestran cómo está construida la red, no lo que transporta, y la documentación lo dice así.
La página global. Todo el parque en una página: cuentas, el hub de Transit Gateway, peerings, gateways de Direct Connect. Todo lo que se referencia pero no pertenece a una cuenta auditada va en su propio grupo discontinuo, por identificador de cuenta externa.
Huecos, no ceros. Una llamada denegada se convierte en un hueco registrado. Donde habría ido un recuento, la página dice not read. Nunca escribe 0, porque un cero parece una respuesta.
Páginas abarrotadas. La disposición es la parte difícil. En una página con 77 API Gateways, dibujar los abanicos de aristas como un bus (un tronco y una rama por icono) la llevó de 97 segundos a menos de uno. --detail simple pliega más de tres recursos de un mismo tipo en una sola tarjeta, como API Gateway ×77; en la misma página pasó de 37 segundos a menos de uno, y la página de 17.700 a 2.660 píxeles de ancho.
Pruébalo en una cuenta sandbox
Necesitas Python 3.12 o superior y una cuenta de AWS que puedas leer.
pipx install vpcatlas
vpcatlas iam-policy > auditor-policy.json # asóciala al rol o usuario que vayas a usar
vpcatlas discover --profile audit --output-dir ./out
vpcatlas serve --cache ./out/vpcatlas-graph.json
Para una prueba rápida en un sandbox también sirve la política gestionada de AWS ReadOnlyAccess, pero lee mucho más de lo que la herramienta necesita; no la dejes en un rol que vaya a quedarse. Las credenciales funcionan como las de la CLI de AWS: un perfil, variables de entorno, SSO o un rol asumido con external ID y MFA.
Obtienes el grafo, el inventario y una carpeta diagrams/. Abre cualquier fichero .drawio en diagrams.net o importa un .lucid con Lucid Standard Import. Empieza por vpcatlas-global.drawio. El panel se abre en http://127.0.0.1:8080 sobre el escaneo que acabas de hacer, sin llamar a AWS otra vez.
Hay un instalador binario que no necesita Python (curl -fsSL https://vpcatlas.com/install.sh | sh, o una línea de PowerShell en Windows) y una imagen Docker, que sirve el panel por defecto:
docker run --rm -p 127.0.0.1:8080:8080 -v "$HOME/.aws:/home/atlas/.aws:ro" \
vpcatlas/vpcatlas serve --host 0.0.0.0 --profile audit
El panel muestra la topología de tu red, así que mantenlo en una red privada, o define VPCATLAS_AUTH_PASSWORD y sírvelo por HTTPS.
Lo que aún no hace
Es una alfa, y los límites están en la documentación.
- Una cuenta por ejecución. Repite
--profileo--role-arnpara fusionar varias en un grafo. Todavía no descubre las cuentas de una AWS Organization; las listas tú. - Una instantánea. Los ficheros describen la red en el momento del escaneo.
- Sin análisis de tráfico. Ni flow logs, ni análisis de alcanzabilidad, ni simulación de rutas.
- Sin contenidos. Ni objetos de S3, ni secretos, ni eventos de log, ni cuerpos de reglas o políticas.
- Servicios sin colector. Global Accelerator, VPC Lattice, IPAM, Network Manager y Cloud WAN, Client VPN y alguno más.
- Solo AWS, y un fichero regenerado sustituye tus ediciones, así que guarda las copias editadas con otro nombre.
Previsto para la v2: topologías de Network Manager y Cloud WAN, trazado de rutas de Direct Connect y VPN, deriva entre dos instantáneas, diferencias de diagramas en pull requests y ejecuciones multicuenta a partir de la lista de AWS Organizations.
Cómo se construye y se publica
Quería poder pedirle a esta herramienta lo que le pido a cualquier otra: ¿de dónde ha salido el binario?
Cada cambio pasa por lint (ruff, actionlint, zizmor), una comprobación de tipos, los tests en Linux, macOS y Windows con un umbral de cobertura, las dos imágenes Docker con pruebas de humo y un análisis con Trivy, y los instaladores en tres sistemas. CodeQL, OpenSSF Scorecard y Dependabot corren cada semana; pip-audit, cada noche.
Una release produce binarios para cinco plataformas, SHA256SUMS, un SBOM e imágenes firmadas y con atestación, y un último trabajo instala la release publicada con los instaladores en vivo. El paquete está en PyPI y la imagen en Docker Hub, para linux/amd64 y linux/arm64. Para comprobar una descarga:
gh attestation verify vpcatlas-X.Y.Z-linux-x86_64.tar.gz --owner karina-pp
Las firmas de imagen y los SBOM empiezan en la 0.4.1, y verificar la firma de una imagen necesita cosign 3 o superior.
Hecha con IA, funciona sin ella
La IA me ayudó a escribir esta herramienta, y prefiero decirlo a fingir lo contrario. La herramienta en sí no necesita nada de eso: ni modelo, ni clave de API, ni cuenta con nadie, ni factura por token, y nada sale de tu red salvo las llamadas a la API de AWS que tú autorizaste. Muchos equipos trabajan en sitios donde las herramientas de IA no están permitidas, o donde nadie las va a pagar. El diagrama no debería depender de eso.
Dónde conseguirla
- Código y releases: https://github.com/karina-pp/vpcatlas
- Web: https://vpcatlas.com
- Documentación: https://vpcatlas.com/docs/
- Docker Hub: https://hub.docker.com/r/vpcatlas/vpcatlas
Tiene licencia MIT. Lo más útil que puedes hacer es ejecutarla en una cuenta sandbox y decirme dónde el dibujo está mal o la lectura es incompleta.