DEV Community: Karina Pérez

Un servicio en el centro: páginas de Transit Gateway, grupos de seguridad y API Gateway

Karina Pérez — Tue, 20 Oct 2026 05:55:13 +0000

Cómo VPC Atlas 0.9.0 dibuja un servicio por página, con sus tablas y hallazgos, y lo que esas páginas todavía no cuentan.

Las preguntas llegaban de una en una

En una revisión reciente de la red, cada pregunta trataba de un solo servicio. ¿A dónde va esta ruta del Transit Gateway? ¿Qué security group está abierto al mundo y cuál no tiene nada asociado? ¿Dónde acaba cada ruta de esta API? VPC Atlas contesta con la página de región, y la página de región lo dibuja todo. La respuesta a cada una de esas preguntas está ahí, pero desparramada por toda la página.

La versión 0.9.0, publicada el 20 de octubre de 2026, añade --focus: una página por servicio, unas tablas junto al inventario y tres hallazgos que la herramienta marca en esas páginas y tablas. Hay además un cambio pequeño que no tiene que ver con focus: las páginas de VPC ahora muestran en el subtítulo las IP libres de cada subnet, como en 10.0.1.0/24 | 251 free IPs.

La opción

pipx install vpcatlas        # o: curl -fsSL https://vpcatlas.com/install.sh | sh
vpcatlas discover -r eu-west-1 --focus tgw,sg,apigw --output-dir vpcatlas-out

--focus VIEW funciona en discover, inventory, diagram y serve. Se puede repetir o separar las vistas con comas. Hay tres, y se aceptan alias como transit-gateway y api-gateway.

tgw escribe una página por Transit Gateway, tuyo o compartido contigo, con sus tablas de rutas, sus rutas y sus attachments (uno compartido se dibuja con lo que tus credenciales pueden leer, ver los límites más abajo). sg escribe una página por VPC, con sus security groups, sus reglas y lo que tienen asociado. apigw escribe una página por región, con sus API, endpoints, dominios y destinos de integración. Las páginas salen en draw.io y Lucid como diagrams/vpcatlas-focus-<view>-<id>.<ext>, con el mismo motor de layout que las demás (páginas focus).

Con --focus, --level genera por defecto solo las páginas focus; si le pasas --level account, vpc o all, se añaden esas páginas. Sin --focus no cambia nada. --detail no toca una página focus, y --tag reduce el grafo antes, así que un recurso que --tag deja fuera tampoco sale en una página focus.

En discover y inventory, --focus escribe además seis tablas junto al inventario: tgw-attachments, tgw-routes, sg-rules, sg-attachments, apigw-apis y apigw-integrations. Cada una es un fichero vpcatlas-focus-<table> en todos los formatos de inventario que hayas elegido (json, md, html, csv). El JSON lleva el id de esquema vpcatlas-focus/1, y las filas van ordenadas para que el mismo grafo dé siempre los mismos bytes. Las columnas están en la sección de tablas focus de la documentación.

Tres hallazgos aparecen en las páginas y en las tablas. Los textos de las tarjetas los imprime la herramienta en inglés, tal cual:

open_ingress:<proto>/<ports>, en un security group abierto al mundo (orígenes 0.0.0.0/0 o ::/0) en un puerto que no sea el 80 ni el 443. La tarjeta dice ! open to the world: tcp 22.
unused, en un grupo que nada usa y que ninguna regla nombra. La tarjeta dice ! not attached.
default_endpoint_open, en una API con dominio propio cuyo endpoint execute-api por defecto sigue activo. La tarjeta dice ! default endpoint open.

Hay una cuarta marca, en la página del Transit Gateway. Un peering que nadie ha aceptado aparece como pending_acceptance en la tabla de attachments, y su estado va entre paréntesis en la línea que lo une a su caja.

unused no se marca si un servicio que lleva security groups quedó fuera del escaneo con --exclude-services, o no se pudo leer. Un grupo que parece sin uso solo porque el escaneo nunca miró Lambda ni ECS sería una falsa alarma, y prefiero que la herramienta calle a que marque algo equivocado.

Lo que medí

Las cifras salen de la cuenta simulada del repositorio (demo/fake_aws.py, moto 5.2.4, la biblioteca de Python que imita AWS, detrás de un shim pequeño), en eu-west-1, con la 0.9.0 ya publicada. Amplié la cuenta para esta versión, de modo que las tres vistas tuvieran algo que enseñar. Ahora tiene una instancia bastion en una subnet pública con un grupo bastion (SSH abierto al mundo), un grupo legacy-app con RDP abierto al mundo y nada asociado, una API HTTP prod-http y una API REST partner-rest, una VPN dc-vpn conectada al Transit Gateway hub, un peering hub-frankfurt, que nadie ha aceptado, con un Transit Gateway de eu-central-1 en otra cuenta, y una segunda tabla de rutas, hub-partners.

vpcatlas discover -r eu-west-1 --focus tgw,sg,apigw --output-dir vpcatlas-out encuentra 113 recursos y 0 incidencias (ninguna llamada denegada ni fallida), y escribe 5 páginas focus: 1 del Transit Gateway, 3 de security groups (la cuenta tiene 3 VPC) y 1 con las API de la región. Las seis tablas tienen 7 filas en tgw-routes, 4 en tgw-attachments, 20 en sg-rules, 31 en sg-attachments, 2 en apigw-apis y 4 en apigw-integrations.

El Transit Gateway hub (ASN 64512) tiene 4 attachments: la VPC prod, la VPC shared-services, la VPN dc-vpn y el peering, que está en estado pendingAcceptance y lleva el hallazgo pending_acceptance. Su tabla de rutas por defecto tiene 6 rutas: 0.0.0.0/0 → shared-services, 10.0.0.0/16 → prod, 10.1.0.0/16 → shared-services, 10.20.0.0/16 → el peering de Frankfurt, 10.99.0.0/16 como blackhole y 172.16.0.0/12 → dc-vpn. La segunda tabla, hub-partners, tiene una ruta, 10.0.0.0/16 → prod, y el peering está asociado a ella.

El Transit Gateway hub de la cuenta simulada: sus dos tablas de rutas a la izquierda, sus cuatro attachments a la derecha y el peering sin aceptar con su estado entre paréntesis.

«¿A dónde va esta ruta?» ahora es una tarjeta a la izquierda y una línea hasta una caja a la derecha.

En la VPC prod hay 6 security groups (web, app, db, bastion, legacy-app y default) y 15 filas de reglas. bastion lleva open_ingress:tcp/22. legacy-app lleva open_ingress:tcp/3389 y unused. De las 31 filas de sg-attachments, 12 son via_eni, 9 de ellas del grupo default: cuando solo una interfaz de red delata que un grupo está asociado, la página y la tabla nombran la interfaz, no el recurso que hay detrás. La VPC shared-services tiene 2 grupos y 4 reglas, y la tercera VPC 1 grupo y 1 regla.

La parte de arriba de la página de security groups de la VPC prod. La página es alta, con una tarjeta por grupo y todos los recursos asociados, así que esto es un recorte. La página completa está a un clic.

Cada tarjeta enseña las primeras ocho reglas de entrada y las primeras cuatro de salida de su grupo. Una regla que nombra a otro grupo de la VPC es una línea entre las dos tarjetas, rotulada con el protocolo y los puertos: app acepta el 22 desde bastion, y legacy-app acepta el 8080 desde web.

La región tiene dos API. prod-http es una API HTTP en api.vpcatlas.com con el endpoint por defecto todavía activo, así que lleva default_endpoint_open, y tiene un VPC link, prod-link. partner-rest es una API REST en partners.vpcatlas.com con el endpoint por defecto desactivado y una web ACL regional, prod-api, en su stage. apigw-integrations tiene 4 filas: GET /orders +1 hacia la Lambda prod-api (dos rutas que comparten una integración son una sola fila, y el +1 cuenta la otra), ANY /app/{proxy+} por el VPC link prod-link hasta el balanceador de carga prod-web, GET /status hacia https://status.partner.example/health y POST /orders hacia la Lambda prod-api.

Las API de eu-west-1: prod-http lleva la línea ! default endpoint open, y a la derecha están la Lambda, el VPC link con su balanceador y el host externo.

Las rutas que no llevaban a ningún sitio

Mientras preparaba estas figuras, las rutas del hub salieron sin destino. Todas decían → -.

El producto pide a AWS las rutas de cada tabla con SearchTransitGatewayRoutes y lee el attachment de cada ruta de la respuesta. El simulador (moto) guarda el attachment de una ruta como un único objeto, mientras que la API real devuelve una lista, así que su serializador lo perdía y cada ruta salía con la lista de attachments vacía. En una cuenta real, las rutas ya tenían su destino desde el principio.

El límite está en el simulador, y ahí lo arreglé: antes de arrancar moto, el script de la demo (demo/fake_aws.py) envuelve la llamada que crea una ruta para que el attachment se guarde como lista.

Un mock que responde con la forma correcta y el contenido equivocado se caza peor que uno que falla, y lo cazaron las tablas: una columna entera de attachment_ids vacíos en tgw-routes salta a la vista más que una flecha que acaba en un guion en una página.

Con un grafo guardado y en el dashboard

--focus sobre un grafo guardado no necesita ninguna llamada a AWS:

vpcatlas diagram --cache vpcatlas-out/vpcatlas-graph.json --focus tgw,apigw

En el dashboard, vpcatlas serve --focus ... o la variable VPCATLAS_FOCUS, separada por comas, añade un tercer grupo a la barra lateral, llamado «Focus views». /api/status informa de las vistas activas en filters.focus. Docker Compose pasa VPCATLAS_FOCUS tal cual, y el chart de Helm acepta config.focus como lista. El resto está en la documentación del dashboard.

Lo que no hace

Una página focus no tiene capa de cambios en el dashboard: «View changes on diagram» la salta.
Una vista sin nada que enseñar no escribe página. Sin Transit Gateway no hay página tgw, y sin API no hay página apigw.
Un Transit Gateway compartido por una cuenta que no has escaneado se dibuja con lo que tus credenciales pueden leer: el gateway con su dueño y tus attachments a él. Y una tarjeta de tabla de rutas lista como mucho 12 rutas y termina con +N more; si AWS anuncia más rutas de las que devuelve, la tarjeta termina con (routes truncated by the scan) y routes_truncated vale yes en tgw-routes. La tabla tiene todas las rutas que el escaneo leyó.
Un grupo que solo delata una interfaz se lista a través de esa interfaz (via_eni).
En la página de API, un balanceador al que se llega por un VPC link y que además es destino directo de otra integración se dibuja una sola vez, y su arista cruza la columna de destinos. Lo dejo para la 0.9.1.

Un hallazgo como open_ingress no siempre es un problema: el bastion de las figuras está abierto en el 22 a propósito.

Dime qué vista toca ahora

La opción está en la documentación del CLI, el historial de versiones en el changelog, y el paquete en PyPI. ¿Qué vista querrías después: balanceadores de carga, VPC endpoints, algo que sigues buscando por toda la página de región? Y ¿la regla unused te parece acertada para tus cuentas, o tienes a propósito grupos que nada usa? Dímelo.

One service at the centre: Transit Gateway, security group and API Gateway pages

Karina Pérez — Tue, 20 Oct 2026 05:54:34 +0000

How VPC Atlas 0.9.0 draws one service per page, with its tables and findings, and what those pages still leave out.

Why a page per service

In a recent network review the questions were about one service at a time. Where does this Transit Gateway route go? Which security group is open to the world, and which one is attached to nothing? Where does each route of this API end up? VPC Atlas draws everything on the region page, which answers none of them well: the answer to each is on it somewhere, spread across the whole page.

Version 0.9.0, published on 20 October 2026, adds --focus: a page per service, two tables per view next to the inventory, and three findings the tool raises on those pages and tables. One small change isn't about focus: the pages of a VPC now show the free IPs of each subnet in its subtitle, as in 10.0.1.0/24 | 251 free IPs.

The option

pipx install vpcatlas        # or: curl -fsSL https://vpcatlas.com/install.sh | sh
vpcatlas discover -r eu-west-1 --focus tgw,sg,apigw --output-dir vpcatlas-out

--focus VIEW works on discover, inventory, diagram and serve. You can repeat it or separate the views with commas. There are three views, and aliases such as transit-gateway and api-gateway are accepted.

tgw writes one page per Transit Gateway, your own or one shared with you, with its route tables, routes and attachments (a shared one is drawn from what your credentials can read, see the limits below). sg writes one page per VPC, with its security groups, their rules and what they're attached to. apigw writes one page per region, with its APIs, endpoints, domains and integration targets. The pages come out in draw.io and Lucid as diagrams/vpcatlas-focus-<view>-<id>.<ext>, drawn by the same layout engine as the other pages (focus pages).

With --focus, --level defaults to the focus pages only; --level account, vpc or all adds those pages. Without --focus nothing changes. --detail doesn't change a focus page, and --tag narrows the graph first, so a resource the rules drop isn't on a focus page either.

On discover and inventory, --focus also writes six tables next to the inventory: tgw-attachments, tgw-routes, sg-rules, sg-attachments, apigw-apis and apigw-integrations. Each one is a file called vpcatlas-focus-<table> in every inventory format you selected (json, md, html, csv). The JSON has the schema id vpcatlas-focus/1, and rows are sorted so the same graph gives the same bytes. The columns are in the focus tables section of the docs.

Three findings appear on the pages and in the tables:

open_ingress:<proto>/<ports>, on a security group that admits the world (sources 0.0.0.0/0 or ::/0) on a port other than 80 or 443. The card reads ! open to the world: tcp 22.
unused, on a group that nothing uses and no rule names. The card reads ! not attached.
default_endpoint_open, on an API with a custom domain whose default execute-api endpoint is still enabled. The card reads ! default endpoint open.

A fourth mark is on the Transit Gateway page. A peering attachment that nobody accepted shows pending_acceptance in the attachments table, and its state in brackets on the line to its box.

unused isn't raised when a service that carries security groups was left out of the scan with --exclude-services, or couldn't be read. A group that looks unused only because the scan never looked at Lambda or ECS would be a false alarm, and I'd rather the tool stay quiet than raise a wrong flag.

What I measured

The figures come from the simulated account of the repository (demo/fake_aws.py, built on moto 5.2.4, the Python library that mocks AWS, behind a small shim), in eu-west-1, with the released 0.9.0. I grew the account for this release so the three views had something to show. It now has a bastion instance in a public subnet with a group bastion (SSH open to the world), a group legacy-app with RDP open to the world and nothing attached to it, an HTTP API prod-http and a REST API partner-rest, a VPN dc-vpn attached to the Transit Gateway hub, a peering hub-frankfurt that nobody has accepted, to a Transit Gateway in eu-central-1 of another account, and a second route table hub-partners.

vpcatlas discover -r eu-west-1 --focus tgw,sg,apigw --output-dir vpcatlas-out finds 113 resources and 0 issues (no call was denied or failed), and writes 5 focus pages: 1 for the Transit Gateway, 3 for security groups (the account has 3 VPCs) and 1 for the APIs of the region. The six tables have 7 rows in tgw-routes, 4 in tgw-attachments, 20 in sg-rules, 31 in sg-attachments, 2 in apigw-apis and 4 in apigw-integrations.

On the Transit Gateway page, the gateway hub (ASN 64512) has 4 attachments: the VPC prod, the VPC shared-services, the VPN dc-vpn and the peering, which is in state pendingAcceptance and carries the mark pending_acceptance. Its default route table has 6 routes: 0.0.0.0/0 → shared-services, 10.0.0.0/16 → prod, 10.1.0.0/16 → shared-services, 10.20.0.0/16 → the Frankfurt peering, 10.99.0.0/16 as a blackhole, and 172.16.0.0/12 → dc-vpn. The second table, hub-partners, has one route, 10.0.0.0/16 → prod, and the peering is associated to it.

The Transit Gateway hub of the simulated account: its two route tables on the left, its four attachments on the right, and the unaccepted peering with its state in brackets.

The VPC prod has 6 groups (web, app, db, bastion, legacy-app and default) and 15 rule rows. bastion carries open_ingress:tcp/22. legacy-app carries open_ingress:tcp/3389 and unused. Of the 31 rows in sg-attachments, 12 are via_eni, 9 of them on the group default: when only a network interface shows that a group is attached, the page and the table name the interface, not the resource behind it. The VPC shared-services has 2 groups and 4 rules, and the third VPC 1 group and 1 rule.

The top of the page of the security groups of VPC prod. The page is tall, with a card per group and every attached resource, so this is a crop. The full page has the rest.

Each card shows the first eight inbound and four outbound rules of its group. A rule that names another group of the VPC is a line between the two cards, labelled with the protocol and the ports: app accepts 22 from bastion, and legacy-app accepts 8080 from web.

The region has two APIs. prod-http is an HTTP API on api.vpcatlas.com whose default endpoint is still enabled, so it carries default_endpoint_open, and it has a VPC link prod-link. partner-rest is a REST API on partners.vpcatlas.com with the default endpoint disabled and a regional web ACL prod-api on its stage. apigw-integrations has 4 rows: GET /orders +1 to the Lambda prod-api (two routes that share one integration are one row, and the +1 counts the other), ANY /app/{proxy+} through the VPC link prod-link to the load balancer prod-web, GET /status to https://status.partner.example/health, and POST /orders to the Lambda prod-api.

The APIs of eu-west-1: prod-http carries the line ! default endpoint open, and to the right are the Lambda, the VPC link with its load balancer and the external host.

The routes that pointed nowhere

While I was making these figures, the routes of the hub came out with no target. Every route read → -.

The product asks AWS for the routes of each route table with SearchTransitGatewayRoutes, and it reads the attachment of every route in the answer. moto stores the attachment of a route as a single object where the real API returns a list, so its serializer dropped it, and every route came back with an empty list of attachments. Against a real account, the routes had their targets all along.

The limit is in the simulator, so the fix went there: before moto starts, the demo script (demo/fake_aws.py) wraps the call that creates a route so the attachment is stored as a list.

A mock that answers with the right shape and the wrong content is harder to catch than one that fails, and it was the tables that caught it: a whole column of empty attachment_ids in tgw-routes is harder to skim past than an arrow to a dash on a page.

Cache and dashboard

--focus on a saved graph needs no AWS call:

vpcatlas diagram --cache vpcatlas-out/vpcatlas-graph.json --focus tgw,apigw

In the dashboard, vpcatlas serve --focus ... or the variable VPCATLAS_FOCUS, comma separated, adds a third sidebar group called "Focus views". /api/status reports the active views under filters.focus. Docker Compose passes VPCATLAS_FOCUS through, and the Helm chart takes config.focus as a list. The dashboard docs have the rest.

What it doesn't do

A focus page has no layer of changes in the dashboard: "View changes on diagram" skips it.
A view with nothing to show writes no page. With no Transit Gateway there's no tgw page, and with no API there's no apigw page.
A Transit Gateway shared by an account you didn't scan is drawn from what your credentials can read: the gateway with its owner and your attachments to it. And a route table card lists at most 12 routes and ends in +N more; when AWS reports more routes than it returns, the card ends in (routes truncated by the scan) and routes_truncated is yes in tgw-routes. The table has every route the scan read.
A group that only an interface reveals is listed through that interface (via_eni).
On the API page, a load balancer reached through a VPC link that is also the direct target of another integration is drawn once, and its edge crosses the column of targets. I've left that for 0.9.1.

A hit isn't always a problem: the bastion in the figures is open on 22 on purpose.

Tell me which view is next

The option is in the CLI docs, the version history in the changelog, and the package on PyPI. Which view would you want next: load balancers, VPC endpoints, something else you keep chasing across a region page? And is the unused rule right for your accounts, or do you keep groups on purpose that nothing uses? Tell me.

Una cuenta de AWS, varios entornos y los tags como único mapa

Karina Pérez — Mon, 19 Oct 2026 11:24:29 +0000

Cómo VPC Atlas dibuja y hace el inventario de un entorno de una cuenta de AWS compartida con su nuevo filtro por tag, y qué deja fuera.

Cuando la cuenta es toda la empresa

Muchos equipos no reparten su AWS en cuentas como hacen los diagramas de referencia. No lo defiendo: una cuenta por entorno es el consejo habitual. Esto es para las cuentas que ya existen. Una sola cuenta guarda prod, staging y un sandbox, y a veces varios equipos además. Lo que los distingue es un tag: Environment=prod, Team=payments. Si el etiquetado es coherente, los tags son el único mapa de qué pertenece a qué.

Eso es incómodo para una herramienta que dibuja redes. VPC Atlas toma la cuenta como unidad y dibuja lo que encuentra, región por región. En una cuenta compartida eso significa prod junto a staging junto al sandbox, en una sola página. La página crece y dice poco: preguntabas por prod y la respuesta llega mezclada con el resto. VPC Atlas también escribe una página por VPC, y eso basta cuando cada entorno tiene la suya. No basta cuando dos entornos comparten VPC, ni cuando quieres que la página de región, el inventario y el dashboard salgan reducidos también.

La cuenta entera en una página: tres VPC, el hub, la VPN, el peering y la fila de edge.

La versión 0.8.0 añade --tag. Te da el diagrama y el inventario de un entorno de una cuenta compartida, sin mover ni un solo recurso. Aquí cuento la opción, dos decisiones de diseño (una con un bug que encontré al preparar estas figuras), lo que desaparece bajo el filtro y cómo funciona con un grafo guardado y con el dashboard. La parte que yo leería dos veces es la que explica lo que desaparece. Hace falta la 0.8.1 o posterior; el motivo está en la historia de más abajo.

La opción

pipx install vpcatlas        # o: curl -fsSL https://vpcatlas.com/install.sh | sh
vpcatlas discover -r eu-west-1 --tag Environment=prod

--tag CLAVE=VALOR conserva los recursos que llevan ese tag con ese valor. --tag CLAVE conserva los que llevan el tag con cualquier valor. La opción se puede repetir, y entonces deben cumplirse todas las reglas a la vez (un AND). En el valor, * y ? son comodines. Claves y valores se comparan tal cual, mayúsculas incluidas, de modo que environment=prod no encuentra nada en una cuenta que usa Environment=prod. El valor se corta en el primer =.

Tres formas:

vpcatlas discover --tag Environment=prod --tag Team=payments
vpcatlas discover --tag 'Name=web-*'
vpcatlas discover --tag Owner

La primera es un equipo dentro de un entorno, la segunda una convención de nombres, la tercera todo lo que tiene dueño, sea cual sea. La opción funciona en discover, inventory, diagram y serve (documentación). Primero se excluyen los servicios con --exclude-services (la opción que ya existía para dejar fuera servicios enteros), y después las reglas de tag deciden qué se queda.

Lo que medí

Las cifras salen de la cuenta simulada de los artículos anteriores, en eu-west-1, creada con moto, la biblioteca de Python que imita AWS. La VPC prod (10.0.0.0/16) tiene nueve subnets en tres zonas, NAT gateways, un balanceador de carga, tres grupos de una sola instancia, endpoints, mount targets de EFS, una instancia de RDS, un clúster de ElastiCache prod-cache, una Lambda prod-api y un clúster de ECS prod con el servicio prod-worker. A su lado hay una VPC de servicios compartidos con endpoints y una regla de Route 53 Resolver, una tercera VPC, un Transit Gateway hub, una VPN a una oficina, un peering con una VPC de otra cuenta, y los servicios de edge y de cuenta (CloudFront, la hosted zone, el certificado, Shield, WAF, S3, DynamoDB, CloudTrail, Config, GuardDuty y otros).

Los tags siguen una convención: la mayoría de los recursos de prod llevan Environment=prod y los compartidos Environment=shared. El clúster de ECS prod y su servicio prod-worker, la web ACL, el hub, la VPN, el customer gateway de la oficina, las interfaces de red, las ACL de red y las listas de prefijos no llevan ningún tag Environment.

vpcatlas discover -r eu-west-1 --output-dir vpcatlas-all encuentra 100 recursos y 0 incidencias. Después, sobre el grafo guardado:

vpcatlas inventory --cache vpcatlas-all/vpcatlas-graph.json --tag Environment=prod --format csv --output-dir vpcatlas-prod

Eso escribe 34 filas de 100: 1 de 3 VPC, 9 de 14 subnets, 5 de 9 tablas de rutas, 3 de 7 security groups, los 3 grupos de instancias, los 3 NAT gateways, los 3 endpoints, y uno de cada para el balanceador, el target group, la instancia de RDS, el sistema de ficheros EFS, el internet gateway, el virtual private gateway y el peering.

El diagrama sale del mismo grafo guardado y de la misma regla:

vpcatlas diagram --cache vpcatlas-all/vpcatlas-graph.json --tag Environment=prod --output-dir vpcatlas-prod

La misma cuenta con --tag Environment=prod: 34 de los 100 recursos, todos con Environment=prod, más el marco del que cuelgan.

El peering está porque lleva Environment=prod él mismo; el dibujo lo cuelga de la VPC prod. La ejecución filtrada imprime un aviso, y quería que lo hiciera: «Working from a partial graph: only resources matching Environment=prod are kept (--tag).»

Conservar el marco

La forma obvia de filtrar es tirar todo lo que no coincide. Pero un NAT gateway sin subnet, sin VPC y sin región no tiene dónde ponerse, y no se puede dibujar. Así que un recurso que se queda conserva su marco: su cuenta, su región, y la VPC y las subnets de las que cuelga. Una subnet que coincide trae consigo su VPC, tenga tag o no.

La dirección contraria también pedía una decisión, y elegí la más estricta. Una VPC que coincide no arrastra sus subnets ni sus cargas de trabajo; tienen que coincidir por sí mismas. Si una VPC lleva Environment=prod y una de sus subnets Environment=staging, la subnet de staging se queda fuera del diagrama de prod, salvo que dentro haya algo con tag prod: entonces vuelve como marco de ese recurso. Prefiero un diagrama demasiado pequeño a uno que incluya staging sin avisar, que es justo lo que esta opción quiere evitar.

Los grupos de instancias que desaparecieron

VPC Atlas no dibuja las instancias EC2 una a una. Las dibuja en grupos: por Auto Scaling group, por Name o por subnet. Había que decidir qué tags lleva un grupo. En la 0.8.0 un grupo solo tenía su tag Name, o los tags de su Auto Scaling group.

Lo descubrí preparando las figuras de este artículo. Lancé --tag Environment=prod contra la cuenta simulada esperando la VPC prod con sus tres instancias, y las instancias no estaban: 3 de 3 grupos fuera. Las instancias llevan Environment=prod; los grupos no, porque un grupo solo tenía su nombre. El filtro hizo lo que yo había escrito, y lo que yo había escrito tiraba todo grupo de instancias cuyos tags estaban en las instancias y no en su nombre ni en su Auto Scaling group.

El arreglo está en la 0.8.1, publicada el mismo día. Ahora un grupo lleva los tags que todos sus miembros comparten con el mismo valor, más los del propio Auto Scaling group y su Name. Un tag que solo tienen algunos miembros no va en el grupo, porque no puedo llamar prod a un grupo si una de sus instancias no lo es. Con la 0.8.1 los tres grupos han vuelto, y la segunda figura se dibujó con esa versión. Si ejecutaste --tag con la 0.8.0 en una cuenta con instancias, vuelve a escanear con la 0.8.1: un fichero de grafo guardado con la 0.8.0 conserva los tags antiguos de los grupos, y --cache no los recupera.

Lo que desaparece, y por qué

De los 100 recursos, 66 quedan fuera. Quince están en tipos que se conservan en parte: 2 de 3 VPC, 5 de 14 subnets, 4 de 9 tablas de rutas y 4 de 7 security groups (5 de los 15 llevan Environment=shared y los otros 10 no llevan ningún tag). Los otros 51 son de 24 tipos que desaparecen por completo, y se reparten en tres grupos.

El grupo más grande son recursos que no llevan tag Environment en esta cuenta, así que el filtro hace bien en descartarlos: los servicios de edge (CloudFront, la hosted zone, el certificado, Shield), CloudTrail, Config y GuardDuty, el Transit Gateway con sus attachments y su tabla de rutas, la VPN y el customer gateway, 19 interfaces de red, 3 ACL de red y 6 listas de prefijos. Son huecos en el etiquetado de la cuenta. Por eso prod-vgw en la segunda figura acaba en el borde de la VPC: su conexión VPN no lleva tag. Un rótulo como +4 ENIs en la cabecera de una subnet es solo un contador que lleva la propia subnet; las interfaces en sí han desaparecido. El filtro solo muestra esos huecos como una ausencia; para listarlos, escribe el CSV con y sin --tag y compara la columna id.

Después vienen los servicios cuyos colectores no registran ningún tag: S3 y DynamoDB, y también WAFv2 (la web ACL) y Route 53 Resolver (los endpoints y la regla). La herramienta no puede saber si alguno lleva tag, así que ninguno coincide. Los stubs (recursos de otras cuentas a los que se refiere la tuya) y los resúmenes de cuenta están en la misma situación, aunque ninguno está entre estos 100.

El último grupo es un límite de la propia opción. Dos recursos están etiquetados Environment=prod en AWS y aun así desaparecen: la Lambda prod-api y el clúster de ElastiCache prod-cache. Sus colectores todavía no leen tags. Así que un diagrama de prod hecho con --tag no tiene una función ni una caché que cualquiera del equipo llamaría prod. El clúster de ECS prod y su servicio prod-worker también desaparecen, pero en esta cuenta no llevan tag Environment (el clúster solo tiene Name), así que no sirven para enseñar este hueco. La página de cobertura recoge este hueco de la herramienta. Mientras esos colectores no lean tags, trata el diagrama como la red etiquetada y revisa a mano esos servicios.

Caché, dashboard y una regla sobre el fichero

Un escaneo con --tag guarda el grafo reducido y anota las reglas en sus metadatos. Una ejecución posterior con --cache sobre ese fichero imprime el aviso de grafo parcial y nombra las reglas, para que medio grafo no pase por uno entero. Una ejecución con --cache y --tag reduce el grafo cargado de la misma manera y deja el fichero como estaba. La consecuencia práctica: si quieres prod hoy y el sandbox mañana, escanea una vez sin --tag y filtra el grafo guardado cada vez. Escanea con --tag solo cuando quieras el fichero reducido.

El dashboard toma las mismas reglas de --tag en vpcatlas serve, o de la variable VPCATLAS_TAGS, separadas por comas, por ejemplo Environment=prod,Owner. Un valor que contenga una coma necesita la línea de comandos. /api/status lista las reglas activas en filters.tags. Docker Compose pasa VPCATLAS_TAGS tal cual, y el chart de Helm acepta config.tags como lista. Con eso es posible un dashboard por entorno con las mismas credenciales, cada uno arrancado con su propia VPCATLAS_TAGS. El resto está en la documentación del dashboard.

Lo que no hace

Filtra solo por tags. Una subnet sin tag se queda fuera del diagrama de prod aunque todas las de al lado entren, salvo que contenga un recurso que coincida.
No puede usar los tags que los colectores no leen: por ahora, los de Lambda, ECS, ElastiCache, WAFv2, Route 53 Resolver, S3 y DynamoDB. Los tags salen de las mismas llamadas describe que los colectores ya hacen. La API de Resource Groups Tagging cubriría el resto en una sola llamada; todavía no está conectada.
No hay modo que ignore mayúsculas, así que dos grafías de un mismo entorno son dos entornos.
Reduce el grafo después del escaneo. El escaneo sigue leyendo toda la cuenta con los mismos permisos, así que --tag es una vista, no un límite.
Los 66 recursos que quedaron fuera son lo que pierde esta cuenta simulada; en la tuya serán otros.

Dime qué falta

La opción está en la documentación del CLI, el historial de versiones en el changelog, y el paquete en PyPI. Si trabajas con una cuenta compartida, me gustaría saber qué tag usas de verdad para repartirla, y si un AND de reglas CLAVE=VALOR te basta o necesitabas un OR. Dime qué servicio buscaste en un diagrama filtrado y no encontraste, para que lea sus tags a continuación. Y si te serviría que la salida dijera qué recursos dejó fuera el filtro, y si cada uno no tenía tag o está en un servicio cuyos tags todavía no leo, dímelo; hoy no lo dice.

One AWS account, several environments, and tags as the only map

Karina Pérez — Mon, 19 Oct 2026 11:23:19 +0000

How VPC Atlas draws and inventories one environment of a shared AWS account with its new tag filter, and what it leaves out.

When the account is the whole company

Plenty of teams don't split their AWS estate into accounts the way the reference diagrams do. I'm not arguing for it: one account per environment is the usual advice. This is for the accounts that exist. One account holds prod, staging and a sandbox, sometimes several teams as well. What tells them apart is a tag: Environment=prod, Team=payments. If the tagging is consistent, the tags are the only map of what belongs to what.

That's awkward for a tool that draws networks. VPC Atlas takes the account as its unit and draws what it finds, region by region. In a shared account that means prod next to staging next to the sandbox, on one page. The page gets big and says little, because your question was about prod and the answer is mixed in with the rest. VPC Atlas also writes one page per VPC, which is enough when every environment has its own. It isn't when two environments share a VPC, or when you want the region page, the inventory and the dashboard narrowed too.

The whole account on one page: three VPCs, the hub, the VPN, the peering and the edge row.

Version 0.8.0 adds --tag. It gives you the diagram and the inventory of one environment of a shared account, without moving a single resource. This post covers the option, two design decisions (one with a bug I found while making these figures), what disappears under the filter, and how it works with a saved graph and the dashboard. The part I'd read twice is the one about what disappears. You need 0.8.1 or later; the reason is in the story below.

The option

pipx install vpcatlas        # or: curl -fsSL https://vpcatlas.com/install.sh | sh
vpcatlas discover -r eu-west-1 --tag Environment=prod

--tag KEY=VALUE keeps the resources that carry that tag with that value. --tag KEY keeps the ones that carry the tag with any value. The option can be repeated, and then every rule must hold (an AND). In the value, * and ? are wildcards. Keys and values are compared exactly, case included, so environment=prod matches nothing in an account that spells it Environment=prod. The value is split at the first =.

Three shapes:

vpcatlas discover --tag Environment=prod --tag Team=payments
vpcatlas discover --tag 'Name=web-*'
vpcatlas discover --tag Owner

The first is one team inside one environment, the second a naming convention, the third everything that has an owner at all. The option works on discover, inventory, diagram and serve (docs). Services are excluded first, with --exclude-services (the existing option that leaves whole services out), and then the tag rules judge what stays.

What I measured

The figures come from the simulated account of the earlier posts, in eu-west-1, built with moto, the Python library that mocks AWS. The prod VPC (10.0.0.0/16) has nine subnets in three zones, NAT gateways, a load balancer, three single-instance groups, endpoints, EFS mount targets, an RDS instance, an ElastiCache cluster prod-cache, a Lambda prod-api and an ECS cluster prod with the service prod-worker. Next to it sit a shared-services VPC with Route 53 Resolver endpoints and a rule, a third VPC, a Transit Gateway hub, a VPN to an office, a peering to a VPC of another account, and the edge and account services (CloudFront, the hosted zone, the certificate, Shield, WAF, S3, DynamoDB, CloudTrail, Config, GuardDuty and so on).

Tags follow a convention: most prod resources carry Environment=prod, the shared ones Environment=shared. The ECS cluster prod and its service prod-worker, the web ACL, the hub, the VPN, the customer gateway of the office, the network interfaces, the network ACLs and the prefix lists carry no Environment tag.

vpcatlas discover -r eu-west-1 --output-dir vpcatlas-all finds 100 resources and 0 issues. Then, on the saved graph:

vpcatlas inventory --cache vpcatlas-all/vpcatlas-graph.json --tag Environment=prod --format csv --output-dir vpcatlas-prod

That writes 34 rows out of 100: 1 of 3 VPCs, 9 of 14 subnets, 5 of 9 route tables, 3 of 7 security groups, all 3 instance groups, the 3 NAT gateways, the 3 endpoints, and one each of load balancer, target group, RDS instance, EFS file system, internet gateway, virtual private gateway and peering.

The diagram comes from the same saved graph and the same rule:

vpcatlas diagram --cache vpcatlas-all/vpcatlas-graph.json --tag Environment=prod --output-dir vpcatlas-prod

The same account with --tag Environment=prod: 34 of the 100 resources, every one tagged Environment=prod, plus the frame they hang from.

The peering is there because it carries Environment=prod itself; the drawing hangs it from the prod VPC. The filtered run prints a warning, and I wanted it to: "Working from a partial graph: only resources matching Environment=prod are kept (--tag)."

Keeping the frame

The obvious way to filter is to throw away everything that doesn't match. A NAT gateway with no subnet, no VPC and no region has nowhere to sit, though, and can't be drawn. So a kept resource keeps its frame: its account, its region, and the VPC and subnets it hangs from. A subnet that matches brings its VPC along, tagged or not.

The other direction needed a decision too, and I chose the stricter one. A VPC that matches doesn't drag in its subnets or its workloads; they have to match on their own. If a VPC is tagged Environment=prod and one of its subnets Environment=staging, the staging subnet stays out of the prod diagram, unless something tagged prod sits in it: then it comes back as that resource's frame. I'd rather have a diagram that's too small than one that quietly includes staging, which is what the option exists to avoid.

The instance groups that went missing

VPC Atlas doesn't draw EC2 instances one by one. It draws them as groups: by Auto Scaling group, by Name, or by subnet. So I had to decide what tags a group carries. In 0.8.0 a group had only its Name tag, or the tags of its Auto Scaling group.

I found out while making the figures for this post. I ran --tag Environment=prod against the simulated account, expecting the prod VPC with its three instances, and the instances weren't there: 3 of 3 groups gone. The instances carry Environment=prod; the groups didn't, because a group only had its name. The filter did what I'd written, and what I'd written dropped every instance group whose tags sat on the instances and not on the group's name or its Auto Scaling group.

The fix is in 0.8.1, released the same day. A group now carries the tags that every member shares with the same value, plus the Auto Scaling group's own tags and its Name. A tag only some members have isn't on the group, because I can't call the group prod when one of its instances isn't. With 0.8.1 the three groups are back, and the second figure was drawn with that version. If you ran --tag with 0.8.0 on an account with instances, scan again with 0.8.1: a graph file saved by 0.8.0 still has the old group tags, so --cache won't bring the groups back.

What disappears, and why

Of the 100 resources, 66 are gone. Fifteen of them are in types that stay in part: 2 of 3 VPCs, 5 of 14 subnets, 4 of 9 route tables and 4 of 7 security groups (5 of the 15 are tagged Environment=shared, the other 10 carry no tags). The other 51 belong to 24 types that disappear completely, and they fall into three groups.

The biggest group is resources that carry no Environment tag in this account, so the filter is right to drop them: the edge services (CloudFront, the hosted zone, the certificate, Shield), CloudTrail, Config and GuardDuty, the Transit Gateway with its attachments and route table, the VPN and the customer gateway, 19 network interfaces, 3 network ACLs and 6 prefix lists. Those are gaps in the account's tagging. That's why prod-vgw in the second figure ends at the edge of the VPC: its VPN connection carries no tag. A label like +4 ENIs in a subnet header is just a count the subnet carries; the interfaces themselves are gone. The filter shows those gaps only as an absence, so to list them, write the CSV with and without --tag and compare the id column.

Next come services whose collectors record no tags at all: S3 and DynamoDB, and also WAFv2 (the web ACL) and Route 53 Resolver (the endpoints and the rule). The tool can't tell whether any of them is tagged, so none matches. Stubs (resources of other accounts that yours refer to) and the account summaries are in the same position, though none is among these 100.

The last group is a limit of the option itself. Two resources are tagged Environment=prod in AWS and still vanish: the Lambda prod-api and the ElastiCache cluster prod-cache. Their collectors don't read tags yet. So a prod diagram made with --tag lacks a function and a cache that anyone on the team would call prod. The ECS cluster prod and its service prod-worker go too, but in this account they carry no Environment tag (the cluster has only a Name), so they can't show the gap. The coverage page lists this gap in the tool. Until those collectors read tags, treat the diagram as the tagged network and check those services by hand.

Cache, dashboard and a rule about the file

A scan run with --tag saves the narrowed graph, and it records the rules in its metadata. A later --cache run on that file prints the partial-graph warning and names the rules, so a half graph can't pass for a whole one. A --cache run with --tag narrows the loaded graph the same way and leaves the file as it is. The practical consequence: if you want prod today and the sandbox tomorrow, scan once without --tag and filter the saved graph each time. Scan with --tag only when you want the narrow file.

The dashboard takes the same rules from --tag on vpcatlas serve, or from the VPCATLAS_TAGS variable, comma separated, for example Environment=prod,Owner. A value that contains a comma needs the command line. /api/status lists the active rules under filters.tags. Docker Compose passes VPCATLAS_TAGS through, and the Helm chart takes config.tags as a list. That makes one dashboard per environment possible from the same credentials, each started with its own VPCATLAS_TAGS. The dashboard docs cover the rest.

What it doesn't do

It filters on tags only. A subnet with no tag stays out of the prod diagram even if every neighbour is in, unless a resource that matches sits in it.
It can't use tags the collectors don't read: Lambda, ECS, ElastiCache, WAFv2, Route 53 Resolver, S3 and DynamoDB, at the moment. Tags come from the same describe calls the collectors already make. The Resource Groups Tagging API would cover the rest in one call; it isn't wired in yet.
There's no case-insensitive mode, so two spellings of one environment are two environments.
It narrows the graph after the scan. The scan still reads the whole account with the same permissions, so --tag is a view, not a boundary.
The 66 resources that went are what this simulated account loses; yours will differ.

Tell me what's missing

The option is in the CLI docs, the version history in the changelog, and the package on PyPI. If you run a shared account, I'd like to know which tag you actually use to split it, and whether an AND of KEY=VALUE rules is enough or you needed an OR. Tell me which service you looked for in a filtered diagram and didn't find, so I can read its tags next. And if you'd want the output to say which resources the filter left out, and whether each was untagged or in a service whose tags I don't read yet, tell me; today it doesn't.

El inventario de red de AWS, ahora también en CSV para filtrarlo

Karina Pérez — Sun, 18 Oct 2026 23:35:43 +0000

Qué contiene el inventario de VPC Atlas, los cuatro formatos en que sale y por qué hice el CSV con una fila plana por recurso.

El diagrama es la foto, el inventario es la lista

Un diagrama te cuenta cómo es una red. Sirve poco para responder a «qué subnets son públicas en eu-west-1», a «qué ha cambiado desde el mes pasado» o a «mándame todas las VPC con sus CIDR». En una imagen no se puede buscar, y nadie compara dos a ojo con garantías. Para esas preguntas quería una lista: un único documento con todo lo que encontró el escaneo, que una persona pueda filtrar y un script pueda leer.

La foto: la VPC prod de la cuenta simulada, tal como la dibuja VPC Atlas. Cada recurso dibujado aquí es una fila del inventario de más abajo.

VPC Atlas ya escribía ese documento en JSON, Markdown y HTML. La versión 0.7.0 le suma una cuarta forma, el CSV. Aquí cuento qué contiene el inventario, para quién es cada formato, cómo se obtiene, tres maneras de filtrarlo y las decisiones que tomé en el CSV, entre ellas la que te mete un apóstrofo suelto en las celdas.

Qué contiene el documento

El inventario es la cuenta escrita como un árbol. De cada cuenta auditada cuelgan sus regiones. De una región cuelgan sus VPC y los recursos que no están en ninguna VPC, como los Transit Gateways y los peerings. Una VPC contiene sus subnets y los recursos que no están en ninguna subnet, como las tablas de rutas y los security groups. Una subnet contiene lo que se coloca en ella, como los NAT gateways y los balanceadores de carga, y trae su zona de disponibilidad, su CIDR y un nivel: pública cuando la ruta por defecto sale por un internet gateway; si no, privada, aislada o desconocida.

Junto al árbol de red, cada cuenta tiene una capa de servicios en cinco familias: DNS y edge, API y balanceo, cómputo y contenedores, datos y almacenamiento, y servicios de cuenta como CloudTrail y GuardDuty. Cuando el escaneo no pudo leer un valor de los servicios de cuenta, el fichero pone not read. Eso no es lo mismo que cero o no, así que una llamada denegada nunca se lee como una cuenta vacía.

Después vienen las partes que cruzan cuentas. Las cuentas que el escaneo vio pero para las que no tiene credenciales salen como cuentas externas, cada enlace que cruza el límite de una cuenta tiene su propia entrada, y las llamadas que fallaron al descubrir salen como incidencias (issues). Un resumen con los recuentos abre el documento. Todos los recursos llevan los mismos campos: id, nombre, ARN, estado, sus detalles, sus tags, si el dueño es una cuenta que no auditaste y qué cuentas auditadas lo vieron.

Cuatro formatos, cuatro lectores

El JSON, en vpcatlas-inventory.json, es para máquinas y para jq; su identificador de esquema es vpcatlas-inventory/1. El Markdown es para una pull request o una wiki: el mismo documento en tablas, con los detalles cortados a 240 caracteres por celda. El HTML es una sola página autocontenida con un cuadro de búsqueda que filtra las filas por id, nombre, tipo o cuenta, y es el que mandaría a alguien que no va a abrir una terminal. El CSV es para una hoja de cálculo o para csvkit.

Son cuatro versiones de un mismo documento, y el mismo grafo da siempre el mismo documento.

Cómo se obtiene

vpcatlas discover escribe el inventario junto con los diagramas. vpcatlas inventory escanea igual pero no dibuja nada, que es lo que quieres para el anexo de una auditoría o para un job programado:

vpcatlas inventory --profile prod --format json --output-dir out

--format acepta json, md, html, csv o all, repetido o separado por comas, y all son los cuatro. Los ficheros se escriben junto a vpcatlas-graph.json en el directorio de salida, vpcatlas-out por defecto.

La lista: la misma cuenta en CSV, y sus subnets filtradas con csvkit. Grabado contra la cuenta simulada, así que los identificadores son de ejemplo.

El dashboard sirve los mismos cuatro en /export/inventory.json, /export/inventory.md, /export/inventory.html y /export/inventory.csv, y la pestaña de inventario tiene un botón .csv. /export/all.zip trae todo junto: los diagramas, el inventario en los cuatro formatos y graph.json.

La pestaña de inventario del dashboard, con los cuatro formatos a un clic.

Si ya tienes un grafo guardado, no necesitas AWS para nada:

vpcatlas inventory --cache ./out/vpcatlas-graph.json --format csv

Tres maneras de filtrarlo

En una hoja de cálculo, activa el filtro en la fila de cabecera y elige un valor en la columna type, por ejemplo subnet, y luego una región en la columna region. Con eso tienes las subnets de una región.

Con csvkit, la misma pregunta como comando, tal como está en la documentación:

csvgrep -c type -m subnet vpcatlas-out/vpcatlas-inventory.csv | csvcut -c region,vpc_id,id,name,cidr

Con jq, sobre el JSON, las subnets públicas, una por línea con cuenta, región, VPC, subnet, CIDR, zona y nivel. Es la receta de las referencias del agent skill con un select añadido, y INV es la ruta del fichero JSON:

INV=vpcatlas-out/vpcatlas-inventory.json
jq -r '.accounts[] as $a | $a.regions[] as $r | $r.vpcs[] as $v | $v.subnets[]
  | select(.tier == "public")
  | [$a.account_id, $r.region, $v.vpc.id, .subnet.id, .cidr, .availability_zone, .tier] | @tsv' "$INV"

Por qué el CSV es como es

La primera decisión fue la forma. El JSON es un árbol, y un árbol no cabe en una tabla. La respuesta ordenada parecía un fichero por nivel: cuentas, VPC, subnets, cada uno apuntando a su padre por id. No la construí, porque lo primero que se hace con una hoja de cálculo es filtrar, y un filtro trabaja sobre una sola hoja. Con tres ficheros, «todo lo que hay en esta subnet» se convierte en una búsqueda cruzada entre ficheros, que es justo el trabajo que quería ahorrarte.

Así que es una sola tabla, con una fila por recurso y una columna scope que dice dónde está la fila: region, vpc, subnet o service. Los ids de la VPC y de la subnet se repiten en cada fila que cuelga de ellas, de modo que una fila sigue teniendo sentido cuando has filtrado todo lo demás. El precio son 23 columnas. Las filas van en el orden del documento, la fila de una subnet y luego los recursos que hay en ella. Para un recurso de la capa de servicios, family dice a qué familia pertenece.

Con los detalles y los tags pasa lo contrario. Una subnet y un NAT gateway no comparten atributos, así que una columna por atributo daría una tabla muy ancha y casi vacía. Los dos se escriben como clave=valor; clave=valor, en el orden del documento, y a diferencia del Markdown los detalles no se cortan.

La protección de las celdas salió de lo que hay en ellas. Los tags son texto que puede escribir cualquiera con acceso a la cuenta, y una hoja de cálculo ejecuta una celda que empieza por =. Por eso una celda que empieza por =, +, - o @ recibe un apóstrofo delante, y la hoja enseña el texto en vez de ejecutarlo. También cuentan las formas de ancho completo de esos signos, y un tabulador o un retorno de carro delante de uno se quitan antes, para que no pueda esconderlo. La contrapartida es que una celda que empieza por un signo menos recibe también el apóstrofo, sea inofensiva o no. El apóstrofo forma parte del fichero. Quítalo si lees el CSV desde código.

Lo demás es más pequeño. Las líneas terminan en CRLF, como define el formato CSV. La cabecera se escribe siempre, aunque el escaneo no encuentre ningún recurso, así que un script que lee el fichero por nombre de columna nunca se topa con un fichero vacío. Un valor que falta es una celda vacía, y el mismo documento da los mismos bytes, de modo que dos CSV del mismo grafo salen idénticos. El fichero es UTF-8 sin marca de orden de bytes: si una hoja de cálculo muestra mal los acentos, importa el fichero y elige UTF-8. Una hoja también puede leer un id de cuenta de 12 dígitos como número y quitarle los ceros del principio, así que importa esa columna como texto cuando necesites el id exacto.

Lo que no hace

El CSV tiene los recursos y nada más. Las cuentas externas, los enlaces entre cuentas y las incidencias no son filas; están en el JSON y en el Markdown.
El número de filas puede no coincidir con summary.resources del JSON. Una VPC que se mencionó pero que el escaneo nunca describió tiene una fila de relleno en el árbol, y el resumen no la cuenta.
Un escaneo solo puede nombrar lo que ven sus credenciales. VPC Atlas todavía no descubre las cuentas de una AWS Organization: las das tú, repitiendo --profile o --role-arn. Si se ejecuta desde la cuenta de administración, lee Organizations solo para ponerles nombre a las cuentas.
Cada fichero es un escaneo, con la hora de ese escaneo en generated_at. Es una instantánea, no un historial. Para comparar dos momentos guardas dos ficheros de grafo, o dejas que el dashboard registre los escaneos y dibuje la diferencia.

Dime qué falta

El formato está en la documentación del inventario y el comando, en la página de inventory. Si echaste en falta una columna, o acabaste escribiendo a mano un filtro, dime cuál.

The AWS network inventory, now also a CSV you can filter

Karina Pérez — Sun, 18 Oct 2026 23:25:39 +0000

What the VPC Atlas inventory holds, the four formats it comes in, and why I made the CSV one flat row per resource.

The diagram is the picture, the inventory is the list

A diagram tells you what a network looks like. It's a poor answer to "which subnets are public in eu-west-1", to "what changed since last month" or to "send me every VPC with its CIDRs". You can't search a picture, and nobody diffs one by eye with any confidence. For those questions I wanted a list: one document with everything the scan found, that a person can filter and a script can read.

The picture: the prod VPC of the simulated account, as VPC Atlas draws it. Each resource drawn here is one row in the inventory below.

VPC Atlas already wrote that document as JSON, Markdown and HTML. Version 0.7.0 adds a fourth rendering, a CSV. This post covers what the inventory holds, who each format is for, how to get it, three ways to filter it, and the choices I made in the CSV, including the one that puts a stray apostrophe in your cells.

What the document holds

The inventory is the account written as a tree. Under each audited account come its regions. Under a region come its VPCs, plus the resources that sit in no VPC, such as Transit Gateways and peering connections. A VPC holds its subnets and the resources that sit in no subnet, such as route tables and security groups. A subnet holds what's placed in it, such as NAT gateways and load balancers, and carries its Availability Zone, its CIDR and a tier: public when the default route goes to an internet gateway, otherwise private, isolated or unknown.

Next to the network tree, each account has a service layer in five families: DNS and edge, API and load balancing, compute and containers, data and storage, and account services such as CloudTrail and GuardDuty. When the scan couldn't read a value in the account services, the file says not read. That's different from zero or no, so a denied call never reads as an empty account.

Then come the parts that cross accounts. Accounts the scan saw but has no credentials for are listed as external accounts, every link that crosses an account boundary has its own entry, and the calls that failed while discovering are listed as issues. A summary with the counts opens the document. Every resource carries the same fields: id, name, ARN, state, its details, its tags, whether the owner is an account you didn't audit, and which audited accounts saw it.

Four formats, four readers

JSON, in vpcatlas-inventory.json, is for machines and for jq. Its schema id is vpcatlas-inventory/1. Markdown is for a pull request or a wiki: the same document as tables, with the details cut at 240 characters per cell. HTML is a single self-contained page with a search box that filters rows by id, name, type or account, and it's the one I'd send to someone who won't open a terminal. CSV is for a spreadsheet or csvkit.

They're four renderings of one document, and the same graph always gives the same document.

How to get it

vpcatlas discover writes the inventory with the diagrams. vpcatlas inventory scans the same way but draws nothing, which is what you want for an audit attachment or a scheduled job:

vpcatlas inventory --profile prod --format json --output-dir out

--format takes json, md, html, csv or all, repeated or separated with commas, and all is the four. The files land next to vpcatlas-graph.json in the output directory, vpcatlas-out by default.

The list: the same account as a CSV, and its subnets filtered with csvkit. Recorded against the simulated account, so the ids are examples.

The dashboard serves the same four at /export/inventory.json, /export/inventory.md, /export/inventory.html and /export/inventory.csv, and the inventory tab has a .csv button. /export/all.zip holds the lot: the diagrams, the inventory in the four formats, and graph.json.

The inventory tab of the dashboard, with the four formats one click away.

If you already have a saved graph, you don't need AWS at all:

vpcatlas inventory --cache ./out/vpcatlas-graph.json --format csv

Three ways to filter it

In a spreadsheet, turn on the filter on the header row and pick a value in the type column, say subnet, then a region in the region column. That's all it takes to get the subnets of one region.

With csvkit, the same question as a command, from the docs:

csvgrep -c type -m subnet vpcatlas-out/vpcatlas-inventory.csv | csvcut -c region,vpc_id,id,name,cidr

With jq, on the JSON, here are the public subnets, one per line with account, region, VPC, subnet, CIDR, zone and tier. This is the recipe from the agent skill's references with one select added, and INV is the path of the JSON file:

INV=vpcatlas-out/vpcatlas-inventory.json
jq -r '.accounts[] as $a | $a.regions[] as $r | $r.vpcs[] as $v | $v.subnets[]
  | select(.tier == "public")
  | [$a.account_id, $r.region, $v.vpc.id, .subnet.id, .cidr, .availability_zone, .tier] | @tsv' "$INV"

Why the CSV looks the way it does

The first decision was the shape. The JSON is a tree, and a tree doesn't fit in a table. The tidy answer looked like one file per level: accounts, VPCs, subnets, each pointing at its parent by id. I didn't build that, because the first thing anyone does with a spreadsheet is filter, and a filter works on one sheet. With three files, "everything in this subnet" turns into a lookup between files, which is the work I wanted the file to save you.

So it's one table with a row per resource and a scope column that says where the row sits: region, vpc, subnet or service. The VPC and subnet ids are repeated on every row under them, so a row still makes sense after you've filtered the rest away. The price is 23 columns. Rows come in document order, a subnet row and then the resources in it. For a resource of the service layer, family says which one it belongs to.

Details and tags are the opposite problem. A subnet and a NAT gateway don't share attributes, so a column for each would give a very wide table, mostly empty. Both are written as key=value; key=value, in document order, and unlike the Markdown file the details aren't cut.

The cell guard came from what's in the cells. Tags are text that anyone with access to the account can write, and a spreadsheet will run a cell that starts with =. So a cell starting with =, +, - or @ gets a leading apostrophe, which makes the spreadsheet show the text instead of running it. The full-width forms of those signs count too, and a tab or carriage return in front of one is removed first, so it can't hide the sign. The trade-off is that a cell starting with a minus sign gets the apostrophe as well, harmless or not. The apostrophe is part of the file. Strip it if you read the CSV in code.

The rest is smaller. Lines end with CRLF, as the CSV format has it. The header row is always written, even when the scan found no resource, so a script that reads the file by column name never meets an empty file. A missing value is an empty cell, and the same document gives the same bytes, so two CSVs of the same graph compare equal. The file is UTF-8 with no byte order mark: if a spreadsheet shows accents wrongly, import the file and choose UTF-8. A spreadsheet may also read a 12-digit account id as a number and drop its leading zeros, so import that column as text when you need the exact id.

What it doesn't do

The CSV has the resources and nothing else. External accounts, cross-account links and issues aren't rows; they're in the JSON and the Markdown.
The number of rows can differ from summary.resources in the JSON. A VPC that was referenced but never described in the scan has a placeholder row in the tree, and the summary doesn't count it.
A scan can only name what its credentials can see. VPC Atlas doesn't discover the accounts of an AWS Organization yet: you list them yourself, with --profile or --role-arn repeated. When it runs from the management account, it reads Organizations only to put names on accounts.
Each file is one scan, with the time of that scan in generated_at. It's a snapshot, not a history. To compare two moments you keep two graph files, or let the dashboard record the scans and draw the difference.

Tell me what's missing

The format reference is in the inventory docs and the command in the inventory page. If there's a column you needed and didn't find, or a filter you ended up writing by hand, tell me which one.

Qué hace falta para fiarse del binario de una CLI de una sola persona

Karina Pérez — Sun, 18 Oct 2026 20:18:07 +0000

Cómo construí el CI/CD y la cadena de suministro de VPC Atlas, y los comandos para comprobar cada descarga.

Por qué una herramienta pequeña lleva tanto pipeline

La herramienta solo hace llamadas de lectura, pero se ejecuta con credenciales de una cuenta de AWS, así que quien la instala debería saber qué está ejecutando.

Quien hace merge y publica las releases soy yo, y nadie más. CODEOWNERS tiene una sola regla y un solo nombre, el mío. Sin un segundo revisor que pille un error o un atajo, escribí las comprobaciones que haría un revisor y puse a una máquina a ejecutarlas en cada cambio, en público.

Quería que cualquiera que descargue un fichero de la página de releases pudiera averiguar qué workflow lo construyó, y desde qué commit, sin fiarse de mi palabra. Lo que sigue es cada decisión y por qué la tomé. Los motivos sirven para otros proyectos. El YAML solo encaja en el mío.

Cómo está montado el pipeline

Hay cinco workflows. ci se ejecuta en cada pull request y en cada push a main. release se ejecuta cuando subo un tag. CodeQL y OpenSSF Scorecard corren además cada lunes, y las comprobaciones nocturnas, a las 05:00 UTC, vigilan lo que puede romperse sin tocar el código: pip-audit sobre los paquetes instalados, los enlaces de la documentación, un benchmark del layout y un análisis con Trivy de la imagen publicada. Cada job tiene un tiempo máximo. Solo un tag con la forma vX.Y.Z dispara una publicación:

on:
  push:
    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
  workflow_dispatch:

permissions:
  contents: read

Qué se ejecuta en cada cambio

ci tiene nueve jobs y ninguno espera a otro, así que un cambio tarda lo que tarde el más lento. Un push nuevo a la misma rama cancela la ejecución anterior. Los nombres de los jobs son las comprobaciones obligatorias de main, y no se aceptan commits directos a main.

Una ejecución de ci, sobre el commit que publicó la 0.7.0: nueve jobs y ninguna flecha entre ellos.

Lint y tipos. ruff y mypy sobre el Python, actionlint y zizmor sobre los ficheros de workflow. Cualquier hallazgo hace fallar el job. Los workflows pueden publicar mis releases, así que pasan las mismas comprobaciones que el Python.

Tests. Linux con Python 3.12 y 3.13, macOS 14 y Windows 2022. Solo la combinación de Linux con Python 3.12 mide la cobertura, con --cov-fail-under=88.

Docs y paquete. mkdocs build --strict falla ante un enlace roto, y el sdist y el wheel se construyen desde un lock con hashes fijados. La revisión de dependencias bloquea los pull requests que añaden una dependencia con un aviso de seguridad de severidad alta.

Imágenes. Las imágenes del panel y de Lambda se construyen y se arrancan. El panel debe responder en /healthz, y la imagen de Lambda debe responder a un evento de HTTP API enviado a través del Runtime Interface Emulator. Trivy hace fallar el job ante una vulnerabilidad crítica con corrección disponible. El tiempo máximo es de 40 minutos, el más alto de ci.

Chart de Helm. helm lint --strict y helm template se ejecutan con los valores por defecto y con todas las opciones activadas. Después el job construye la imagen desde el commit, levanta un clúster kind, instala el chart, ejecuta helm test, llega al panel con un port-forward, actualiza con todas las opciones activadas y vuelve a probar. El tiempo máximo es de 30 minutos.

Instaladores. En windows-2022, ubuntu-22.04 y macos-14, el job construye el archivo comprimido, pasa el script de instalación al intérprete como lo hace curl -fsSL https://vpcatlas.com/install.sh | sh y ejecuta vpcatlas --version. Después le da al instalador una suma de verificación que no coincide y exige que falle con checksum mismatch, sin dejar nada instalado. Una comprobación que nunca se ha visto fallar demuestra poco.

Qué hace un tag

Para publicar, pongo la misma versión en pyproject.toml, src/vpcatlas/__init__.py y deploy/helm/vpcatlas/Chart.yaml, incorporo el cambio con un pull request, pongo el tag al commit de merge y lo subo. El primer job se niega a seguir si el tag y los cuatro campos de versión no coinciden:

chart=$(sed -n 's/^version: *\(.*\)$/\1/p' deploy/helm/vpcatlas/Chart.yaml)
app=$(sed -n 's/^appVersion: *"\(.*\)"$/\1/p' deploy/helm/vpcatlas/Chart.yaml)
if [ "$package" != "$chart" ] || [ "$package" != "$app" ]; then
  echo "pyproject.toml says ${package} but Chart.yaml says version ${chart} and appVersion ${app}" >&2
  exit 1
fi
if [ "${GITHUB_REF_TYPE}" = "tag" ] && [ "${GITHUB_REF_NAME#v}" != "$package" ]; then
  echo "Tag ${GITHUB_REF_NAME} does not match the version ${package}" >&2
  exit 1
fi

Después, por orden:

binaries se construyen con PyInstaller para Linux, macOS (Intel y Apple silicon) y Windows. Cada binario se ejecuta, y el que sale del archivo desempaquetado debe imprimir --version en menos de tres segundos. La compilación de Linux x86_64 escribe además el SBOM.
release escribe SHA256SUMS, lo comprueba con sha256sum -c, genera la atestación de cada archivo, del fichero de sumas y del SBOM, y crea la release de GitHub.
docker y lambda construyen cada imagen (la del panel, para linux/amd64 y linux/arm64), la analizan con Trivy y se detienen antes del push si hay una vulnerabilidad crítica con corrección. Luego la suben, la firman por digest con cosign y generan su atestación.
chart sube el chart de Helm a ghcr.io/karina-pp/charts/vpcatlas, lo firma, genera su atestación y lo descarga de nuevo para verificar ambas.
pypi publica con trusted publishing: PyPI confía en la ejecución del workflow, así que no existe ningún token. Una variable del repositorio activa el job, porque antes hay que registrar el publicador en pypi.org.
verify va el último. Todos los jobs anteriores prueban mis ficheros. Este prueba lo que recibe el usuario.

Ejecuta curl -fsSL https://vpcatlas.com/install.sh | sh en Linux y macOS y irm https://vpcatlas.com/install.ps1 | iex en Windows, con la versión fijada, desde el sitio publicado y no desde el commit. vpcatlas --version debe imprimir exactamente vpcatlas X.Y.Z. En Linux verifica además la atestación y la firma de la imagen publicada. Si el sitio, el script, los ficheros de la release o las firmas están mal, este job falla.

La ejecución de release de la 0.7.0, tal como la dibuja GitHub: la release en el centro, las imágenes, PyPI y el chart después, y verify al final.

Si lanzo el workflow a mano desde la pestaña Actions, prueba y construye pero no publica nada, porque todos los jobs que publican llevan una condición sobre el tag, así que una ejecución manual es el ensayo.

Decisiones que mantienen pequeña la cadena de suministro

Todo lo que traigo de otros repositorios va fijado por contenido. Los workflows usan 25 actions de otros repositorios, cada una fijada a un SHA de commit completo con la versión en un comentario, y la única action de contenedor, por su digest:

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  with:
    persist-credentials: false

Las imágenes base se fijan por digest y los requisitos de Python por hash, y se instalan con --require-hashes. Un tag se puede mover después. Un SHA de commit, no. Dependabot propone las actualizaciones cada lunes, con una espera de siete días, así que una versión nueva tarda una semana en llegarme.

Los cinco workflows empiezan con permissions: contents: read. Un job pide más solo para lo que hace, como id-token: write para firmar. Los 21 checkouts llevan persist-credentials: false, así que el token no se queda en la copia de trabajo.

Las firmas y las atestaciones usan la identidad efímera que GitHub da a cada ejecución del workflow, y PyPI usa trusted publishing, así que no hay ningún secreto de firma que se pueda filtrar. La única credencial de larga duración que queda es el token de Docker Hub, porque Docker Hub no acepta la identidad de GitHub.

El workflow de release no restaura ninguna caché de compilación, ni siquiera la de Trivy, porque una caché escrita por una ejecución nunca debe acabar dentro de un fichero publicado.

Hay un solo SBOM, un fichero CycloneDX escrito por Syft, que lista lo que hay dentro de la compilación de Linux x86_64 y lleva su atestación vinculada a ese archivo. Los demás se construyen con el mismo lock de dependencias, así que un fichero vale para todos.

Lo que lleva una release: los archivos, SHA256SUMS, el SBOM y el chart, con el digest de cada fichero al lado.

Después de una release, CodeQL con las consultas security-extended, Scorecard, pip-audit y un análisis nocturno con Trivy de la imagen de Docker Hub siguen vigilando lo que ya está publicado. Si una noche falla, se abre un único issue con la etiqueta nightly y los fallos siguientes se añaden como comentarios.

Cómo comprobar una descarga

SHA256SUMS viaja junto al archivo, así que solo demuestra que el fichero no se dañó por el camino. La atestación demuestra que lo construyó el workflow de release de este repositorio, y esa es la comprobación que importa. Necesitas la CLI de GitHub y, para las imágenes, cosign 3 o superior:

gh attestation verify vpcatlas-X.Y.Z-linux-x86_64.tar.gz --owner karina-pp
gh attestation verify SHA256SUMS --owner karina-pp
sha256sum --check --ignore-missing SHA256SUMS       # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
gh attestation verify oci://index.docker.io/vpcatlas/vpcatlas:X.Y.Z --owner karina-pp
cosign verify index.docker.io/vpcatlas/vpcatlas:X.Y.Z \
  --certificate-identity-regexp '^https://github.com/karina-pp/vpcatlas/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Una ejecución correcta nombra el workflow y el commit que produjeron el fichero. Si falla, no instales el fichero. Los scripts de instalación hacen por ti la comprobación del archivo cuando gh está instalado y con la sesión iniciada, y VPCATLAS_SKIP_ATTESTATION=1 la desactiva.

Las comprobaciones sobre una descarga real de la 0.7.0, con la CLI de GitHub: el archivo, SHA256SUMS y la imagen publicada apuntan todos al workflow de release del tag.

Qué cuesta y qué me saltaría

El primer coste es el tamaño: los cinco ficheros de workflow suman unas 1.650 líneas de YAML. El mantenimiento es el segundo: un lote semanal de pull requests de Dependabot y runners que cambian bajo tus pies. GitHub retiró el runner de macOS 13 con Intel, así que el workflow de release construye ahora ese binario en macos-15-intel. Las herramientas también discrepan: las líneas que usan la action local de setup llevan un comentario para ignorar un aviso, porque zizmor y actionlint 1.7.12 no pueden quedar contentos a la vez. El tercer coste es la espera. En ci, los tiempos máximos van de 10 minutos para la revisión de dependencias a 40 para las imágenes.

Para un proyecto más pequeño, con un solo binario y sin chart, sin imagen de Lambda ni script de instalación, me saltaría el clúster kind, la prueba con el emulador, la matriz de instaladores, el benchmark nocturno del layout y Scorecard. Scorecard puntúa el repositorio, y lo que protege son las versiones fijadas y los permisos que puntúa. Conservaría lo que casi no cuesta: SHA fijados, contents: read por defecto, zizmor, Dependabot, SHA256SUMS con una atestación de procedencia de la compilación y un último job que instala la release publicada como lo haría un usuario.

Lo que aún falta

Sin certificado de firma de código. La atestación dice quién construyó un fichero, pero Windows y macOS no la leen, así que SmartScreen y Gatekeeper pueden seguir avisando ante un fichero descargado con el navegador.
La verificación depende de gh. Sin la CLI de GitHub con la sesión iniciada, los instaladores solo comprueban la suma de verificación, que demuestra que el fichero llegó entero, no quién lo hizo.
Las firmas llegan tarde. Las imágenes firmadas y los SBOM existen solo en las releases hechas con este pipeline. Las anteriores solo llevan las atestaciones de los archivos y SHA256SUMS.
Cinco archivos, a veces cuatro. Linux arm64 se construye solo mientras hay una variable del repositorio activa, así que una release puede llevar cuatro.

Actualización, 23 de octubre de 2026: el repositorio del código es privado por ahora, así que los pasos que necesitan un repositorio público están en pausa: las atestaciones, CodeQL, la revisión de dependencias y el último job que instala la release con los instaladores de la web. Las releases se copian a vpcatlas.com/releases, los instaladores descargan de ahí (ver Install) y una descarga se comprueba con SHA256SUMS (las imágenes y el chart, con cosign).

Dónde mirar

Los workflows corren en GitHub Actions en el repositorio del código, que es privado por ahora, y la lista completa de comprobaciones está en la página de ingeniería de la documentación. Lo que dibuja la herramienta en sí está en el post de lanzamiento. El paquete está en PyPI y la imagen en Docker Hub. Si algún paso no comprueba lo que dice su nombre, dímelo.

What a one-person CLI needs before you can trust its binary

Karina Pérez — Sun, 18 Oct 2026 20:17:08 +0000

How I built the CI/CD and supply chain of VPC Atlas, and the commands that let you check every download.

Why a small tool gets this much pipeline

The tool only makes read-only calls, but it runs with credentials for an AWS account, so whoever installs it should know what they are running.

Only the maintainer merges and releases, and that's me. CODEOWNERS has one rule with one name. With no second reviewer to catch a mistake or a shortcut, I wrote down the checks a reviewer would make and had a machine run them on every change, in public.

I wanted anyone who downloads a file from the releases page to be able to find out which workflow built it, and from which commit, without taking my word for it. What follows is each decision and why I made it. The reasons carry over to other projects. The YAML only fits mine.

The shape of the pipeline

There are five workflows. ci runs on every pull request and every push to main. release runs when I push a tag. CodeQL and OpenSSF Scorecard also run every Monday, and nightly checks run at 05:00 UTC for what can break without a code change: pip-audit on the installed packages, the links in the docs, a layout benchmark and a Trivy scan of the published image. Every job has a timeout. Only a tag of the form vX.Y.Z publishes:

on:
  push:
    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
  workflow_dispatch:

permissions:
  contents: read

What runs on every change

ci has nine jobs and none waits for another, so a change takes as long as its slowest job. A newer push to the same branch cancels the older run. The job names are the required checks of main, and direct commits to main are not accepted.

One ci run, on the commit that released 0.7.0: nine jobs and no arrows between them.

Lint and types. ruff and mypy on the Python, actionlint and zizmor on the workflow files. Any finding fails the job. The workflows can publish my releases, so they get the same checks as the Python.

Tests. Linux on Python 3.12 and 3.13, macOS 14 and Windows 2022. Only the Linux 3.12 leg measures coverage, with --cov-fail-under=88.

Docs and package. mkdocs build --strict fails on a broken link, and the sdist and wheel are built from a hash-pinned lock. Dependency review blocks pull requests that add a dependency with a high-severity advisory.

Images. The dashboard and Lambda images are built and started. The dashboard must answer /healthz, and the Lambda image must answer an HTTP API event sent through the Runtime Interface Emulator. Trivy fails the job on a fixable critical vulnerability. The timeout is 40 minutes, the highest in ci.

Helm chart. helm lint --strict and helm template run with the defaults and with every option on. Then the job builds the image from the commit, starts a kind cluster, installs the chart, runs helm test, reaches the dashboard through a port-forward, upgrades with every option on and tests again. The timeout is 30 minutes.

Installers. On windows-2022, ubuntu-22.04 and macos-14, the job builds the archive, pipes the install script into the shell the way curl -fsSL https://vpcatlas.com/install.sh | sh does, and runs vpcatlas --version. Then it hands the installer a checksum that does not match and requires a checksum mismatch failure, with nothing left behind. A check that has never been seen to fail proves little.

What a tag does

To release, I set the same version in pyproject.toml, src/vpcatlas/__init__.py and deploy/helm/vpcatlas/Chart.yaml, merge that through a pull request, tag the merge commit and push the tag. The first job refuses to go on unless the tag and all four version fields agree:

chart=$(sed -n 's/^version: *\(.*\)$/\1/p' deploy/helm/vpcatlas/Chart.yaml)
app=$(sed -n 's/^appVersion: *"\(.*\)"$/\1/p' deploy/helm/vpcatlas/Chart.yaml)
if [ "$package" != "$chart" ] || [ "$package" != "$app" ]; then
  echo "pyproject.toml says ${package} but Chart.yaml says version ${chart} and appVersion ${app}" >&2
  exit 1
fi
if [ "${GITHUB_REF_TYPE}" = "tag" ] && [ "${GITHUB_REF_NAME#v}" != "$package" ]; then
  echo "Tag ${GITHUB_REF_NAME} does not match the version ${package}" >&2
  exit 1
fi

Then, in order:

binaries are built with PyInstaller for Linux, macOS on Intel and Apple silicon, and Windows. Each build is run, and the binary from the unpacked archive must print --version in under three seconds. The Linux x86_64 build also writes the SBOM.
release writes SHA256SUMS, checks it with sha256sum -c, attests every archive, the checksum file and the SBOM, and creates the GitHub Release.
docker and lambda build each image (the dashboard one for linux/amd64 and linux/arm64), scan it with Trivy, and stop before the push on a fixable critical vulnerability. Then they push, sign by digest with cosign and attest.
chart pushes the Helm chart to ghcr.io/karina-pp/charts/vpcatlas, signs and attests it, and pulls it back to verify both.
pypi publishes through trusted publishing: PyPI trusts the workflow run, so no token exists. A repository variable switches the job on, because the publisher must be registered on pypi.org first.
verify runs last. Every job before it tests my files. This one tests what users get.

It runs curl -fsSL https://vpcatlas.com/install.sh | sh on Linux and macOS and irm https://vpcatlas.com/install.ps1 | iex on Windows, with the version pinned, from the live site and not from the commit. vpcatlas --version must print exactly vpcatlas X.Y.Z. On Linux it also verifies the attestation and signature of the published image. If the site, the script, the assets or the signatures are wrong, this job fails.

The release run of 0.7.0, as GitHub draws it: the release in the middle, the images, PyPI and the chart after it, and verify last.

Started by hand from the Actions tab, the workflow tests and builds but publishes nothing, because every publishing job has a condition on the tag, so a manual run is the rehearsal.

Decisions that keep the supply chain small

Everything I pull from other repositories is pinned by content. The workflows use 25 actions from other repositories, each pinned to a full commit SHA with the version in a comment, and the one container action by its digest:

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  with:
    persist-credentials: false

Base images are pinned by digest and Python requirements by hash, installed with --require-hashes. A tag can be moved after the fact. A commit SHA cannot. Dependabot proposes the bumps every Monday, with a seven-day cooldown, so a new release waits a week before it reaches me.

All five workflows start with permissions: contents: read. A job asks for more only for what it does, such as id-token: write to sign. All 21 checkouts set persist-credentials: false, so the token does not stay in the working copy.

Signatures and attestations use the short-lived identity GitHub gives each workflow run, and PyPI uses trusted publishing, so there is no signing secret to leak. The one long-lived credential left is the Docker Hub token, because Docker Hub does not accept GitHub's identity.

The release workflow restores no build cache, not even Trivy's, because a cache written by one run must never end up inside a published file.

There is one SBOM, a CycloneDX file written by Syft, that lists what is inside the Linux x86_64 build and is attested against that archive. The other archives are built from the same lock of dependencies, so one file stands for all of them.

What a release carries: the archives, SHA256SUMS, the SBOM and the chart, with the digest of each file next to it.

After a release, CodeQL with the security-extended queries, Scorecard, pip-audit and a nightly Trivy scan of the image on Docker Hub keep watching what is already published. A failing night opens one issue labelled nightly, and later failures comment on it.

How to check a download

SHA256SUMS travels with the archive, so it only proves the file was not damaged on the way. The attestation proves the archive was built by this repository's release workflow, and that is the check that matters. You need the GitHub CLI and, for images, cosign 3 or newer:

gh attestation verify vpcatlas-X.Y.Z-linux-x86_64.tar.gz --owner karina-pp
gh attestation verify SHA256SUMS --owner karina-pp
sha256sum --check --ignore-missing SHA256SUMS       # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
gh attestation verify oci://index.docker.io/vpcatlas/vpcatlas:X.Y.Z --owner karina-pp
cosign verify index.docker.io/vpcatlas/vpcatlas:X.Y.Z \
  --certificate-identity-regexp '^https://github.com/karina-pp/vpcatlas/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

A successful run names the workflow and the commit that produced the file. If it fails, do not install the file. The install scripts run the archive check for you when gh is installed and signed in, and VPCATLAS_SKIP_ATTESTATION=1 turns it off.

The checks on a real download of 0.7.0, with the GitHub CLI: the archive, SHA256SUMS and the published image all point at the release workflow of the tag.

What it costs, and what I would skip

The first cost is size: the five workflow files add up to about 1,650 lines of YAML. Upkeep is the second: a weekly batch of Dependabot pull requests, and runners that change under you. GitHub retired the Intel macOS 13 runner, so the release workflow now builds that binary on macos-15-intel. Tools disagree too: the lines that use the local setup action carry an ignore comment because zizmor and actionlint 1.7.12 cannot both be pleased. The third cost is the wait. In ci, the timeouts run from 10 minutes for the dependency review to 40 for the images.

For a smaller project, with one binary and no chart, Lambda image or installer script, I'd skip the kind cluster, the emulator test, the installer matrix, the nightly layout benchmark and Scorecard. Scorecard grades the repository, and the pins and permissions it grades do the protecting. I'd keep what costs almost nothing: pinned SHAs, contents: read by default, zizmor, Dependabot, SHA256SUMS with a build provenance attestation, and a last job that installs the published release the way a user does.

What is still missing

No code-signing certificate. The attestation tells you who built a file, but Windows and macOS do not read it, so SmartScreen and Gatekeeper can still warn about a file downloaded with a browser.
Verification depends on gh. Without gh installed and signed in, the installers only check the checksum, which proves the file arrived intact, not who made it.
Signatures start late. Signed images and SBOMs exist only for releases made by this pipeline. Earlier ones carry only the attestations of the archives and SHA256SUMS.
Five archives, sometimes four. Linux arm64 is built only while a repository variable is set, so a release can carry four.

Update, 23 October 2026: the source repository is private for now, so the steps that need a public repository are paused: the artifact attestations, CodeQL, the dependency review and the last job that installs the release with the live installers. Releases are mirrored to vpcatlas.com/releases, the installers download from there (see Install), and a download is checked against SHA256SUMS (the images and the chart with cosign).

Where to look

The workflows run on GitHub Actions in the source repository, which is private for now, and the full list of checks is on the engineering page of the docs. What the tool itself draws is in the launch post. The package is on PyPI and the image on Docker Hub. If a step does not check what its name says, tell me.

Nadie mantiene al día el diagrama de red de AWS. He hecho una herramienta para eso

Karina Pérez — Sun, 18 Oct 2026 19:10:15 +0000

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:

curl -fsSLO https://vpcatlas.com/releases/vX.Y.Z/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

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.

Actualización, 23 de octubre de 2026: el repositorio del código es privado por ahora. Las releases se copian a vpcatlas.com/releases y los instaladores descargan de ahí; una descarga se comprueba con SHA256SUMS como arriba (las imágenes y el chart, con cosign), y los pasos que necesitan un repositorio público (atestaciones, CodeQL, el último job de instalación) están en pausa.

Dónde conseguirla

Instalación: https://vpcatlas.com/docs/install/
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.

Nobody keeps the AWS network diagram current. I built a tool for it

Karina Pérez — Sun, 18 Oct 2026 19:08:12 +0000

VPC Atlas reads an AWS account with read-only calls and draws its network in draw.io and Lucidchart. Alpha, MIT licensed.

Every team I joined asked for the same thing first: the network diagram. The one that shows every VPC, how the VPCs connect through Transit Gateways, peerings, VPNs and Direct Connect, and what sits at the edge in front of them. And every time, the diagram that existed was out of date.

Drawn by hand, or rebuilt from the console

A network diagram drawn by hand is wrong a week later. Someone adds an attachment, someone shares a Transit Gateway through AWS RAM, a peering with another account appears, and the picture stays as it was.

The alternative is to rebuild it from the console: open each VPC, read the route tables, follow the attachments, check the endpoints, then draw it. On a real account that takes days. I wanted to point a tool at the account, get the diagram in minutes, and do it again next week to compare.

What VPC Atlas does

vpcatlas connects to an AWS account with auditor permissions and maps its network: VPCs, subnets, routing, gateways, endpoints, load balancers, firewalls, the DNS resolver and whatever is shared through RAM, plus what sits in front of them: Route 53, CloudFront, WAF, ACM and Shield. It also reads compute and data stores such as RDS, S3 and DynamoDB, so a subnet shows what runs in it, and account services such as CloudTrail, GuardDuty and KMS for the inventory.

It is read-only by design. It calls Describe*, Get*, List* and Search* APIs and never creates, changes or deletes anything. It ships the minimal policy it needs, so you can read what it asks for before you grant it.

One run gives you three things. The diagrams: a Global page, one page per Region and one page per VPC, as .drawio and .lucid files, drawn with the AWS Architecture Icons and laid out like the AWS Managed Services multi-account landing zone network reference. An inventory in JSON, Markdown and HTML, with every resource account by account and a section for every external account linked to yours. And a dashboard: vpcatlas serve shows the same diagrams in the browser, keeps a history of scans and draws the difference between two of them, what was added in green and what changed in orange. The raw result is saved too, as vpcatlas-graph.json, so you can redraw later without calling AWS again.

The recordings and diagrams here come from a simulated AWS account, so the ids are examples. This is the dashboard on that account:

And a Region page:

How it works

A read-only pipeline with four stages: collect, graph, layout, export. Each stage takes one input and gives one output, which is what makes it easy to test.

Collectors read the account, one per service, all paginated. Regions run in parallel, but inside a Region the collectors run one after another to keep API throttling low, and a call that fails with AccessDenied is logged and skipped, without ever stopping the run. The results become a networkx directed graph wrapped by Pydantic models, with typed edges (contains, routes_to, attached_to, peered_with, shared_from) and external accounts as nodes of their own. Positions are computed once, as a deterministic grid: cloud, Region, VPC, availability zone, subnet. Both diagram exporters draw from that one layout, so the same input gives the same drawing, nothing moves between two runs unless the network moved, and a diff means something. The exporters write mxGraph XML with the mxgraph.aws4 shapes for draw.io, a Lucid Standard Import package for Lucid, and the inventory in JSON, Markdown and HTML.

The decisions that took time

Numbered flows. Every arrow is the same grey, and numbered circles tell the kinds of traffic apart. A kind of traffic keeps its number on every page: 1 Internet ingress, 2 NAT egress, 3 Transit Gateway attachment, 4 Direct Connect or VPN, 5 VPC peering, 6 shared prefix list or RAM. A legend lists the ones a page uses. The numbers come from the kind of each edge, not from observed traffic, and the documentation says so.

The Global page. The whole network on one page: accounts, the Transit Gateway hub, peerings, Direct Connect gateways. Anything referenced but not owned by an audited account goes in a dashed box of its own, one per external account.

Gaps, not zeros. A denied call becomes a recorded gap. Where a count would have been, the page says not read. It never writes 0, because a zero looks like an answer.

Crowded pages. The layout is where most of my time went. A Region page with 77 API Gateways took 97 seconds in --detail full; drawing the fans of edges as a bus, one trunk with a branch per icon, brought it to under a second. --detail simple folds more than three resources of one kind into one card, such as API Gateway ×77, and on the same page it went from 37 seconds to under a second, and from 17,700 to 2,660 pixels wide.

One VPC page: subnets, routing and numbered flows.

Try it in a sandbox account

You need Python 3.12 or newer and an AWS account you may read.

pipx install vpcatlas
vpcatlas iam-policy > auditor-policy.json   # attach this to the role or user you will use
vpcatlas discover --profile audit --output-dir ./out
vpcatlas serve --cache ./out/vpcatlas-graph.json

For a quick run in a sandbox, the AWS managed ReadOnlyAccess also works, but it reads far more than the tool needs; don't leave it on a role you keep. Credentials work the way the AWS CLI's do: a profile, environment variables, SSO, or an assumed role with an external ID and MFA.

You get the graph, the inventory and a diagrams/ folder. Open any .drawio file in diagrams.net, or import a .lucid file with Lucid Standard Import. Start with vpcatlas-global.drawio. The dashboard opens on http://127.0.0.1:8080 over the scan you just made, without calling AWS again.

There is a binary installer with no Python needed (curl -fsSL https://vpcatlas.com/install.sh | sh, or a PowerShell one-liner on Windows) and a Docker image, which serves the dashboard by default:

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

The dashboard shows your network topology, so keep it on a private network, or set VPCATLAS_AUTH_PASSWORD and serve it over HTTPS.

What it does not do yet

This is an alpha, and the limits are in the documentation.

Accounts are listed by hand. Repeat --profile or --role-arn to merge several accounts into one graph. There is no discovery of the accounts of an AWS Organization yet: you list them.
A snapshot. The files describe the network at the moment of the scan.
No traffic analysis. No flow logs, reachability analysis or route simulation.
No contents. No S3 objects, secrets or log events, and no rule or policy bodies.
Services without a collector. Global Accelerator, VPC Lattice, IPAM, Network Manager and Cloud WAN, Client VPN and a few more.
AWS only, and a regenerated file replaces your edits, so keep edited copies under another name.

Planned for v2: Network Manager and Cloud WAN topologies, Direct Connect and VPN path tracing, drift between two snapshots, diagram diffs in pull requests, and multi-account runs from an AWS Organizations list.

How it is built and released

I wanted to be able to ask of this tool what I ask of any other: where did the binary come from?

Every change goes through lint, type checks, tests on Linux, macOS and Windows, both Docker images with smoke tests and a scan, and the installers on three systems. CodeQL, OpenSSF Scorecard and Dependabot run weekly, pip-audit nightly. The full list, and the reason for each check, is in the CI/CD post.

A release produces binaries for up to five platforms, SHA256SUMS, an SBOM, and signed and attested images, and a last job installs the published release with the live installers. The package is on PyPI and the image on Docker Hub, for linux/amd64 and linux/arm64. To check a download:

curl -fsSLO https://vpcatlas.com/releases/vX.Y.Z/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

Image signatures and SBOMs start with 0.4.1, and verifying an image signature needs cosign 3 or newer.

Update, 23 October 2026: the source repository is private for now. Releases are mirrored to vpcatlas.com/releases and the installers download from there; a download is checked against SHA256SUMS as above (the images and the chart with cosign), and the steps that need a public repository (attestations, CodeQL, the last install job) are paused.

Where to get it

Install: https://vpcatlas.com/docs/install/
Documentation: https://vpcatlas.com/docs/
Docker Hub: https://hub.docker.com/r/vpcatlas/vpcatlas

It's MIT licensed. The most useful thing you can do is run it on a sandbox account and tell me where the drawing is wrong or the reading comes up short.