DEV Community: Karina Pérez

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.

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.

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.

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, el comando en la página de inventory y el código en el repositorio. 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.

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

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, the command in the inventory page, and the code in the repository. 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.

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.

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.

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.

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.

Dónde mirar

Los workflows están en el repositorio, cada ejecución aparece en su página de Actions 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.

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.

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.

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.

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.

Where to look

The workflows are in the repository, every run is on its Actions page, 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:

gh attestation verify vpcatlas-X.Y.Z-linux-x86_64.tar.gz --owner karina-pp

Las firmas de imagen y los SBOM empiezan en la 0.4.1, y verificar la firma de una imagen necesita cosign 3 o superior.

Hecha con IA, funciona sin ella

La IA me ayudó a escribir esta herramienta, y prefiero decirlo a fingir lo contrario. La herramienta en sí no necesita nada de eso: ni modelo, ni clave de API, ni cuenta que abrir en ningún sitio, ni factura por token, y nada sale de tu red salvo las llamadas a la API de AWS que tú autorizaste. Hay equipos que no pueden usar herramientas de IA en el trabajo, o que no las van a pagar. Siguen necesitando el diagrama, así que la herramienta no depende de ninguna.

Dónde conseguirla

Código y releases: https://github.com/karina-pp/vpcatlas
Web: https://vpcatlas.com
Documentación: https://vpcatlas.com/docs/
Docker Hub: https://hub.docker.com/r/vpcatlas/vpcatlas

Tiene licencia MIT. Lo más útil que puedes hacer es ejecutarla en una cuenta sandbox y decirme dónde está mal el dibujo o dónde la lectura se queda corta.

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:

gh attestation verify vpcatlas-X.Y.Z-linux-x86_64.tar.gz --owner karina-pp

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

Built with AI, runs without it

AI helped me write this tool, and I'd rather say so than pretend otherwise. The tool itself needs none of it: no model, no API key, no account with anyone, no bill per token, and nothing leaves your network except the AWS API calls you authorised. Some teams can't use AI tools at work, or won't pay for them. They still need the diagram, so the tool doesn't depend on one.

Where to get it

Source and releases: https://github.com/karina-pp/vpcatlas
Site: https://vpcatlas.com
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.