FAQ

Is it safe to run against a production account?

It was built for that. vpcatlas calls list, describe, get and search operations only; it never creates, changes, tags or deletes anything. You can check this three ways: the list of every call is in Coverage, the published policy grants nothing else, and you can give the tool a role that holds only that policy, so even a bug could not write. The policy also denies reading API Gateway keys and client certificates. Secret members of API answers (VPN pre-shared keys, Direct Connect keys) are removed before anything is kept.

What does it send, and to whom?

The tool starts exactly one kind of network traffic: calls to the AWS APIs, from the machine where it runs, with the credentials you give it. It has no account, no telemetry and no server of ours. The calls carry vpcatlas in the user agent, and with --role-arn the session name is vpcatlas (or what you set), so CloudTrail shows who called.

The one other thing to know is in the dashboard: your browser loads the diagrams.net viewer script from viewer.diagrams.net. The diagram itself is served by your dashboard; only the script comes from that host. You can host that script yourself; see Troubleshooting.

What do the output files reveal?

A lot about your network: account ids, ARNs, CIDR blocks, route targets, security group rules and tags. Handle vpcatlas-graph.json, the inventory and the diagrams like any other architecture document, and keep the dashboard on a private network or behind VPCATLAS_AUTH_PASSWORD.

Does it cost money?

vpcatlas is free software under the MIT license, and 0.1.0 is an alpha. There is no paid plan in 0.1.0. In AWS it makes read-only API calls and creates nothing, so it adds no resources to your bill.

Which credentials can I use? Do I need access keys?

Any method the AWS CLI understands: environment variables, ~/.aws files, SSO profiles, assumed roles, EC2 instance roles, ECS task roles, EKS pod roles (IRSA and Pod Identity) and Lambda execution roles. Prefer a role or SSO. If you use access keys, put them in the environment or in the shared files; they are never command line flags. See IAM.

Lucid or draw.io: which should I use?

Both files are generated from the same layout, so they show the same diagram. Use draw.io (.drawio) when you want a free, offline editor: open the file in diagrams.net or draw.io Desktop, and it is a plain XML file that diffs well in Git. Use Lucid (.lucid) when your team documents in Lucidchart: import it with Lucid Standard Import and it becomes an editable Lucid document. Lucid has no rounded corners or dash-dot lines, so a few styles differ slightly.

How often should I refresh the diagrams?

Think of a diagram as a photograph. For a documentation set, run it when the network changes: after a project ends, before an audit, when you hand over. For a living view, run the dashboard with VPCATLAS_REFRESH_SECONDS=900 (15 minutes) or hourly, never below 300 seconds. The History page keeps earlier snapshots (30 by default) and the "View changes on diagram" page marks what was added and what changed between two of them.

Can it draw my whole AWS Organization?

Not by itself yet. Discovery of every account from the organization is planned for v2. Today you list the accounts, with repeated --profile or --role-arn, and the tool merges them into one graph. See Cross-account.

Does it see the accounts of my partners or other teams?

It sees the account ids and the shared resources: a Transit Gateway shared with you, a peering with a foreign account, a shared subnet. It cannot look inside accounts it has no credentials for; those show as dashed external accounts. Cross-account explains what appears and why.

How long does a scan take?

It depends on the number of regions and resources: a scan of one region is far shorter than a scan of all of them, which is on the order of a thousand list calls for 17 regions. Use --regions to scan only the regions you use. Scans are polite on purpose and slow down when AWS throttles; see Troubleshooting.

Does it work on Windows?

Yes, in three ways. A Windows binary (vpcatlas.exe, x86_64) is on the releases page as a .tar.gz archive with a SHA256SUMS file; the install script is for Linux and macOS only. The Python package works on Windows with Python 3.12 or newer (pipx install git+https://github.com/vpcatlas/vpcatlas). And the Docker image runs under Docker Desktop. The binary is not code-signed, so SmartScreen asks for confirmation once; see Troubleshooting. Native Windows on Arm has no binary.

Can I run it in an air-gapped environment?

The scan needs to reach the AWS APIs. In a network without internet that means private connectivity: interface VPC endpoints for the services it calls, or a proxy to the AWS endpoints. Everything after the scan is local. A common pattern is to scan from a machine that can reach AWS, copy vpcatlas-graph.json across, and run vpcatlas inventory --cache and vpcatlas diagram --cache (or vpcatlas serve --cache) inside. Without internet the dashboard viewer needs a self-hosted script, or you open the .drawio files in draw.io Desktop. To install without a registry, copy the binary, a wheel set, or a docker save archive of the image.

Does it work in GovCloud or China?

The code knows the bootstrap region and the partition of aws, aws-cn, aws-us-gov, aws-iso and aws-iso-b, and builds ARNs with the right partition. The tests use mocked AWS, so report a partition that misbehaves.

Can I run it in CI?

Yes. vpcatlas discover --strict exits with code 4 when any call was denied or failed, which is useful to keep a role honest, and the exit codes are listed in Troubleshooting. Commit the Markdown inventory to see the network change in a pull request.

Do I need Docker or Python to use it?

No. The binary is a single file with the dashboard inside. Python 3.12 or newer is needed only for the package, and Docker only for the image.