Skip to content

vpcatlas serve

vpcatlas [GLOBAL OPTIONS] serve [OPTIONS]

What it does

Starts the dashboard: live diagrams, inventory and draw.io / Lucid downloads, plus the history of earlier scans and the diff between two of them. It is part of the binary, the Python package and the Docker image; in the image it is the default command, listening on 0.0.0.0:8080.

The dashboard scans AWS when it starts and then every --refresh-seconds. While a scan runs, and after a failed one, it keeps serving the last good snapshot; a failed scan is reported in the dashboard, not as an exit code. The process runs until it is stopped.

Pages and endpoints:

Path Content
/ The diagrams, in the draw.io viewer.
/inventory The inventory as an HTML page.
/history, /diff/<older>/<newer> The earlier scans and the comparison between two of them.
/export/<page>.drawio, /export/<page>.lucid, /export/all.zip Diagram downloads.
/export/inventory.json, /export/inventory.md, /export/inventory.html Inventory downloads.
/api/status, /api/overview, /api/graph, /api/inventory, /api/diagrams, /api/history, /api/diff JSON API.
POST /refresh Start a scan now, subject to the minimum refresh interval.
/healthz Health check; never asks for a password.

--profile, --role-arn, --external-id, --session-duration, --role-session-name, --regions, --exclude-regions, --concurrency, --cache and --account-names work as in discover and take precedence over the matching VPCATLAS_* variables. serve has no --mfa-serial or --mfa-token: a one-time code cannot be used again for the refreshes, so a role that requires MFA cannot be used here. Use a role without the MFA condition, or run discover and serve its graph with --cache.

By default serve listens on 127.0.0.1 only. To reach it from another machine bind it with --host 0.0.0.0 and set VPCATLAS_AUTH_PASSWORD, so every page, API route, download and POST /refresh asks for HTTP Basic credentials (/healthz, /static/ and the API description stay open).

Options

Flag Environment variable Default Description
--host none 127.0.0.1 Address to listen on.
--port none 8080 Port to listen on (1 to 65535).
--refresh-seconds VPCATLAS_REFRESH_SECONDS 300 (0 in the Docker image) Seconds between scans; 0 scans only once.
--profile, -p VPCATLAS_PROFILE standard credential chain AWS profile. Repeat it to scan several accounts into one graph.
--role-arn VPCATLAS_ROLE_ARN none Role to assume (ARN). Repeat it to scan several accounts.
--external-id VPCATLAS_EXTERNAL_ID none ExternalId required by the role.
--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 VPCATLAS_REGIONS see below Regions to scan, comma separated. Default: every enabled region.
--exclude-regions VPCATLAS_EXCLUDE_REGIONS none Regions to leave out, comma separated.
--concurrency, -c VPCATLAS_CONCURRENCY 8 Regions scanned in parallel (1 to 32).
--cache VPCATLAS_GRAPH_FILE none Read this graph file (vpcatlas-graph.json) instead of calling AWS. The file must exist.
--account-names VPCATLAS_ACCOUNT_NAMES_FILE none JSON file that maps account ids to labels, for accounts the API cannot name. The file must exist.

The environment variable of a flag is the dashboard's alternative to it: set VPCATLAS_PROFILE and start with no flag. Only VPCATLAS_EXTERNAL_ID, VPCATLAS_SESSION_DURATION and VPCATLAS_ROLE_SESSION_NAME are also read by the other commands; VPCATLAS_REFRESH_SECONDS belongs to serve.

Regions when nothing is given. If neither --regions nor VPCATLAS_REGIONS is set, serve falls back to AWS_REGION, then AWS_DEFAULT_REGION, and scans only that region. When those are unset too, it scans every enabled region. VPCATLAS_REGIONS=all forces every region. The other commands do not read AWS_REGION for this.

Refresh floor. An automatic interval below VPCATLAS_MIN_REFRESH_SECONDS (default 300) is raised to it, and so are manual refreshes.

Settings without a flag

These variables configure the dashboard and have no flag. All are optional.

Variable Default Description
VPCATLAS_MIN_REFRESH_SECONDS 300 Floor of the automatic interval and of manual refreshes.
VPCATLAS_REFRESH_MODE background (lazy in AWS Lambda) background runs a loop in the process; lazy scans on request when the data is stale.
VPCATLAS_SCAN_ON_REQUEST true In lazy mode, let a request trigger a scan.
VPCATLAS_SNAPSHOT_URI none s3://bucket/prefix or file:///absolute/path: keep the last snapshot and the history there, so restarts and Lambda cold starts serve it without a new scan. Without it the history stays in memory.
VPCATLAS_HISTORY_KEEP 30 Snapshots the history keeps; the oldest are deleted (at least 1).
VPCATLAS_HISTORY_MIN_INTERVAL_SECONDS 0 A scan identical to the previous one and newer than this is not added to the history; a scan that differs is always kept.
VPCATLAS_BASE_PATH none URL prefix when served below a path, for example /atlas.
VPCATLAS_VIEWER_URL the hosted diagrams.net viewer-static.min.js Viewer script; an https:// URL or an absolute path.
VPCATLAS_AUTH_USER atlas User of the optional HTTP Basic protection.
VPCATLAS_AUTH_PASSWORD none When set, every page, API route and download requires HTTP Basic credentials; /healthz, /static/ and the API description are open.
VPCATLAS_LOG_LEVEL INFO Level of the vpcatlas loggers: DEBUG, INFO, WARNING, ERROR or CRITICAL.

Deployment on Docker, Lambda, Kubernetes and ECS is covered in deploy.

Files it writes

None on the command line. The dashboard builds its diagrams and inventory in memory and serves them as downloads (/export/...). With VPCATLAS_SNAPSHOT_URI it also stores the snapshots and the history at that location.

Examples

A local profile, with a scan every 15 minutes:

vpcatlas serve --profile audit --regions eu-west-1 --refresh-seconds 900
# then open http://127.0.0.1:8080

An assumed role with an external id, read from the environment, with a password on the dashboard:

export VPCATLAS_EXTERNAL_ID=my-external-id
export VPCATLAS_AUTH_PASSWORD='choose-a-long-one'
vpcatlas serve --host 0.0.0.0 \
  --role-arn arn:aws:iam::111122223333:role/VpcAtlasAuditor \
  --role-arn arn:aws:iam::444455556666:role/VpcAtlasAuditor

Docker. The image already serves on 0.0.0.0:8080; publish the port on the loopback of the host and mount the profile. The environment variables replace the flags:

docker run --rm -p 127.0.0.1:8080:8080 -v "$HOME/.aws:/home/atlas/.aws:ro" \
  -e VPCATLAS_PROFILE=audit -e VPCATLAS_REGIONS=eu-west-1 -e VPCATLAS_REFRESH_SECONDS=900 \
  vpcatlas/vpcatlas

On an EC2 instance, an ECS task or an EKS pod with a role, add no credential option at all: the dashboard finds the instance, task or web identity credentials by itself.

Exit codes

Code When
0 The server stopped normally.
1 An invalid value in a VPCATLAS_* variable, for example a role that is not an ARN or a region that is not a region name, or the port is already in use.
2 Bad usage: an unknown option or value, a missing --cache or --account-names file, a port outside 1 to 65535, and the checks listed on the index.

Credential problems do not end the process: the scan fails, the dashboard reports the error in its status, and a new scan starts at the next automatic refresh or when POST /refresh is called. Exit codes 3 and 4 do not occur here. Details: exit codes.