Graph file

vpcatlas-graph.json is the scan itself: every resource the collectors read and every relationship between them, in one file. The inventory and the diagrams are views of it. Nothing else is stored from a scan, so with this file you can redraw everything later without calling AWS.

Where it comes from

vpcatlas discover, vpcatlas inventory and vpcatlas diagram write it to the root of the output directory (--output-dir, default vpcatlas-out) whenever they read AWS:

vpcatlas-out/vpcatlas-graph.json

When you pass --cache, the command reads a graph file instead of AWS and does not write a new one.

What reads it

Reader	How
vpcatlas diagram --cache vpcatlas-graph.json	Draws the diagrams again, with no AWS calls and no credentials.
vpcatlas inventory --cache ... and vpcatlas discover --cache ...	Rebuild the inventory (and the diagrams) from the file.
vpcatlas serve --cache ...	Starts the dashboard on a saved scan.
The dashboard snapshots	Each snapshot holds the graph of its scan in its graph field, next to the inventory and the rendered pages. The history of snapshots and the diff between two of them compare graphs. GET /api/graph returns the graph of the latest snapshot, and the zip from /export/all.zip carries it as graph.json.

# scan once, keep the graph
vpcatlas discover --profile prod --output-dir scan-2026-10-17

# redraw later, offline
vpcatlas diagram --cache scan-2026-10-17/vpcatlas-graph.json --output-dir redraw

Format

The file is JSON, indented by two spaces, with object keys sorted. Nodes are sorted by key and edges by source, destination and kind, so the same scan always writes the same bytes.

The schema id is vpcatlas-graph/1. A reader refuses a file with another schema id (unsupported graph schema ...) and a file that holds a resource type it does not know (unknown resource type ...), instead of guessing. The inventory has its own id, vpcatlas-inventory/1; the two version independently.

Key	Type	Meaning
schema	string	vpcatlas-graph/1.
generated_at	string	Time of the scan, UTC, YYYY-MM-DDTHH:MM:SSZ. The diagrams print this time in their legend, and the inventory carries it as its own generated_at.
meta	object	How the scan ran: tool (vpcatlas), version, partition, regions (scanned), unavailable_regions (regions that could not be reached), collectors (names of the collectors that ran) and duration_seconds. When several accounts are merged, lists are united and sorted and other values keep the first one.
audited_accounts	list of strings	The ids of the accounts the scan had credentials for.
nodes	list of objects	The resources, below.
edges	list of objects	The relationships, below.
gaps	list of objects	The calls that failed, below.

Nodes

Every node has these keys:

Key	Type	Meaning
type	string	The resource type id, for example vpc, subnet, tgw, lb, hosted_zone. The inventory's summary.by_type uses the same ids.
id	string	The AWS id, or the name or ARN tail for a resource without an id.
key	string	The node key, <account>/<region>/<type>/<id>. An account is keyed account:<id>. A stub, a resource that was referenced but never described, is keyed external:<id>.
arn	string or null	The ARN, when the API returns one.
account_id	string	The owner of the resource.
region	string	A region code, or global for an account-wide resource.
name	string or null	The Name tag, or the native name.
state	string or null	The state the API reports.
tags	object of strings	The tags.
raw	object	The item the API returned, trimmed: secrets and tags are removed, and some long members are dropped.
seen_by	list of strings	The audited accounts whose credentials saw it.
stub	boolean	true for a node that was referenced and not described. A scan of a second account replaces the stubs it can now resolve.
findings	list of strings	Observations the scan made about the resource.

Besides these, each type has its own fields (a VPC has its CIDR blocks, a route table its routes and associations, a load balancer its scheme and listeners, and so on). They are the source of the details of the inventory rows.

The types are, grouped as the coverage list groups them: account, external_account, region; the network (vpc, subnet, route_table, igw, eigw, nat, eni, sg, nacl, prefix_list, tgw, tgw_attachment, tgw_route_table, peering, vgw, cgw, vpn, dx_connection, dx_gateway, dx_vif, endpoint, endpoint_service, lb, nfw, nfw_policy, resolver_endpoint, resolver_rule, ram_share); and the service layer (hosted_zone, cloudfront, web_acl, certificate, shield, api_gateway, api_vpc_link, target_group, ecs_cluster, ecs_service, eks_cluster, instance_group, rds, elasticache, efs, lambda, s3_bucket, s3, dynamodb, cloudtrail, guardduty, config_recorder, cloudwatch, kms, ecr).

Edges

Key	Type	Meaning
src	string	The key of the node the edge starts at.
dst	string	The key of the node it ends at.
kind	string	The relationship, from the list below. Two nodes can be linked by several kinds.
attrs	object	Attributes of the relationship; see the table.

Kind	Meaning
contains	Parent to child: account, region, VPC, subnet and what sits in them. A node has at most one parent.
attached_to	A resource to what it is attached to. relation says which.
routes_to	A route table to the target of its routes. routes lists them.
peered_with	Requester to accepter, for VPC peerings and Transit Gateway peerings.
shared_from	A resource owned by another account to that account.
serves	A Route 53 hosted zone to the target of one of its records (record, record_type).
origin	A CloudFront distribution to an origin (origin_id, path, access: oac, oai or none).
protects	A web ACL or Shield to the resource it covers (via: web_acl or shield).
secures	An ACM certificate to a load balancer, a distribution or an API (use: listener, distribution or domain).
integrates	An API Gateway API to a function, a load balancer or a VPC link; a VPC link to the load balancer it reaches.
targets	A load balancer to its target groups (port), a target group to its targets (health).
attaches	An ECS service or an Auto Scaling group to the target group it registers in (port).
mounts	An EFS file system to the subnets of its mount targets (ip_address, mount_target).

Gaps

A gap is a call that could not be completed. The scan continues; the inventory lists gaps as issues.

Key	Type	Meaning
service	string	The boto3 client name.
operation	string	The operation.
code	string	The AWS error code, or a code the tool assigns when the failure is not an AWS error.
message	string	The message.
region	string or null	The region.
account_id	string or null	The account.

Handle it like the inventory

The graph holds ARNs, account ids, tags, CIDR blocks, security group rules and routes. The tool strips secrets from the items it keeps, but the file still describes your network in detail. Store it with the access you give to the diagrams.