Nadie 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. En alfa, con 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 siempre, el diagrama que existía estaba desactualizado.

A mano, o desde la consola

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: VPC, subredes, enrutamiento, gateways, endpoints, balanceadores, firewalls, el resolver de DNS y lo que se comparte por RAM, más lo que hay delante: Route 53, CloudFront, WAF, ACM y Shield. También lee el cómputo y las bases de datos y el almacenamiento, como RDS, S3 o DynamoDB, para que cada subred muestre lo que corre en ella, y servicios de la cuenta como CloudTrail, GuardDuty o KMS para el inventario.

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 te da tres cosas. Los diagramas: una página global, una página por región y una página por VPC, como ficheros .drawio y .lucid, dibujados con los AWS Architecture Icons y con el layout de la referencia de red multicuenta (landing zone) de AWS Managed Services. Un inventario en JSON, Markdown y HTML, con cada recurso cuenta por cuenta y una sección por cada cuenta externa vinculada a la tuya. Y un panel: vpcatlas serve muestra los mismos diagramas en el navegador, guarda un historial de escaneos y dibuja la diferencia entre dos de ellos, lo añadido en verde y 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, layout y exportación. Cada etapa recibe una entrada y devuelve una salida, y eso es lo que la hace fácil de probar.

Los colectores leen la cuenta, uno por servicio, todos paginados. Las regiones van en paralelo, pero dentro de cada región los colectores van uno detrás de otro para mantener bajo el throttling de la API, y una llamada que falla con AccessDenied se anota y se salta, sin detener nunca la ejecución. Los resultados se convierten en un grafo dirigido de networkx envuelto en modelos de Pydantic, con aristas tipadas (contains, routes_to, attached_to, peered_with, shared_from) y las cuentas externas como nodos propios. Las posiciones se calculan una sola vez, en una cuadrícula determinista: nube, región, VPC, zona de disponibilidad, subred. Los dos exportadores de diagramas dibujan a partir de ese único layout, así que la misma entrada da el mismo dibujo, nada se mueve entre dos ejecuciones salvo que se haya movido la red, y una diferencia significa algo. Los exportadores escriben 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 círculos numerados distinguen los tipos de 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, y la documentación lo dice así.

La página global. Toda la red en una página: cuentas, el hub de Transit Gateway, peerings, gateways de Direct Connect. Lo que aparece citado pero no pertenece a una cuenta auditada va en un recuadro de línea discontinua, uno por cada cuenta externa.

Huecos, no ceros. Una llamada denegada se convierte en un hueco registrado. Donde iría un recuento, la página pone not read (literal, en inglés). Nunca escribe 0, porque un cero parece una respuesta.

Páginas abarrotadas. El layout es donde más tiempo se me fue. Una página de región con 77 API Gateways tardaba 97 segundos en --detail full; dibujar los abanicos de aristas como un bus, un tronco con una rama por icono, la dejó en menos de uno. --detail simple pliega más de tres recursos de un mismo tipo en una sola tarjeta, como API Gateway ×77, y en la misma página pasó de 37 segundos a menos de uno, y de 17.700 a 2.660 píxeles de ancho.

Una página de VPC: subredes, enrutamiento y flujos numerados.

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 permanente. 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.

• Las cuentas se listan a mano. Repite --profile o --role-arn para fusionar varias cuentas 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 el contenido de las 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, comprobación de tipos, tests en Linux, macOS y Windows, las dos imágenes Docker con pruebas de humo y análisis, y los instaladores en tres sistemas. CodeQL, OpenSSF Scorecard y Dependabot corren cada semana; pip-audit, cada noche. La lista completa, y por qué está cada comprobación, está en el post del CI/CD.

Una release produce binarios para hasta cinco plataformas, SHA256SUMS, un SBOM e imágenes firmadas y con atestación, y un último job instala la release publicada con los instaladores que sirve la web. 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 que abrir en ningún sitio, ni factura por token, y nada sale de tu red salvo las llamadas a la API de AWS que tú autorizaste. Hay equipos que no pueden usar herramientas de IA en el trabajo, o que no las van a pagar. Siguen necesitando el diagrama, así que la herramienta no depende de ninguna.

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 está mal el dibujo o dónde la lectura se queda corta.