vpcatlas discover

vpcatlas [GLOBAL OPTIONS] discover [OPTIONS]

What it does

Scans the account(s), then writes the graph, the inventory and the diagrams. It is the whole run in one command: it reads AWS once and writes everything the other commands write separately. Use inventory or diagram when you only need one of the two, and serve for the dashboard.

Credentials come from the standard chain or from the options below; see credentials. The scan only calls read APIs. Progress shows on standard error while it runs. When it ends, the paths of the files written go to standard output, one per line, and a "Discovery summary" table (audited accounts, external accounts, regions, resources, cross-account links, issues and the number of account-level and VPC-level pages) goes to standard error, followed by the first ten issues.

Diagram pages are written only for regions that hold at least one resource, narrowed by --regions and --exclude-regions. Both options also narrow the pages when the graph comes from --cache.

Options

Flag	Environment variable	Default	Description
--profile, -p	none	standard credential chain	AWS profile. Repeat it to scan several accounts into one graph.
--role-arn	none	none	Role to assume (ARN). Repeat it to scan several accounts.
--external-id	VPCATLAS_EXTERNAL_ID	none	ExternalId required by the role.
--mfa-serial	none	none	MFA device serial or ARN, when the role requires MFA.
--mfa-token	none	none	Current MFA code. Used together with --mfa-serial.
--session-duration	VPCATLAS_SESSION_DURATION	3600	Duration of the assumed-role session, in seconds (900 to 43200).
--role-session-name	VPCATLAS_ROLE_SESSION_NAME	vpcatlas	RoleSessionName used when assuming the role.
--regions, -r	none	every enabled region	Regions to scan, comma separated. Default: every enabled region.
--exclude-regions	none	none	Regions to leave out, comma separated.
--concurrency, -c	none	8	Regions scanned in parallel (1 to 32).
--cache	none	none	Read this graph file (vpcatlas-graph.json) instead of calling AWS. The file must exist.
--output-dir, -o	none	vpcatlas-out	Directory for the generated files. Created when missing.
--format, -f	none	all	drawio, lucid, json, md, html or all. Repeat or separate with commas.
--account-names	none	none	JSON file that maps account ids to labels, for accounts the API cannot name. The file must exist.
--strict	none	off	Exit with code 4 when discovery recorded issues (denied, errors).
--level	none	all	Diagram level: account (global view, one page per region), vpc (one page per VPC) or all.

--format decides what is written: json, md and html are the inventory, drawio and lucid are the diagrams. all is all five. An unknown value is a usage error. --level only matters when a diagram format is selected.

Files it writes

Under the output directory (vpcatlas-out unless --output-dir says otherwise):

File	When
vpcatlas-graph.json	The data came from AWS. Not written with --cache.
vpcatlas-inventory.json, vpcatlas-inventory.md, vpcatlas-inventory.html	The matching format is selected.
diagrams/vpcatlas-global.drawio and diagrams/vpcatlas-global.lucid	Level account or all, and the matching format is selected.
diagrams/vpcatlas-<region>.drawio and .lucid (for example vpcatlas-eu-west-1.drawio)	One per drawn region, level account or all.
diagrams/vpcatlas-vpc-<id>.drawio and .lucid	One per VPC, level vpc or all.

Formats: graph, inventory, diagrams.

Examples

A local profile, one region:

vpcatlas discover --profile audit --regions eu-west-1

An assumed role in another account with an external id. The base identity is the default credential chain (here the environment or a profile), and the role session is the one the audited account sees in CloudTrail:

export VPCATLAS_EXTERNAL_ID=my-external-id
vpcatlas discover \
  --role-arn arn:aws:iam::111122223333:role/VpcAtlasAuditor \
  --role-session-name atlas-nightly --session-duration 3600 \
  --exclude-regions ap-southeast-3 --output-dir ./atlas

Docker, with the AWS profile mounted read-only and the files written to ./vpcatlas-out:

docker run --rm -v "$HOME/.aws:/home/atlas/.aws:ro" -v "$PWD/vpcatlas-out:/data" \
  vpcatlas/vpcatlas discover --profile audit --regions eu-west-1 --output-dir /data

On Linux add --user "$(id -u):$(id -g)" -e HOME=/home/atlas so the container can read ~/.aws and write to the output folder. A credential_process profile needs its helper binary, which the image does not contain. An SSO profile works from the mounted cache while its token is valid; for a long run, or when the token may expire, pass short-lived keys instead with -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN.

A saved graph can be drawn again without AWS: vpcatlas discover --cache vpcatlas-out/vpcatlas-graph.json --format drawio --level vpc.

Exit codes

Code	When
0	The files were written.
1	Unexpected failure: an AWS error that is not about credentials, a file that cannot be read or written, or a malformed --cache or --account-names file.
2	Bad usage: an unknown option or value, a missing --cache or --account-names file, and the checks listed on the index.
3	AWS credentials or access: none found, expired, rejected, or the role cannot be assumed.
4	Discovery finished with issues while --strict is set. The files are written first.

Details and typical causes: exit codes.