runbooks vpc¶

Find | Track | 7 commands. Auto-generated from Click registry on 2026-04-01.

QA/QC: 7/7 commands PASSED (v1.3.17)

L1 --help: 7/7 | L2 params: PASS | L4 cross-validation: N/A

First time? Set up your AWS profiles

Before running any command, configure your AWS SSO profiles. See the Single Account or Multi-Account Landing Zone tabs below for copy-paste setup blocks.

AWS Profile Configuration¶

All runbooks commands support these common options for AWS authentication:

Option	Scope	When to Use
`--profile PROFILE`	Single account	Developer/operator targeting one AWS account
`--all-profiles`	All accounts (Landing Zone)	Platform team — discovers across all SSO profiles
`--region REGION`	Override region	Non-default region (default: `ap-southeast-2`)
`--dry-run`	Safe mode	Analysis only, no mutations (recommended for first run)
`--output-dir DIR`	Output path	Directory for generated reports (default: `output/`)
`--format FORMAT`	Output format	`table`, `json`, `csv`, `markdown` (varies by command)

Single Account

Copy and configure:

# =============================================================
# AWS Single Account Configuration
# =============================================================
export AWS_REGION="ap-southeast-2"
export AWS_PROFILE="your-account-profile"

# Authenticate via SSO
aws sso login --profile $AWS_PROFILE

# Verify
aws sts get-caller-identity --profile $AWS_PROFILE

# Run any command
runbooks finops dashboard --profile $AWS_PROFILE

Multi-Account Landing Zone

Copy and configure all 4 environment variables:

# =============================================================
# AWS Multi-Account Landing Zone Configuration
# =============================================================
export AWS_REGION="ap-southeast-2"

## Single account (default fallback)
export AWS_PROFILE="your-default-profile"

## FinOps/Billing profile (READ-ONLY access to Cost Explorer)
export AWS_BILLING_PROFILE="your-billing-readonly-profile"

## Management account profile (Organizations, Control Tower)
export AWS_MANAGEMENT_PROFILE="your-management-readonly-profile"

## Centralized Operations account profile (for shared resources)
export AWS_OPERATIONS_PROFILE="your-operations-readonly-profile"

# =============================================================
# Authenticate all profiles
# =============================================================
aws sso login --profile $AWS_BILLING_PROFILE
aws sso login --profile $AWS_MANAGEMENT_PROFILE
aws sso login --profile $AWS_OPERATIONS_PROFILE

# =============================================================
# Verify connectivity
# =============================================================
aws sts get-caller-identity --profile $AWS_BILLING_PROFILE
aws sts get-caller-identity --profile $AWS_MANAGEMENT_PROFILE

# =============================================================
# Run org-wide commands
# =============================================================
runbooks inventory collect --all-profiles --region $AWS_REGION
runbooks finops dashboard --all-profiles --format table

Environment Variables Reference¶

Variable	Required	Purpose
`AWS_REGION`	Yes	Target AWS region (default: `ap-southeast-2`)
`AWS_PROFILE`	Yes	Default profile when `--profile` is omitted
`AWS_BILLING_PROFILE`	LZ only	Cost Explorer data enrichment
`AWS_MANAGEMENT_PROFILE`	LZ only	Organizations metadata enrichment
`AWS_OPERATIONS_PROFILE`	LZ only	Centralized Operations shared resources
`RUNBOOKS_TEST_MODE`	No	Set to `1` for offline/mock mode (no AWS calls)

Commands¶

Command	Description	Params	API Type
`analyze`	Comprehensive VPC network analysis with cost optimization.	16	read-only
`analyze-endpoint-activity`	Analyze VPC endpoint activity via CloudTrail (90-day lookback).	7	read-only
`discover-firewall-bypass`	Discover VPCs NOT routing through central firewall for inspection.	7	read-only
`nat-gateway`	NAT Gateway cost optimization and rightsizing analysis.	15	read-only
`network-discover`	Multi-account network discovery with architecture diagrams.	5	read-only
`topology`	Generate network topology diagrams with cost correlation and universal profile support.	14	read-only
`vpce-cleanup`	Analyze VPC endpoint cleanup candidates and calculate savings.	8	write

Quick Start by Role¶

VPC network analysis, topology mapping, and endpoint cleanup.

Executive TechLead Engineer / SRE

Task	Command
Network overview	`runbooks inventory vpc topology --profile $AWS_PROFILE`

Task	Command
VPC topology	`runbooks inventory vpc topology --profile $AWS_PROFILE --output /tmp/vpc.json`
Endpoint analysis	`runbooks inventory vpc vpce-analysis --profile $AWS_PROFILE`

Task	Command
Security groups	`runbooks inventory vpc security-groups --profile $AWS_PROFILE`
Flow log analysis	`runbooks inventory vpc flow-summary --profile $AWS_PROFILE`

Command Details¶

`runbooks vpc analyze`¶

Comprehensive VPC network analysis with cost optimization.

Single AccountMulti-Account Landing Zone

runbooks vpc analyze --profile $AWS_PROFILE

runbooks vpc analyze --all

All Parameters (16)

Parameter	Type	Default	Description
`--profile`	STRING	-	AWS profile for single-account operations.
`--region`	STRING	`ap-southeast-2`	AWS region override (default: ap-southeast-2)
`--dry-run`	BOOL	`True`	Safe analysis mode - no resource modifications (enterprise default)
`-f/--format/--output-format`	CHOICE(json	csv	table
`--output-dir`	PATH	`./ops_evidence`	Directory for generated files and evidence packages
`--all-outputs`	BOOL	`False`	Generate all output formats (JSON, CSV, PDF, Markdown) - use with --output-dir
`--csv`	BOOL	`False`	Export to CSV format (convenience flag, activates --all-outputs)
`--json`	BOOL	`False`	Export to JSON format (convenience flag, activates --all-outputs)
`--markdown`	BOOL	`False`	Export to Markdown format (convenience flag, activates --all-outputs)
`--export`	BOOL	`False`	[DEPRECATED] Use --all-outputs instead
`--cost-optimization`	BOOL	`False`	Include cost optimization analysis
`--topology-analysis`	BOOL	`False`	Include network topology analysis
`--security-assessment`	BOOL	`False`	Include security configuration review
`--savings-target`	FLOAT_RANGE	`0.3`	Target savings percentage for optimization
`--all`	BOOL	`False`	Use all available AWS profiles for multi-account VPC analysis
`--config`	PATH	-	Path to YAML campaign configuration file (config-driven analysis)

`runbooks vpc analyze-endpoint-activity`¶

Analyze VPC endpoint activity via CloudTrail (90-day lookback).

runbooks vpc analyze-endpoint-activity --profile $AWS_PROFILE

All Parameters (7)

Parameter	Type	Default	Description
`--profile`	STRING	-	AWS profile for VPC endpoint discovery
`--management-profile`	STRING	-	AWS profile for CloudTrail access (default: profile)
`--regions`	STRING	`('ap-southeast-2',)`	AWS regions to scan
`--lookback-days`	INT	`90`	CloudTrail lookback period (max: 90 days)
`--output-format`	CHOICE(csv	xlsx	json)
`--output-file`	PATH	`/tmp/vpce-activity-analysis.xlsx`	Output file path
`--output-dir`	PATH	`.`	Output directory for exported files

`runbooks vpc discover-firewall-bypass`¶

Discover VPCs NOT routing through central firewall for inspection.

runbooks vpc discover-firewall-bypass --profile $AWS_PROFILE

All Parameters (7)

Parameter	Type	Default	Description
`--management-profile`	STRING	-	AWS profile for Organizations access
`--operational-profile`	STRING	-	AWS profile for networking resources
`--billing-profile`	STRING	-	AWS profile for cost analysis
`--regions`	STRING	`('ap-southeast-2',)`	AWS regions to scan
`--export`	CHOICE(csv	excel	json
`--output-dir`	PATH	`data`	Output directory for exports
`--profile`	STRING	-	AWS profile (KISS: auto-resolves management/billing/ops from AWS_MANAGEMENT_PROFILE, AWS_BILLING_PROFILE env vars)

`runbooks vpc nat-gateway`¶

NAT Gateway cost optimization and rightsizing analysis.

Single AccountMulti-Account Landing Zone

runbooks vpc nat-gateway --profile $AWS_PROFILE

runbooks vpc nat-gateway --all

All Parameters (15)

Parameter	Type	Default	Description
`--profile`	STRING	-	AWS profile for single-account operations.
`--region`	STRING	`ap-southeast-2`	AWS region override (default: ap-southeast-2)
`--dry-run`	BOOL	`True`	Safe analysis mode - no resource modifications (enterprise default)
`-f/--format/--output-format`	CHOICE(json	csv	table
`--output-dir`	PATH	`./ops_evidence`	Directory for generated files and evidence packages
`--all-outputs`	BOOL	`False`	Generate all output formats (JSON, CSV, PDF, Markdown) - use with --output-dir
`--csv`	BOOL	`False`	Export to CSV format (convenience flag, activates --all-outputs)
`--json`	BOOL	`False`	Export to JSON format (convenience flag, activates --all-outputs)
`--markdown`	BOOL	`False`	Export to Markdown format (convenience flag, activates --all-outputs)
`--export`	BOOL	`False`	[DEPRECATED] Use --all-outputs instead
`--analyze`	BOOL	`False`	Analyze NAT Gateway usage and costs
`--optimize`	BOOL	`False`	Generate optimization recommendations
`--savings-target`	FLOAT_RANGE	`0.3`	Target savings percentage
`--include-alternatives`	BOOL	`False`	Include NAT instance alternatives
`--all`	BOOL	`False`	Use all available AWS profiles for multi-account NAT Gateway analysis

`runbooks vpc network-discover`¶

Multi-account network discovery with architecture diagrams.

runbooks vpc network-discover

Parameter	Type	Default	Description
`--profiles/-p`	STRING	-	AWS profile(s) to discover
`--region/-r`	STRING	`ap-southeast-2`	AWS region
`--output-dir`	PATH	`artifacts/network-discovery`	Output directory
`--export`	CHOICE(all	json	excel
`--diagrams`	BOOL	`True`	Generate architecture diagrams (PNG+SVG)

`runbooks vpc topology`¶

Generate network topology diagrams with cost correlation and universal profile support.

Single AccountMulti-Account Landing Zone

runbooks vpc topology --profile $AWS_PROFILE

runbooks vpc topology --all

All Parameters (14)

Parameter	Type	Default	Description
`--profile`	STRING	-	AWS profile for single-account operations.
`--region`	STRING	`ap-southeast-2`	AWS region override (default: ap-southeast-2)
`--dry-run`	BOOL	`True`	Safe analysis mode - no resource modifications (enterprise default)
`-f/--format/--output-format`	CHOICE(json	csv	table
`--output-dir`	PATH	`./ops_evidence`	Directory for generated files and evidence packages
`--all-outputs`	BOOL	`False`	Generate all output formats (JSON, CSV, PDF, Markdown) - use with --output-dir
`--csv`	BOOL	`False`	Export to CSV format (convenience flag, activates --all-outputs)
`--json`	BOOL	`False`	Export to JSON format (convenience flag, activates --all-outputs)
`--markdown`	BOOL	`False`	Export to Markdown format (convenience flag, activates --all-outputs)
`--export`	BOOL	`False`	[DEPRECATED] Use --all-outputs instead
`--include-costs`	BOOL	`False`	Include cost analysis in topology
`--detail-level`	CHOICE(basic	detailed	comprehensive)
`--output-dir`	STRING	`./vpc_topology`	Output directory
`--all`	BOOL	`False`	Use all available AWS profiles for multi-account topology generation

`runbooks vpc vpce-cleanup`¶

Write Operation

This command modifies AWS resources. Use --dry-run when available.

Analyze VPC endpoint cleanup candidates and calculate savings.

runbooks vpc vpce-cleanup --profile $AWS_PROFILE

All Parameters (8)

Parameter	Type	Default	Description
`--profile`	STRING	-	AWS profile for single-account operations.
`--region`	STRING	`ap-southeast-2`	AWS region override (default: ap-southeast-2)
`--dry-run`	BOOL	`True`	Safe analysis mode - no resource modifications (enterprise default)
`--csv-file`	PATH	-	CSV file with VPCE cleanup data
`--validate`	BOOL	`False`	Validate VPCEs exist via AWS API
`--generate-commands`	BOOL	`False`	Generate cleanup script
`--claimed-annual`	FLOAT	-	Claimed annual savings for comparison
`--output-dir`	PATH	`tmp`	Output directory

Usage Examples¶

graph LR
    A[":material-network: analyze"] -->|"network map"| B[":material-sitemap: topology"]
    B -->|"unused endpoints"| C[":material-delete: vpce-cleanup --dry-run"]
    C -->|"HITL approval"| D[":material-delete: vpce-cleanup"]
    style A fill:#4CAF50,color:#fff
    style C fill:#FF9800,color:#fff
    style D fill:#f44336,color:#fff

VPC Network Audit

# 1. Analyze VPC
runbooks inventory vpc topology --profile $AWS_PROFILE

# 2. Find unused endpoints
runbooks inventory vpc vpce-analysis --profile $AWS_PROFILE

# 3. Security group audit
runbooks inventory vpc security-groups --profile $AWS_PROFILE

Single AccountMulti-Account Landing Zone

# VPC topology for one account
runbooks vpc topology \
  --profile $AWS_PROFILE \
  --region $AWS_REGION

# NAT Gateway cost analysis
runbooks vpc nat-gateway \
  --profile $AWS_PROFILE

# VPCE cleanup analysis (dry-run)
runbooks vpc vpce-cleanup \
  --profile $AWS_PROFILE \
  --dry-run

# Cross-account VPC analysis
runbooks vpc analyze --all \
  --output-dir output/vpc/

# Network Firewall bypass detection across org
runbooks vpc discover-firewall-bypass \
  --management-profile $AWS_MANAGEMENT_PROFILE \
  --operational-profile $AWS_OPERATIONS_PROFILE \
  --billing-profile $AWS_BILLING_PROFILE

# Org-wide NAT Gateway optimization
runbooks vpc nat-gateway --all

Write Commands

vpce-cleanup can modify VPC endpoints. Always use --dry-run first:

runbooks vpc vpce-cleanup --profile my-account --dry-run

runbooks vpc¶

AWS Profile Configuration¶

Environment Variables Reference¶

Commands¶

Quick Start by Role¶

Command Details¶

runbooks vpc analyze¶

runbooks vpc analyze-endpoint-activity¶

runbooks vpc discover-firewall-bypass¶

runbooks vpc nat-gateway¶

runbooks vpc network-discover¶

runbooks vpc topology¶

runbooks vpc vpce-cleanup¶

Usage Examples¶

`runbooks vpc analyze`¶

`runbooks vpc analyze-endpoint-activity`¶

`runbooks vpc discover-firewall-bypass`¶

`runbooks vpc nat-gateway`¶

`runbooks vpc network-discover`¶

`runbooks vpc topology`¶

`runbooks vpc vpce-cleanup`¶