vpcatlas inventory

vpcatlas [GLOBAL OPTIONS] inventory [OPTIONS]

What it does

Writes only the inventory: JSON (schema id vpcatlas-inventory/1), Markdown and HTML. It scans like discover but draws no diagrams, which makes it the choice for a CMDB feed, an audit attachment or a scheduled job that compares accounts. The document lists every resource found, the accounts it refers to and every issue the scan recorded (denied calls, errors).

Credentials come from the standard chain or from the options below; see credentials. The paths of the files written go to standard output, one per line; the "Discovery summary" table goes to standard error.

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

all is the three inventory formats. A diagram format (drawio, lucid) is a usage error here; use diagram or discover for those.

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	json is selected.
vpcatlas-inventory.md	md is selected.
vpcatlas-inventory.html	html is selected.

Format: inventory, graph.

Examples

A local profile, JSON and Markdown only:

vpcatlas inventory --profile audit --regions eu-west-1,eu-central-1 --format json,md

An assumed role with an external id, failing the run when the scan recorded issues:

export VPCATLAS_EXTERNAL_ID=my-external-id
vpcatlas inventory \
  --role-arn arn:aws:iam::111122223333:role/VpcAtlasAuditor \
  --strict --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 inventory --profile audit --format json --output-dir /data

On Linux add --user "$(id -u):$(id -g)" -e HOME=/home/atlas. Inside the container a credential_process profile does not work (its helper is not in the image) and an SSO profile works only while its cached token is valid; for those, pass -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN instead.

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 (including a diagram format), 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	The scan recorded issues while --strict is set. The files are written first.

Details and typical causes: exit codes.