runbooks vpc¶
Find | 14 commands | Networking. Auto-generated from Click registry on 2026-06-26.
QA/QC: 0/14 commands PASSED (v1.3.17)
L1 --help: 0/14 | 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-profile |
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) |
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
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-profile --region $AWS_REGION
runbooks finops dashboard --all-profile --format table
Org-Wide Profile Routing — 4-Step Methodology¶
Each AWS profile has exactly one correct purpose. Mixing them returns empty results, not errors
(CROSS_ACCOUNT_SILENT_ZERO anti-pattern).
Authoritative standard (DISC-001): .claude/skills/aws/org-wide-resource-discovery.md — canonical 4-step methodology with P-ENRICH ranking and Config aggregator vs Resource Explorer priority. See also: aws-profile-semantics.md.
| Step | Name | Profile Env Var | Flag | API / Service | What-If Wrong |
|---|---|---|---|---|---|
| 1. DISCOVER | Org-wide resource inventory | $AWS_OPERATIONS_PROFILE |
--all-profile |
P1 (authoritative, un-capped): AWS Config aggregator (runbooks inventory resource-explorer default backend) — all accounts, paginated, no 1,000-result ceiling. P3 (cross-check only): Resource Explorer Search API — capped at 1,000 results per query; treat any count of exactly 1,000 as suspect. |
Wrong profile → aggregator index not found → silent-zero count |
| 2. ENUMERATE | Account names & IDs | $AWS_MANAGEMENT_PROFILE |
--all-profile |
AWS Organizations ListAccounts |
Wrong profile → empty account list → can't resolve resource owners |
| 3. ENRICH | Per-account attributes | Per-workload ~/.aws/config profile |
--profile |
Single-account describe-* / get-* (encryption, lifecycle, tags — aggregator can't return these) |
Skip this step → counts + cost present but target columns NULL |
| 4. COST | Cost attribution | $AWS_BILLING_PROFILE |
--all-profile |
Cost Explorer GetCostAndUsage |
Wrong profile → no CE access → cost columns blank or AccessDenied |
When to use --profile vs --all-profile
--all-profile $AWS_<PURPOSE>_PROFILE— Landing Zone-wide (hub accounts: Operations, Management, Billing). Always use the matching env var; never pass an LZ-wide profile with--profile.--profile $AWS_PROFILE— Single workload account only (Steps 3 + per-workload incident investigation).
Using --profile with an LZ-wide profile env var (e.g. --profile $AWS_BILLING_PROFILE) is a routing bug — the LZ hub account has no workload resources, so results are silently empty.
--all-profile flag behaviour differs by command group
--all-profile is value-taking (accepts a profile string) for finops, inventory, cfat, vpc, csdm, and workspaces command groups. For runbooks security, --all-profile is a boolean flag (bare, no value). Always use runbooks security baseline --all-profile (no value); never --all-profile $AWS_OPERATIONS_PROFILE for security commands.
# Step 1 — DISCOVER org-wide (Config aggregator, un-capped, P1 authoritative)
runbooks inventory resource-explorer --all-profile $AWS_OPERATIONS_PROFILE
# Step 2 — ENUMERATE accounts (Organizations API)
runbooks inventory discover --all-profile $AWS_MANAGEMENT_PROFILE
# Step 3 — ENRICH per-account (loop each workload profile from ~/.aws/config)
# Resolve account_id -> profile_name via runbooks.common.resolve_readonly_profile() (RB-3):
# from runbooks.common import resolve_readonly_profile
# profile = resolve_readonly_profile(account_id) # canonical account_id->profile resolver
runbooks security scan --profile $AWS_PROFILE # one call per workload account
# Step 4 — COST (Cost Explorer, org-wide consolidated billing)
runbooks finops dashboard --all-profile $AWS_BILLING_PROFILE
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. | 17 | 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 |
flow-log-query |
Query VPC flow logs in CloudWatch Logs Insights for traffic to/from an IP address. | 7 | read-only |
nat-gateway |
NAT Gateway cost optimization and rightsizing analysis. | 15 | read-only |
network-discover |
Multi-account network discovery with architecture diagrams. | 6 | read-only |
tgw |
Transit Gateway multi-account discovery and analysis. | 0 | read-only |
tgw diagram |
Render TGW PNG diagrams from evidence (no AWS API calls). | 3 | read-only |
tgw discover |
Multi-account TGW discovery (Phase 1). | 3 | read-only |
tgw hub-binding |
Identify hub TGW via hub_score formula (Phase 3). | 4 | read-only |
tgw hybrid |
Hybrid connectivity analysis — DX, VPN, TGW peerings. | 4 | read-only |
tgw routes |
Analyze TGW route tables and detect blackhole routes. | 4 | 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.
| 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.
All Parameters (17)
| 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-profile |
STRING | - | Multi-account profile for org-wide VPC analysis (A1-Discovery). |
--config |
PATH | - | Path to YAML campaign configuration file (config-driven analysis) |
--instance-ip |
STRING | - | Filter VPC flow log analysis to traffic to/from a specific IP address. |
runbooks vpc analyze-endpoint-activity¶
Analyze VPC endpoint activity via CloudTrail (90-day lookback).
All Parameters (7)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profile |
STRING | - | AWS profile for VPC endpoint discovery (per-workload, A1-Investigate). |
--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) |
--format/--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.
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 flow-log-query¶
Query VPC flow logs in CloudWatch Logs Insights for traffic to/from an IP address.
All Parameters (7)
| 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) |
--instance-ip |
STRING | - | IP address to query flow logs for (e.g. |
--vpc-id |
STRING | - | VPC ID that owns the flow logs (e.g. |
--days |
INT | 7 |
Lookback window in days (default: 7) |
--output |
CHOICE(table | json) | table |
runbooks vpc nat-gateway¶
NAT Gateway cost optimization and rightsizing analysis.
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-profile |
STRING | - | Multi-account profile for org-wide NAT Gateway analysis (A1-Discovery). |
runbooks vpc network-discover¶
Multi-account network discovery with architecture diagrams.
All Parameters (6)
| Parameter | Type | Default | Description |
|---|---|---|---|
--profiles/-p |
STRING | - | [DEPRECATED v1.5.1] Use --all-profile $AWS_OPERATIONS_PROFILE per ADR-006 §A1-Discovery. |
--all-profile |
STRING | - | Multi-account profile for Resource Explorer aggregator (defaults to $AWS_OPERATIONS_PROFILE). |
--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 tgw¶
Transit Gateway multi-account discovery and analysis.
runbooks vpc tgw diagram¶
Render TGW PNG diagrams from evidence (no AWS API calls).
| Parameter | Type | Default | Description |
|---|---|---|---|
--type |
CHOICE(topology | hybrid | route-flow |
--evidence-dir |
PATH | - | Evidence directory (from discover/hub-binding outputs) |
--output-dir |
PATH | - | Output directory for PNG files |
runbooks vpc tgw discover¶
Multi-account TGW discovery (Phase 1).
| Parameter | Type | Default | Description |
|---|---|---|---|
--management-profile |
STRING | - | AWS profile for Organizations list-accounts (env: $AWS_MANAGEMENT_PROFILE) |
--region |
STRING | - | AWS region (env: $AWS_REGION) |
--output |
PATH | - | Output JSON evidence file |
runbooks vpc tgw hub-binding¶
Identify hub TGW via hub_score formula (Phase 3).
| Parameter | Type | Default | Description |
|---|---|---|---|
--evidence |
PATH | - | Phase 1 discover JSON evidence file |
--output |
PATH | - | Output JSON evidence file |
--network-ou-id |
STRING | - | Optional AWS Organizations Network OU ID for NetworkOU signal |
--terraform-state |
PATH | - | Optional path to terraform.tfstate for IaC managed signal |
runbooks vpc tgw hybrid¶
Hybrid connectivity analysis — DX, VPN, TGW peerings.
| Parameter | Type | Default | Description |
|---|---|---|---|
--hub-profile |
STRING | - | AWS profile for hub account queries (env: $AWS_OPERATIONS_PROFILE) |
--management-profile |
STRING | - | AWS profile for Organizations queries (env: $AWS_MANAGEMENT_PROFILE) |
--region |
STRING | - | AWS region |
--output |
PATH | - | Output JSON evidence file |
runbooks vpc tgw routes¶
Analyze TGW route tables and detect blackhole routes.
| Parameter | Type | Default | Description |
|---|---|---|---|
--hub-profile |
STRING | - | AWS profile for hub account TGW route queries (env: $AWS_OPERATIONS_PROFILE) |
--tgw-id |
STRING | - | Transit Gateway ID to analyze (e.g. |
--region |
STRING | - | AWS region |
--output |
PATH | - | Output JSON evidence file |
runbooks vpc topology¶
Generate network topology diagrams with cost correlation and universal profile support.
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-profile |
STRING | - | Multi-account profile for org-wide topology generation (A1-Discovery). |
runbooks vpc vpce-cleanup¶
Write Operation
This command modifies AWS resources. Use --dry-run when available.
Analyze VPC endpoint cleanup candidates and calculate savings.
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 |