Runbooks CLI Commands Catalog¶
Generated from
runbooks --helpon 2026-06-21 | runbooks v1.5.0 | 16 command groups
For functional area guidance: Start with CxO End-to-End Walkthrough (narrative) → Cloud Foundations Functional Area Runbooks (doctrine) → This page (detailed reference).
By Board-Risk Domain¶
| Domain | CLI Groups | Purpose | See Also |
|---|---|---|---|
| 1. Business Continuity | inventory, cfat |
Org-wide backup coverage, disaster recovery | Cloud Foundations §1 |
| 2. Operations | inventory, operate, itsm |
Patch Manager baseline, patch compliance, change management | Cloud Foundations §2 |
| 3. Finance | finops, workspaces, validation |
Cost attribution, tag enforcement, optimization recommendations | Cloud Foundations §3 |
| 4. Governance | cfat, inventory, validation |
OU-level SCP inheritance, Config compliance, audit automation | Cloud Foundations §4 |
| 5. Security | security, cert, remediation |
GuardDuty 100% enrollment, compliance baselines, findings remediation | Cloud Foundations §5 |
| 6. Infrastructure | vpc, inventory, operate |
Network baselines, drift detection, resource provisioning | Cloud Foundations §6 |
Summary¶
| Group | Commands | Purpose |
|---|---|---|
| inventory | 46 | Multi-account resource discovery & enrichment (88 AWS resource types) |
| finops | 43 | Cost analysis, optimization recommendations, budget tracking |
| security | 6 | Compliance frameworks (SOC2, PCI-DSS, HIPAA, ISO27001), baselines |
| remediation | 4 | Close security findings: S3, IAM, CloudTrail, encryption |
| cfat | 3 | Cloud Foundations Assessment Tool maturity scoring |
| vpc | 7 | Network architecture validation, flow logs, cost optimization |
| validation | 8 | Cross-validation gates, accuracy benchmarking |
| cert | 5 | Certificate discovery & expiry monitoring |
| operate | 5 | Resource operations: EC2 start/stop, S3 provisioning, IaC deploy |
| itsm | (see inventory) | ITSM integration (change records, incidents) |
| workspaces | (see finops) | WorkSpaces cost analysis & decommission scoring |
| csdm | internal | CMDB/CSDM exports (ServiceNow integration prep) |
| orr | internal | Organization resources registry |
| cloudops | internal | Platform team utilities |
| common | internal | Shared CLI infrastructure |
| mcp | internal | MCP server integration |
Commands by Group¶
finops¶
Usage: runbooks finops [OPTIONS] COMMAND [ARGS]...
Financial operations and cost optimization for AWS resources.
Comprehensive cost analysis, budget management, and financial reporting with
multi-format export capabilities.
Features: • Real-time cost analysis with MCP validation • Multi-format exports:
CSV, JSON, PDF, Markdown • Quarterly intelligence with strategic financial
reporting • Enterprise AWS profile support with multi-account capabilities
Examples: runbooks finops dashboard --profile billing-profile
runbooks finops dashboard --all-profiles --timeframe monthly runbooks
finops dashboard --regions ap-southeast-2 ap-southeast-6 runbooks finops
export --format pdf --output-dir ./reports
Options:
--tags TEXT Filter by tags (key=value format)
--accounts TEXT Filter by specific account IDs
--all Multi-account discovery
(CENTRALISED_OPS_PROFILE as aggregator).
📋 Behavior: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━
• Queries AWS Resource Explorer aggregator
index • Discovers resources across ALL
accounts in Landing Zone • Requires
CENTRALISED_OPS_PROFILE with cross-account
permissions
🔐 Enrichment Layers (Automatic): •
Organizations metadata: MANAGEMENT_PROFILE
• Cost data: BILLING_PROFILE Note:
Enrichment uses separate profiles regardless
of discovery mode
Use Case: Enterprise platform teams managing
67+ account Landing Zones
--profiles TEXT Specific AWS profiles (comma-separated,
e.g., "billing,security,audit")
--regions TEXT Specific AWS regions (space-separated)
--all-regions Process all enabled AWS regions
-f, --format, --output-format [json|csv|table|pdf|markdown]
Output format for results display
(-f/--format preferred, --output-format
legacy)
--output-dir PATH Directory for generated files and evidence
packages
--all-outputs Generate all output formats (JSON, CSV, PDF,
Markdown) - use with --output-dir
--csv Export to CSV format (convenience flag,
activates --all-outputs)
--json Export to JSON format (convenience flag,
activates --all-outputs)
--markdown Export to Markdown format (convenience flag,
activates --all-outputs)
--profile TEXT AWS profile for single-account operations.
📋 Profile Selection Guide: ━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Single Account → Use --profile YOUR_PROFILE
Example: --profile dev-account When:
Developer/operator working in one AWS
account
Multi-Account LZ → Use --all-profiles (see
inventory commands) Example: --all-
profiles When: Platform team discovering
across organization
🔐 Enrichment Profiles (Automatic): •
Organizations: MANAGEMENT_PROFILE • Costs:
BILLING_PROFILE Note: Separate from
discovery profile
Decision: Single account = --profile |
Multi-account = --all-profiles
--region TEXT AWS region override (default: ap-
southeast-2)
--dry-run Safe analysis mode - no resource
modifications (enterprise default)
--help Show this message and exit.
Commands:
analyze-ec2 EC2 cost analysis with 4-way enrichment.
analyze-graviton-eligibility Graviton migration eligibility...
analyze-s3-storage-lens Analyze S3 Storage Lens metrics for...
analyze-workspaces WorkSpaces cost analysis with...
appstream-decommission-analysis
AppStream decommission analysis with...
azure Azure Cost Management analysis.
azure anomaly Detect cost anomalies (spending spikes).
azure daily Daily cost breakdown by Azure service.
azure monthly Monthly cost summary with subscription breakdown.
azure preflight Pre-flight auth and access validation for Azure FinOps.
azure validate Validate SDK against Azure native API (ground truth).
check-config-compliance Check AWS Config compliance and map...
cost-drops Detect month-over-month cost drops...
dashboard Multi-account cost visibility with...
detect-orphans Detect orphaned AWS resources across...
detect-rds-idle Detect idle RDS instances for $50K...
ec2-decommission-analysis EC2 decommission analysis with E1-E7...
ec2-snapshots EC2 snapshot cost optimization and...
enrich-workspaces Enrich WorkSpaces inventory with...
export Export financial analysis results in...
infrastructure Infrastructure cost optimization analysis
infrastructure analyze Comprehensive infrastructure optimization analysis
infrastructure elastic-ip Elastic IP cost optimization analysis
infrastructure load-balancer Load Balancer cost optimization analysis
infrastructure nat-gateway NAT Gateway cost optimization analysis
infrastructure vpc-endpoint VPC Endpoint cost optimization analysis
lambda-analysis Lambda cost and activity analysis...
optimize Generate cost optimization...
optimize-cloudwatch-costs Analyze and optimize CloudWatch log...
optimize-s3-lifecycle S3 Lifecycle Optimizer - Automated...
optimize-savings-plans Generate hybrid Savings Plans + RI...
scenario Execute a FinOps business scenario...
sprint1 Run Sprint 1 cost optimization analysis.
validate 4-Way Validation: HTML vs CSV vs MCP...
validate-with-mcp Validate runbooks cost projections...
vizro Launch interactive Vizro FinOps...
workspaces-decommission-analysis
WorkSpaces decommission analysis with...
inventory¶
Runbooks Inventory - Multi-account AWS resource discovery
📋 Command Categories (40 operations across 9 categories):
1️⃣ Discovery: resource-explorer (88 AWS resource types)
2️⃣ Organizations: org-*, accounts-* (multi-account management)
3️⃣ VPC/Network: vpc-*, nat-*, elb-* (network architecture)
4️⃣ CloudFormation: cfn-*, stack-* (IaC drift detection)
5️⃣ Activity/Scoring: enrich-*, score-* (decommission analysis)
6️⃣ Security/Compliance: security-*, audit-*, check-*
7️⃣ Workflows: workflow-*, pipeline-* (automated pipelines)
8️⃣ Validation: validate-*, verify-* (MCP cross-validation)
9️⃣ Utilities: export-*, clean-*, show-* (helper commands)
Inventory Commands (46 commands)
Commands (46):
collect Multi-account resource discovery via Resource Explorer
resource-explorer Discover resources by friendly alias (88 types)
resource-types List all 88 supported resource types
discover-rds RDS database discovery
discover-lambda Lambda function discovery
workspaces WorkSpaces discovery (6-phase investigation)
collect-containers Container discovery (ECS clusters, tasks, services)
list-org-accounts List AWS accounts in organization
list-org-users List IAM users across organization
draw-org Visualize organization hierarchy
check-landingzone Validate Landing Zone configuration
check-controltower Validate Control Tower setup
find-lz-versions Discover Landing Zone versions
collect-ram-shares Discover AWS RAM shares
enrich-accounts Add Organizations metadata
enrich-costs Add cost data from Cost Explorer
enrich-activity Add CloudTrail activity signals
enrich-ec2 EC2-specific enrichment (now includes SSM columns)
score-decommission Score decommission candidates (E1-E8/W1-W6, now includes SSM heartbeat)
vpc flow-logs VPC Flow Logs discovery and analysis
vpc nat-traffic NAT Gateway traffic analysis
vpc security-groups Security group validation
vpc validate VPC architecture assessment
vpc dependencies Cross-VPC dependency analysis
list-elbs Load balancer discovery (ELB/ALB/NLB)
list-enis Network interface discovery (ENI) with optional instance filter
ssm-status SSM agent health and patch compliance per instance
ebs-health EBS volume layout and IOPS utilization per instance
find-cfn-drift CloudFormation drift detection
find-cfn-orphaned-stacks Orphaned stack discovery
list-cfn-stacks List CloudFormation stacks
list-cfn-stacksets List CloudFormation StackSets
find-cfn-stackset-drift StackSet drift detection
recover-cfn-stack-ids Recover CloudFormation stack IDs
check-cloudtrail-compliance CloudTrail compliance validation
list-guardduty-detectors GuardDuty detector discovery
tag-coverage Tag coverage analysis
drift-detection Comprehensive drift detection
list-sns-topics SNS topic discovery
collect-messaging Messaging resources (SQS queues, SNS topics)
collect-analytics Analytics resources (Athena, Glue databases/tables)
workflow-single-account 4-layer pipeline (single account)
workflow-multi-account 5-layer pipeline (multi-account LZ)
pipeline-summary Display pipeline execution summary
validate-mcp MCP cross-validation
validate-costs Cost data accuracy validation
cross-validate 4-way cross-validation (MCP/CLI/Console/AWS)
clean-outputs Clean output directory
💡 Usage: runbooks inventory [COMMAND] [OPTIONS]
📖 Example: runbooks inventory resource-explorer --resource-type ec2 --profile ops --output /tmp/ec2.csv
📋 Taskfile Operations Available:
Runbooks - Inventory Module Operations
├── Discovery Operations (6 operations)
│ └── ╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────╮
│ │ Task Name │ Description │
│ ├─────────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ │ 🔄 discover-ec2 │ Discover EC2 instances across organization (Universal) │
│ │ 🔄 discover-rds │ Discover RDS databases across organization (Universal) │
│ │ 🔄 discover-s3 │ Discover S3 buckets across organization (Universal) │
│ │ 🔄 discover-lambda │ Discover Lambda functions across organization (Universal) │
│ │ 🔄 workspaces │ WorkSpaces investigation (6-phase analysis) │
│ │ 🔄 list-resource-types │ List all available resource types for discovery (Universal) │
│ ╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────╯
├── Organizations Operations (6 operations)
│ └── ╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────╮
│ │ Task Name │ Description │
│ ├─────────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ │ 🏢 list-accounts │ List all AWS accounts in organization (Multi-Account LZ) │
│ │ 🏢 draw-org │ Visualize AWS Organizations hierarchy (Multi-Account LZ) │
│ │ 🏢 check-landing-zone │ Validate AWS Landing Zone configuration (Multi-Account LZ) │
│ │ 🏢 check-control-tower │ Validate AWS Control Tower setup (Multi-Account LZ) │
│ │ 🏢 list-org-users │ List all IAM users across AWS organization accounts │
│ │ │ (Multi-Account LZ) │
│ │ 🏢 find-lz-versions │ Discover AWS Landing Zone versions across organization │
│ │ │ (Multi-Account LZ) │
│ ╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────╯
├── Cost & Account Enrichment (2 operations)
│ └── ╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────╮
│ │ Task Name │ Description │
│ ├─────────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ │ ⚙️ enrich-accounts │ Enrich resources with AWS Organizations account metadata │
│ │ │ (renamed from enrich-organizations) (Context-Dependent) │
│ │ 🔄 enrich-costs │ Add cost data to discovered resources (Universal) │
│ ╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────╯
├── Activity & Scoring Operations (3 operations)
│ └── ╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────╮
│ │ Task Name │ Description │
│ ├─────────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ │ 🔄 enrich-activity │ Add activity metrics to resources (Universal) │
│ │ 🔄 enrich-ec2 │ EC2-specific enrichment with detailed instance metadata │
│ │ │ (Universal) │
│ │ 🔄 score-decommission │ Calculate decommission scores for resources (Universal) │
│ ╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────╯
├── Pipeline Operations (3 operations)
│ └── ╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────╮
│ │ Task Name │ Description │
│ ├─────────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ │ 🔄 pipeline-5-layer │ Execute complete 5-layer enrichment pipeline (EC2) │
│ │ │ (Universal) │
│ │ 🔄 pipeline-5-layer-workspaces │ Execute complete 5-layer enrichment pipeline (WorkSpaces) │
│ │ │ (Universal) │
│ │ 🔄 pipeline-summary │ Display pipeline execution summary (Universal) │
│ ╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────╯
├── Validation Operations (2 operations)
│ └── ╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────╮
│ │ Task Name │ Description │
│ ├─────────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ │ 🔄 validate-mcp │ MCP cross-validation (Universal) │
│ │ 🔄 validate-costs │ Validate cost data accuracy against AWS Cost Explorer │
│ │ │ (Universal) │
│ ╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────╯
├── Workflow Templates (2 operations)
│ └── ╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────╮
│ │ Task Name │ Description │
│ ├─────────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ │ 📋 workflow-single-account │ Best practice workflow for single AWS account (4-layer │
│ │ │ pipeline) (Workflow) │
│ │ 📋 workflow-multi-account │ Best practice workflow for multi-account Landing Zone │
│ │ │ (5-layer pipeline) (Workflow) │
│ ╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────╯
├── Utility Operations (1 operations)
│ └── ╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────╮
│ │ Task Name │ Description │
│ ├─────────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ │ 🛠️ clean-outputs │ Clean output directory (Utility) │
│ ╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────╯
└── ╭──────────────────────────────────────────────── Summary & Legend ────────────────────────────────────────────────╮
│ Total Operations: 33 │
│ Categorized: 25 │
│ Uncategorized: 8 │
│ │
│ Context Legend: │
│ 🏢 Multi-Account LZ (6) 🔄 Universal (23) │
│ ⚙️ Context-Dependent (1) 📋 Workflow (2) 🛠️ Utility (1) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
security¶
Security Commands (7 commands)
Commands (7):
assess Multi-framework compliance assessment (SOC2, PCI-DSS, HIPAA, ISO27001) with optional resource-id filter
baseline Security baseline validation with remediation recommendations
report Generate compliance reports (PDF, HTML, Markdown, JSON)
remediate-findings Remediate Security Hub findings across multi-account organization (FIN-63/62/61)
deploy-guardduty Deploy GuardDuty organization-wide with delegated admin configuration (FIN-64)
cert-inventory Multi-cloud certificate inventory (ACM, IAM, Key Vault) with expiry dashboard
host-findings SecurityHub + GuardDuty + Inspector findings for a specific resource
vpc¶
VPC Commands (8 commands)
Commands (8):
analyze Comprehensive VPC analysis with cost optimization (now with instance-ip filter)
analyze-endpoint-activity Analyze VPC endpoint activity via CloudTrail (90-day lookback).
topology Network topology discovery and visualization
network-discover Multi-account network discovery with diagrams
discover-firewall-bypass Security group firewall bypass detection
nat-gateway NAT Gateway cost optimization
vpce-cleanup VPC Endpoint cleanup and cost reduction
flow-log-query CloudWatch Logs Insights query for VPC flow logs (per IP, 7-day default)
operate¶
Operate Commands (4 sub-groups, 5 commands)
Commands (5):
ec2 start Start EC2 instances (reduce idle time, optimize availability)
ec2 stop Stop EC2 instances (cost savings, schedule optimization)
s3 create-bucket Create S3 buckets (secure, compliant, encrypted)
vpc create-vpc Create VPCs (network isolation, multi-tier architecture)
cloudformation deploy Deploy CloudFormation stacks (IaC automation, repeatable deployments)
cert¶
Certificate Commands (5 commands)
Commands (5):
inventory Discover certificates across AWS accounts and Azure subscriptions
expiring Show certificates expiring within N days (default: 30)
dns-check Check ACM DNS validation CNAME records via dig
report Generate executive certificate assessment report (Markdown)
triage Combined triage: inventory + expiring + executive report
cfat¶
Cloud Foundations Assessment Tool — CFAT Commands (3 commands)
Commands (3):
assess Comprehensive framework assessment
review Structured architecture review
report Generate assessment reports
remediation¶
Remediation Commands (4 commands)
Commands (4):
s3-security S3 security remediation (block public access, enforce SSL, enable encryption)
list-accounts List available accounts for remediation operations
config-info Display current remediation configuration and environment setup
generate-config Generate universal configuration templates for remediation operations
validation¶
Validation Commands (8 commands)
Commands (8):
validate-all Run all validation operations
costs Validate Cost Explorer data accuracy
organizations Validate Organizations API accuracy
single Validate single operation (costs, organizations, ec2, security, vpc)
benchmark Performance benchmarking (iterations, accuracy targets)
test Comprehensive test framework (Sprint 1 validation)
status Framework status and health check
sync-check Detect notebooks that break after CLI command changes.
Command Details — Core Operations¶
inventory ssm-status¶
Purpose: SSM agent health, patch compliance, and recent command invocations per EC2 instance.
Usage:
Options:
- --instance-id (required): EC2 instance ID (e.g., i-0123456789abcdef0)
- --profile (optional): AWS profile for authentication (default: default)
Output: 3-section Rich table display: 1. Agent Info: Agent version, ping status, last ping time, activation code 2. Patch Compliance: Patch manager status, compliant/non-compliant counts, last scan 3. Recent Commands: Last 5 command invocations (document ID, status, execution time, command output)
Example Output:
SSM Agent Status: i-0123456789abcdef0
├─ Agent Version: 3.2.1234.0
├─ Ping Status: Online
├─ Last Ping: 2026-04-10T14:23:45Z
└─ Activation Code: (redacted)
Patch Compliance
├─ Manager: ENABLED
├─ Compliant: 156 patches
├─ Non-Compliant: 3 patches (updates pending)
└─ Last Scan: 2026-04-10T02:00:00Z
Recent Commands (last 5)
├─ ssm-command-12345abc: SUCCESS (2026-04-10T14:15:22Z)
├─ ssm-command-12345abd: SUCCESS (2026-04-09T22:30:11Z)
└─ ...
inventory ebs-health¶
Purpose: EBS volume layout, IOPS utilization (30-day average), and encryption audit per EC2 instance.
Usage:
Options:
- --instance-id (required): EC2 instance ID
- --profile (optional): AWS profile for authentication
Output: Rich table with summary panel:
| Volume ID | Device | Size (GB) | Type | IOPS | Throughput (MiB/s) | Encrypted | KMS Key |
|---|---|---|---|---|---|---|---|
| vol-abc123 | /dev/xvda | 100 | gp3 | 4000 | 250 | Yes | arn:aws:kms:... |
| vol-def456 | /dev/xvdb | 500 | io2 | 6400 | 1000 | Yes | arn:aws:kms:... |
Summary Panel: - Total capacity: 600 GB - 30-day IOPS avg: ~3200 IOPS - Encryption: 2/2 volumes encrypted (100%) - Optimization tip: (e.g., gp3 IOPS below 3000 — consider reducing)
vpc flow-log-query¶
Purpose: CloudWatch Logs Insights query for VPC Flow Logs filtered to a specific private IP address. Returns source/destination traffic, protocol analysis, and flow classification.
Usage:
Options:
- --instance-ip (required): Private IP address (e.g., 10.1.2.3)
- --vpc-id (required): VPC ID (e.g., vpc-abc123def)
- --days (optional, default 7): Query period in days
- --profile (optional): AWS profile
Output: Rich table with traffic classification:
| Source IP | Dest IP | Sport | Dport | Protocol | Bytes | Packets | Flow Count | Classification |
|---|---|---|---|---|---|---|---|---|
| 10.1.2.3 | 10.2.3.4 | 49521 | 443 | TCP | 524288 | 1024 | 142 | HTTPS (Egress) |
| 10.1.2.3 | 8.8.8.8 | 53401 | 53 | UDP | 4096 | 8 | 8 | DNS Query |
Traffic Classification Legend: - HTTP/HTTPS (80, 443) - DNS (53, 5353) - SSH (22) - RDP (3389) - Internal (RFC 1918 targets) - External (public IPs) - Unknown (unclassified ports)
security host-findings¶
Purpose: Aggregated security findings from SecurityHub, GuardDuty, and Inspector for a specific resource (EC2 instance or resource ARN). Organized by severity and finding source.
Usage:
Options:
- --resource-id (required): Instance ID (i-xxx) or full resource ARN
- --profile (optional): AWS profile
Output: Findings organized by severity, then by source (SecurityHub | GuardDuty | Inspector):
CRITICAL Findings (2) - SecurityHub: "EC2.19 - Security group allows unrestricted ingress to port 22" (Risk: SSH brute-force) - GuardDuty: "Trojan.EC2/DNSDataExfiltration.C" (Risk: DNS exfiltration detected)
HIGH Findings (5) - Inspector: "CVE-2024-1234 - OpenSSL 1.0.2 EOL" (CVSS 8.2) - SecurityHub: "CloudTrail API logging is disabled" (Compliance: PCI-DSS 10.1)
MEDIUM Findings (8) - (list continues...)
Summary Panel:
Total Findings: 15
├─ CRITICAL: 2
├─ HIGH: 5
├─ MEDIUM: 8
└─ LOW: 0
Recommended Actions:
1. Close SSH security group rule (54 days open)
2. Apply OS patches (CVE-2024-1234)
3. Enable CloudTrail logging
Enhanced Commands — SSM & EBS Enrichment¶
inventory enrich-ec2 (updated)¶
New columns added:
- ssm_agent_status: Online/Offline (from Systems Manager)
- ssm_ping_status: Last ping timestamp
- last_patch_scan: Date of last patch manager scan
- patch_non_compliant_count: Number of pending patches
Usage:
inventory list-enis (updated)¶
New filter option:
- --instance-id: Filter ENIs by EC2 instance ID
Usage:
security assess (updated)¶
New filter option:
- --resource-id: Filter findings to a specific resource (instance ID or ARN)
Usage:
vpc analyze (updated)¶
New filter option:
- --instance-ip: Filter traffic analysis to a specific private IP address
Usage:
inventory score-decommission (updated)¶
New signal (E8): - SSM Heartbeat: 5 points if no SSM ping in 30 days - Decommission candidates now scored as E1-E8 (previously E1-E7)
Signal Summary: - E1: No CloudTrail activity (30 days) — 10 pts - E2: No VPC Flow Logs activity (30 days) — 10 pts - E3: Zero CPU utilization (30 days) — 8 pts - E4: Zero network I/O (30 days) — 8 pts - E5: Instance stopped (>60 days) — 5 pts - E6: Orphaned ENI (no attachment) — 3 pts - E7: No tags/cost allocation — 2 pts - E8: No SSM heartbeat (30 days) — 5 pts [NEW]
Decommission Score Tiers: - ≥40 pts: Ready for decommission (executive review) - 30-39 pts: Review recommended (operations team) - <30 pts: Monitor (no action)
Investigation Orchestrators¶
inventory ec2-investigate¶
Purpose: 6-phase EC2 host investigation orchestrator. Chains multiple operations (EC2 enrichment, EBS health, security findings, network flow logs, SSM status, risk scoring) into a single unified report with prioritized recommendations.
Usage:
runbooks inventory ec2-investigate --instance-id i-0123456789abcdef0 --profile ops
runbooks inventory ec2-investigate --instance-id i-0123456789abcdef0 --profile ops --output json
Options:
- --instance-id (required): EC2 instance ID (e.g., i-0123456789abcdef0)
- --profile (optional): AWS profile for authentication (default: default)
- --output (optional): json for structured JSON output (default: Rich panel display)
Phases: 1. Discovery: Fetch EC2 instance metadata (type, state, security groups, VPC, subnets) 2. EBS Health: Volume layout, IOPS utilization, encryption audit 3. Security Findings: Aggregated findings from SecurityHub, GuardDuty, Inspector 4. Network Analysis: VPC Flow Logs traffic classification (if private IP present) 5. SSM Status: Agent health, patch compliance, recent command history 6. Risk Scoring: Combined risk score (0-100) with prioritized remediation steps
Output: Rich multi-section panel:
EC2 Investigation Report: i-0123456789abcdef0
├─ Instance: t3.large | Running | VPC: vpc-abc123 | AZ: ap-southeast-2a
├─
├─ EBS Storage (3 volumes)
│ ├─ /dev/xvda: vol-abc123 (100 GB, gp3, 4000 IOPS) ✓ Encrypted
│ ├─ /dev/xvdb: vol-def456 (500 GB, io2, 6400 IOPS) ✓ Encrypted
│ └─ Total Capacity: 600 GB | 30-day IOPS avg: 3200 | Encryption: 100%
├─
├─ Security Findings: 7 total
│ ├─ CRITICAL (2): Security group unrestricted SSH, DNS exfiltration detected
│ └─ HIGH (5): EOL patches (CVE-2024-1234), CloudTrail disabled
├─
├─ Network Activity (last 7 days)
│ ├─ Outbound HTTPS: 524 MB (142 flows)
│ ├─ Inbound SSH: 2 MB (8 flows)
│ └─ DNS: 4 MB (8 queries)
├─
├─ SSM Agent: Online (v3.2.1234) | Patches: 3 non-compliant | Scanned: 2026-04-10
├─
└─ RISK SCORE: 72/100 [HIGH]
1. Close SSH security group rule (54 days open)
2. Apply pending OS patches (CVE-2024-1234)
3. Enable CloudTrail logging
inventory rds-investigate¶
Purpose: 6-phase RDS database investigation orchestrator. Chains RDS discovery, metadata enrichment, security assessment, network analysis, compliance checks, and risk scoring into a unified report.
Usage:
runbooks inventory rds-investigate --db-instance-id prod-postgres-01 --profile ops
runbooks inventory rds-investigate --db-instance-id prod-postgres-01 --profile ops --output json
Options:
- --db-instance-id (required): RDS DB instance identifier (e.g., prod-postgres-01)
- --profile (optional): AWS profile for authentication
- --output (optional): json for structured JSON output
Phases: 1. Discovery: DB engine, version, instance class, Multi-AZ status, backup retention 2. Metadata: Storage allocation, parameter groups, option groups, performance insights 3. Security: Encryption (KMS key), IAM auth, security groups, network exposure 4. Network: VPC/subnet configuration, publicly accessible flag, security group rules 5. Compliance: Automated backups, backup window, copy-on-write, deletion protection 6. Risk Scoring: Combined risk score (0-100) with recommendations
Output: Rich multi-section panel:
RDS Investigation Report: prod-postgres-01
├─ Database: PostgreSQL 14.7 | db.r6g.xlarge | Multi-AZ: Yes | Backup: 7 days
├─
├─ Storage & Performance
│ ├─ Allocated: 1000 GB (gp3)
│ ├─ IOPS: 3000 provisioned
│ ├─ Performance Insights: Enabled
│ └─ Enhanced Monitoring: Enabled (1-minute granularity)
├─
├─ Security Posture
│ ├─ Encryption at Rest: ✓ Yes (KMS key: arn:aws:kms:...)
│ ├─ Encryption in Transit: ✓ Yes (SSL/TLS enforced)
│ ├─ IAM Authentication: ✓ Enabled
│ ├─ Public Access: ✗ NO (secure)
│ └─ Security Groups: 2 rules (port 5432, restricted CIDR)
├─
├─ Compliance & Backup
│ ├─ Automated Backups: Enabled (7-day retention)
│ ├─ Backup Window: 23:00-23:30 UTC
│ ├─ Copy-on-Write: Enabled (cross-region replication)
│ └─ Deletion Protection: Enabled
├─
└─ RISK SCORE: 15/100 [LOW]
Configuration follows AWS best practices. Monitor: parameter group changes, backup timing.
inventory s3-investigate¶
Purpose: 6-phase S3 bucket investigation orchestrator. Audits bucket configuration, public access, encryption, versioning, logging, compliance, and risk scoring.
Usage:
runbooks inventory s3-investigate --bucket-name prod-app-data --profile ops
runbooks inventory s3-investigate --bucket-name prod-app-data --profile ops --output json
Options:
- --bucket-name (required): S3 bucket name (e.g., prod-app-data)
- --profile (optional): AWS profile for authentication
- --output (optional): json for structured JSON output
Phases: 1. Discovery: Bucket location, creation date, versioning status, object count 2. Metadata: ACLs, bucket policies, access control lists, object tagging 3. Security: Block public access settings, encryption (SSE-S3/SSE-KMS/DSSE), CORS policies 4. Network: VPC endpoints, transfer acceleration, CloudFront distribution associations 5. Compliance: Logging (CloudTrail, server-access logs), lifecycle policies, MFA delete 6. Risk Scoring: Combined risk score (0-100) with recommendations
Output: Rich multi-section panel:
S3 Investigation Report: prod-app-data
├─ Bucket: prod-app-data | Region: ap-southeast-2 | Created: 2023-01-15
├─
├─ Storage & Objects
│ ├─ Total Objects: 2,487,365
│ ├─ Total Size: 4.2 TB
│ ├─ Versioning: Enabled (1.1 TB in previous versions)
│ └─ Object Lock: Not configured
├─
├─ Public Access Assessment
│ ├─ Block Public ACLs: ✓ YES
│ ├─ Ignore Public ACLs: ✓ YES
│ ├─ Block Public Policy: ✓ YES
│ ├─ Restrict Public Buckets: ✓ YES
│ └─ Public Objects Detected: 0
├─
├─ Encryption & Protection
│ ├─ Default Encryption: ✓ Yes (SSE-KMS, key: arn:aws:kms:...)
│ ├─ Bucket Key: ✓ Enabled (cost optimization)
│ ├─ Lifecycle Expiration: ✓ Configured (90-day cleanup)
│ └─ Server-Access Logging: ✓ Enabled (target: access-logs bucket)
├─
├─ Compliance & Monitoring
│ ├─ CloudTrail Data Events: ✓ Enabled
│ ├─ CloudWatch Alarms: ✓ 3 configured (size, deletion, policy change)
│ ├─ Replication: Not configured
│ └─ Transfer Acceleration: Disabled
├─
└─ RISK SCORE: 8/100 [LOW]
Bucket is well-secured with all recommended protections enabled.
Recommendation: Enable cross-region replication for DR (optional).
inventory workspaces-investigate¶
Purpose: 6-phase Amazon WorkSpaces investigation orchestrator. Audits WorkSpace configuration, cost optimization, user activity, compliance, security, and risk scoring.
Usage:
runbooks inventory workspaces-investigate --workspace-id ws-0123456789abcdef0 --profile ops
runbooks inventory workspaces-investigate --workspace-id ws-0123456789abcdef0 --profile ops --output json
Options:
- --workspace-id (required): WorkSpaces workspace ID (e.g., ws-0123456789abcdef0)
- --profile (optional): AWS profile for authentication
- --output (optional): json for structured JSON output
Phases: 1. Discovery: User, bundle type, directory, state, creation date, last connection 2. Metadata: IP address, root volume size, user volume size, running mode 3. Security: User account status, MFA enabled, Active Directory integration 4. Network: VPC, subnet, security group rules, ENI configuration 5. Compliance: Encryption (root & user volumes), backup settings, tagging 6. Risk Scoring: Cost optimization (AlwaysOn vs AutoStop), activity signals, risk score
Output: Rich multi-section panel:
WorkSpaces Investigation Report: ws-0123456789abcdef0
├─ WorkSpace: alice.smith | Bundle: PERFORMANCE (8 vCPU, 32 GB RAM)
├─ Directory: corp-directory | State: AVAILABLE | Last Connection: 2026-04-10 14:22Z
├─
├─ Storage & Performance
│ ├─ Root Volume: 175 GB (SSD, encrypted ✓)
│ ├─ User Volume: 100 GB (SSD, encrypted ✓)
│ ├─ Running Mode: AlwaysOn
│ └─ Bundle Type: PERFORMANCE ($25/month)
├─
├─ User & Access
│ ├─ Status: ACTIVE
│ ├─ Active Directory: corp-directory (synced)
│ ├─ MFA Enabled: ✓ Yes
│ └─ Last 7-Day Access: 5 days active (2 days idle)
├─
├─ Security & Compliance
│ ├─ Encryption at Rest: ✓ Enabled (KMS, default key)
│ ├─ Tagging: ✓ 4 tags (cost-center, owner, project, env)
│ ├─ Security Groups: 1 rule (RDP/PCoIP ingress, restricted)
│ └─ Network Interface: eni-abc123 (VPC vpc-def456, subnet subnet-ghi789)
├─
├─ Activity & Usage
│ ├─ Connection History (last 30 days): 18 sessions
│ ├─ Avg Session Duration: 4.5 hours
│ ├─ Estimated Monthly Cost: $25 (AlwaysOn) + storage
│ └─ Optimization Candidate: Consider AutoStop mode ($10/month + $0.33/hour)
├─
└─ RISK SCORE: 28/100 [LOW-MODERATE]
1. OPPORTUNITY: Migrate to AutoStop mode — save $180/year ($25 × 12 - 8 hrs/day usage)
2. Review: User only connects 18 days/month — confirm business requirement
3. Monitor: Session duration trending for licensing optimization
inventory vpc-investigate¶
Purpose: 6-phase VPC investigation orchestrator. Audits VPC topology, resource inventory, security posture, network design, compliance, and risk scoring. Identifies unused resources, security gaps, and cost optimization opportunities.
Usage:
runbooks inventory vpc-investigate --vpc-id vpc-0123456789abcdef0 --profile ops
runbooks inventory vpc-investigate --vpc-id vpc-0123456789abcdef0 --profile ops --output json
Options:
- --vpc-id (required): VPC ID (e.g., vpc-0123456789abcdef0)
- --profile (optional): AWS profile for authentication
- --output (optional): json for structured JSON output
Phases: 1. Discovery: VPC CIDR, region, DNS hostnames, DNS resolution, creation date 2. Topology: Subnets (count, CIDR, AZ distribution), route tables, internet gateways, NAT gateways 3. Security: Network ACLs, security groups (count, unused rules), VPC endpoints 4. Network: Transit Gateway attachments, VPC peering, multi-account connectivity, DNS query logging 5. Compliance: VPC Flow Logs (enabled/disabled, retention), CloudTrail logging, encryption 6. Risk Scoring: Resource efficiency, orphaned resources, security gaps, cost optimization score
Output: Rich multi-section panel:
VPC Investigation Report: vpc-0123456789abcdef0
├─ VPC: vpc-0123456789abcdef0 | Region: ap-southeast-2 | CIDR: 10.0.0.0/16
├─ DNS: ✓ Hostnames enabled | ✓ Resolution enabled
├─
├─ Topology & Connectivity
│ ├─ Subnets: 6 (2 public, 4 private across 3 AZs)
│ │ ├─ Public: 10.0.1.0/24 (us-east-2a, 254 IPs available)
│ │ ├─ Public: 10.0.2.0/24 (us-east-2b, 241 IPs available)
│ │ ├─ Private: 10.0.11.0/24 (us-east-2a, 128 IPs available)
│ │ ├─ Private: 10.0.12.0/24 (us-east-2b, 108 IPs available)
│ │ ├─ Private: 10.0.13.0/24 (us-east-2c, 256 IPs available)
│ │ └─ Private: 10.0.14.0/24 (us-east-2c, 197 IPs available)
│ ├─
│ ├─ Gateways & NAT
│ │ ├─ Internet Gateways: 1 (igw-abc123, attached)
│ │ ├─ NAT Gateways: 3 (1 per AZ, EIP allocated, ~$130/month)
│ │ └─ Virtual Private Gateway: vpgw-def456 (VPN to on-prem)
│ ├─
│ ├─ Advanced Connectivity
│ │ ├─ Transit Gateway: Attached (tgw-ghi789)
│ │ ├─ VPC Peering: 2 connections (dev-vpc, staging-vpc)
│ │ └─ VPC Endpoints: 3 (S3, DynamoDB, Secrets Manager)
├─
├─ Security Posture
│ ├─ Network ACLs: 6 (all subnets configured)
│ ├─ Security Groups: 12 total
│ │ ├─ ALB-sg: 1 rule (HTTP/HTTPS ingress, 0.0.0.0/0)
│ │ ├─ App-sg: 3 rules (1 unused — port 3000 no source flows)
│ │ ├─ DB-sg: 2 rules (PostgreSQL 5432, restricted to app-sg)
│ │ └─ Others: 8 groups (review needed)
│ └─ VPC Flow Logs: ✓ Enabled (CloudWatch Logs, 7-day retention)
├─
├─ Compliance & Monitoring
│ ├─ Flow Logs: ✓ Enabled | Retention: 7 days | Destination: /aws/vpc/flowlogs/vpc-0123
│ ├─ CloudTrail: ✓ Data events enabled for VPC API calls
│ ├─ VPC Endpoints: ✓ Configured (S3, DynamoDB, Secrets Manager)
│ └─ Route Table Logging: ⚠ No custom logging configured
├─
├─ Resource Inventory
│ ├─ EC2 Instances: 8 running (across 3 subnets)
│ ├─ RDS Instances: 2 (multi-AZ, in private subnets)
│ ├─ ELBs/ALBs: 3 (public-facing, traffic distributed)
│ ├─ Network Interfaces: 22 (18 attached, 4 unattached ⚠️)
│ └─ Elastic IPs: 4 (3 in-use, 1 unassociated ⚠️)
├─
└─ RISK SCORE: 34/100 [MODERATE]
1. CRITICAL: 4 unattached ENIs (cleanup → save $0/month but reduce clutter)
2. HIGH: 1 unused security group rule (app-sg:3000) — remove
3. MEDIUM: 1 unassociated EIP (delete → save $3.50/month)
4. OPTIMIZATION: NAT Gateway cost ($130/month) — consider NAT instance for non-prod
5. MONITORING: Enable VPC endpoint usage logging for cost allocation