Resource Investigation Runbook¶
Single command per resource type. Six-phase orchestration. Risk-scored output. CxO-ready reports.
Claude Code Prompts¶
One-line prompts for AI-assisted investigation via infrastructure-engineer agent:
| Resource | Prompt | What It Does |
|---|---|---|
| EC2 Instance | /adlc Investigate EC2: i-04adf4d7eb2320218 |
6-phase investigation with SSM, security findings, flow logs |
| RDS Database | /adlc Investigate RDS: prod-postgres-01 |
Encryption, backups, compliance, network access audit |
| S3 Bucket | /adlc Investigate S3: my-bucket-name |
Public access, encryption, lifecycle, cost analysis |
| WorkSpaces | /adlc Investigate WorkSpaces: ws-abc123 |
Cost optimization, activity, security, decommission signals |
| VPC Network | /adlc Investigate VPC: vpc-8e9c0aeb |
Topology, flow logs, security groups, routing |
| Any IP | /adlc Investigate host: 192.168.13.140 |
Resolve IP → instance → full 6-phase investigation |
| Any hostname | /adlc Investigate host: ip-192-168-13-140.ap-southeast-2.compute.internal |
DNS → IP → instance → full investigation |
Quick Start¶
Start with the orchestrator command for your resource. All return structured Rich panels with risk scoring, findings aggregation, and prioritized remediation steps.
| Resource | Command | Required Input | Common Trigger |
|---|---|---|---|
| EC2 Instance | runbooks inventory ec2-investigate |
--instance-id i-xxx |
Nessus alert, incident triage, decommission review |
| RDS Database | runbooks inventory rds-investigate |
--db-instance-id mydb |
Security patch cycle, backup audit, compliance review |
| S3 Bucket | runbooks inventory s3-investigate |
--bucket-name mybucket |
Public access audit, encryption review, cost analysis |
| WorkSpaces | runbooks inventory workspaces-investigate |
--workspace-id ws-xxx |
Activity audit, cost review, decommission candidate |
| VPC Network | runbooks inventory vpc-investigate |
--vpc-id vpc-xxx |
Connectivity troubleshooting, security audit, design review |
All commands accept:
- --profile <PROFILE> — AWS profile for authentication
- --output json — Machine-readable JSON output (for CI/CD pipelines)
- Default output: Rich multi-panel UI with color-coded findings
EC2 Instance Investigation¶
When to use: Nessus alerts, GuardDuty findings, incident response, decommission evaluation, patch compliance
Command:
Six Phases: 1. Discovery — Instance type, state, VPC, security groups, AMI metadata 2. EBS Health — Volume layout, IOPS utilization, encryption audit 3. Security Findings — Aggregated findings from SecurityHub, GuardDuty, Inspector (CRITICAL/HIGH priority) 4. Network Activity — VPC Flow Logs traffic classification (inbound/outbound/DNS, 7-day lookback) 5. SSM Status — Agent health, patch compliance, recent command execution history 6. Risk Score — Combined 0–100 score with prioritized remediation steps (e.g., "Close unrestricted SSH rule")
Output: Rich multi-section panel with instance ID header, color-coded risk levels (CRITICAL red, HIGH orange), and actionable recommendations.
Deep-dive commands (individual phases):
runbooks inventory ssm-status --instance-id i-xxx # Patch compliance only
runbooks inventory ebs-health --instance-id i-xxx # Storage/IOPS breakdown
runbooks security assess --profile ops # SecurityHub + GuardDuty findings
runbooks inventory vpc flow-logs --vpc-id vpc-xxx # VPC Flow Logs analysis
runbooks inventory list-enis --instance-id i-xxx # ENI/NIC details
JSON export (for dashboards/CI):
runbooks inventory ec2-investigate --instance-id i-xxx --profile ops --output json > /tmp/ec2-investigation.json
RDS Database Investigation¶
When to use: Database patch cycle, backup audit, compliance review, security assessment, performance troubleshooting
Command:
Six Phases: 1. Discovery — DB engine, version, instance class, Multi-AZ, backup retention 2. Metadata — Storage allocation, parameter groups, option groups, performance insights enabled 3. Security — Encryption (KMS key), IAM authentication, security groups, public access flag 4. Network — VPC/subnet configuration, security group rules, DNS resolution, publicly accessible status 5. Compliance — Automated backups, backup window, copy-on-write flag, deletion protection, CloudTrail logging 6. Risk Score — Combined risk assessment with recommendations (e.g., "Enable automated backups", "Enforce SSL/TLS")
Output: Rich multi-section panel showing encryption status (green checkmarks), compliance gaps (red X), and recommendations.
Deep-dive commands:
runbooks inventory discover-rds --region ap-southeast-2 # RDS discovery across region
runbooks security assess --profile ops # Multi-framework compliance assessment
runbooks inventory vpc flow-logs --vpc-id vpc-xxx # VPC Flow Logs for RDS subnet
JSON export:
runbooks inventory rds-investigate --db-instance-id prod-postgres-01 --output json > /tmp/rds-investigation.json
S3 Bucket Investigation¶
When to use: Public access audit, encryption compliance, cost analysis, data retention policy review, security hardening
Command:
Six Phases: 1. Discovery — Bucket location, creation date, versioning status, object count, total size 2. Metadata — Bucket ACLs, bucket policies, object tagging, object lock configuration 3. Security — Block public access settings (4 flags), encryption (SSE-S3/SSE-KMS/DSSE), CORS policies 4. Network — VPC endpoints, transfer acceleration, CloudFront distributions, S3 website hosting 5. Compliance — CloudTrail logging, server access logs, lifecycle policies, MFA delete, replication 6. Risk Score — Public access risk, encryption coverage, cost optimization (lifecycle enforcement), compliance gaps
Output: Rich multi-section panel with storage breakdown (versioned vs. current), public access flags (green ✓ or red ✗), and recommendations.
Deep-dive commands:
runbooks inventory collect --resource-type s3 --profile ops # S3 discovery across org
runbooks finops analyze-s3-storage-lens --profile ops # Storage Lens cost intelligence
runbooks security assess --profile ops # Multi-framework compliance assessment
JSON export:
runbooks inventory s3-investigate --bucket-name prod-app-data --output json > /tmp/s3-investigation.json
Amazon WorkSpaces Investigation¶
When to use: User activity audit, cost optimization review (AlwaysOn vs. AutoStop), decommission evaluation, access review, compliance audit
Command:
Six Phases: 1. Discovery — User name, bundle type, directory, state (AVAILABLE/STOPPED/TERMINATED), creation date, last connection timestamp 2. Metadata — IP address, root volume size, user volume size, running mode (AlwaysOn/AutoStop), compute type 3. Security — User account status (ACTIVE/SUSPENDED), MFA enabled, Active Directory integration, password policy compliance 4. Network — VPC, subnet, security group rules, ENI configuration, DNS resolution 5. Compliance — Encryption (root & user volumes), backup settings, tagging compliance, audit logging 6. Risk Score — Cost optimization signal (unused AlwaysOn bundles), user activity (7-day lookback), security gaps, decommission likelihood
Output: Rich multi-section panel with user name, bundle type, monthly cost, 7-day activity heatmap, and recommendations (e.g., "Switch to AutoStop to save $X/month").
Deep-dive commands:
runbooks inventory discover-workspaces --region ap-southeast-2 # WorkSpaces discovery
runbooks finops analyze-workspaces --profile ops # WorkSpaces cost analysis
runbooks inventory enrich-activity # CloudTrail activity enrichment
JSON export:
runbooks inventory workspaces-investigate --workspace-id ws-xxx --output json > /tmp/workspaces-investigation.json
VPC Network Investigation¶
When to use: Connectivity troubleshooting, security audit, network design review, cost optimization (unused resources), disaster recovery validation
Command:
Six Phases: 1. Discovery — VPC CIDR, region, DNS hostnames, DNS resolution status, creation date, flow logs enabled 2. Topology — Subnets (count, CIDR, AZ distribution), route tables, internet gateways, NAT gateways, transit gateway attachments 3. Security — Network ACLs, security groups (count, unused rules), VPC endpoints, security group analysis 4. Network — VPC peering (active/inactive), multi-account connectivity, inter-VPC routing, hosted zones 5. Compliance — VPC Flow Logs (enabled/disabled, retention), CloudTrail logging, encryption in transit (TLS/IPsec) 6. Risk Score — Resource efficiency (orphaned ENIs/route tables), security gaps (overly permissive rules), cost optimization (unused NAT gateways), design gaps
Output: Rich multi-section panel with topology tree (subnets → route tables → gateways), security group rule count, VPC Flow Logs status, and recommendations.
Deep-dive commands:
runbooks vpc analyze --profile ops # VPC cost & topology analysis
runbooks vpc topology --profile ops # Network topology visualization
runbooks inventory vpc flow-logs --vpc-id vpc-xxx --profile ops # Flow logs discovery
runbooks vpc discover-firewall-bypass --profile ops # Security group bypass detection
JSON export:
Cross-Validation Framework¶
For any investigation, validate findings across three layers:
| Layer | Tool | Purpose | Command |
|---|---|---|---|
| L1 | runbooks inventory <type>-investigate --output json |
Rich CLI structured output | Direct invocation |
| L2 | awslabs AWS API MCP (real-time) | Native AWS API query | Via Claude Code MCP |
| L3 | aws <service> describe-<resource> |
Native CLI ground truth | AWS CLI native |
Example: EC2 investigation cross-validation:
# L1: Rich CLI investigation
runbooks inventory ec2-investigate --instance-id i-xxx --output json > /tmp/l1-investigation.json
# L2: MCP validation (Claude Code session)
# Use awslabs-network MCP: find_ip_address, get_eni_details
# Use awslabs-aws-api MCP: ec2 describe-instances, ssm describe-instance-information
# L3: Native AWS CLI
aws ec2 describe-instances --instance-ids i-xxx --region ap-southeast-2 > /tmp/l3-native.json
Target agreement: ≥99.5% data match (checksums, counts, status fields).
Profile Reference¶
Select the appropriate AWS profile for your investigation scope:
| Scope | Profile | Use For |
|---|---|---|
| Org-wide discovery | $AWS_MANAGEMENT_PROFILE |
Landing zone inventory, Organizations queries |
| Cost data | $AWS_BILLING_PROFILE |
Cost Explorer, FinOps analysis |
| Network/VPC | $AWS_OPERATIONS_PROFILE |
Flow logs, ENIs, Transit Gateway, network analysis |
| Per-account resource | Account-specific ReadOnly | EC2, RDS, S3, SecurityHub, SSM for single account |
Example:
# Per-account EC2 investigation
runbooks inventory ec2-investigate --instance-id i-xxx --profile account-ops
# Org-wide cost discovery (uses billing profile)
runbooks inventory collect --resource-type ec2 --profile billing-aggregator
Output Formats¶
Rich CLI (default): Multi-section panel with color-coding, trees, and visual formatting. Best for terminal viewing.
JSON output: Machine-readable, suitable for CI/CD pipelines, dashboards, automation.
runbooks inventory ec2-investigate --instance-id i-xxx --profile ops --output json > /tmp/output.json
CSV export: Tabular format for Excel/sheets analysis.
CxO Report Generation¶
Generate executive summaries from investigation output:
# Investigate + score for executive report
runbooks inventory ec2-investigate --instance-id i-xxx --profile ops --output json \
| jq '.risk_score, .remediation_steps' > /tmp/executive-findings.json
# Trend analysis across multiple resources
for instance in i-111 i-222 i-333; do
runbooks inventory ec2-investigate --instance-id $instance --output json >> /tmp/findings.jsonl
done
jq -s 'map(.risk_score) | add/length' /tmp/findings.jsonl # Average risk score
ADLC Integration (Claude Code)¶
Delegate complex investigations to the infrastructure-engineer agent:
The agent will: 1. Use awslabs-network MCP to locate the IP address across all regions 2. Chain ec2-investigate with security findings and flow logs 3. Suggest remediation with cost/risk trade-offs 4. Provide a prioritized action plan
Agent delegation benefits: - Multi-region IP lookup (if hostname/IP is ambiguous) - Context-aware remediation (compares current findings to known patterns) - Audit trail in coordination logs
Common Scenarios¶
Incident Response (Nessus Alert)¶
- Get instance ID from alert
- Run EC2 investigation
- Review CRITICAL/HIGH security findings
- Check SSM patch compliance
- Verify network isolation (security group review)
- Review VPC Flow Logs for traffic patterns
runbooks inventory ec2-investigate --instance-id i-xxx --profile ops
runbooks inventory ssm-status --instance-id i-xxx
runbooks vpc flow-log-query --instance-ip 10.x.x.x --vpc-id vpc-xxx
Decommission Evaluation¶
- Investigate EC2 instance (includes activity signals)
- Score decommission candidate (E1-E8 framework)
- Review last connection (WorkSpaces) or network activity (EC2)
- Validate no critical workloads
- Generate decommission report
runbooks inventory ec2-investigate --instance-id i-xxx --profile ops
runbooks inventory score-decommission --instance-id i-xxx --profile ops
Compliance Audit (RDS)¶
- Investigate RDS database
- Verify encryption (KMS key present)
- Check backup retention ≥7 days
- Validate IAM auth enabled
- Review security group restrictions
- Generate compliance report
runbooks inventory rds-investigate --db-instance-id prod-db --profile ops --output json > /tmp/rds-compliance.json
Cost Optimization (S3)¶
- Investigate S3 bucket
- Review lifecycle policies
- Check versioning status (cost impact)
- Analyze storage by access tier across all buckets
- Identify candidates for Intelligent-Tiering
- Generate cost optimization recommendations
runbooks inventory s3-investigate --bucket-name prod-bucket --profile ops
runbooks finops analyze-s3-storage-lens --profile ops
Network Troubleshooting (VPC)¶
- Investigate VPC topology
- Review route tables and transit gateway attachments
- Check security group rules (both sides)
- Analyze VPC Flow Logs for traffic patterns
- Verify DNS configuration
- Identify bottlenecks or missing routes
runbooks inventory vpc-investigate --vpc-id vpc-xxx --profile ops
runbooks vpc topology --profile ops
runbooks vpc analyze --profile ops
runbooks inventory vpc flow-logs --vpc-id vpc-xxx --profile ops
Exit Codes & Error Handling¶
| Exit Code | Meaning | Remediation |
|---|---|---|
| 0 | Success — investigation completed | Review Rich panel or JSON output |
| 1 | Warning — partial findings (e.g., flow logs not enabled) | Proceed; note gaps in findings |
| 2 | Error — resource not found or auth failure | Verify instance ID, VPC ID, profile, region |
| 3 | Access denied | Verify AWS profile has ReadOnly permissions |
Debug mode (verbose output):
References¶
AWS Official Documentation¶
- AWS Systems Manager - DescribeInstanceInformation — SSM agent status and patch compliance
- Amazon VPC Flow Logs — Network traffic analysis and troubleshooting
- AWS Security Hub - GetFindings — Security findings aggregation
- Amazon RDS - Describe DB Instances — RDS database metadata
- Amazon S3 - List Buckets — S3 bucket discovery and configuration
- Amazon WorkSpaces - Describe Workspaces — WorkSpaces instance details
- AWS Well-Architected Framework - Security Pillar — Risk assessment framework
- AWS Config Aggregator — Multi-account compliance audit
Claude Code & ADLC¶
- Claude Code Best Practices — AI-assisted investigation workflows
- Claude Code MCP Integration — awslabs MCP servers for real-time AWS data
- Claude Code Sub-agents — infrastructure-engineer delegation patterns
runbooks PyPI & Documentation¶
- runbooks Package — Enterprise AWS automation toolkit
- CLI Command Catalog — Full command reference (127+ commands)
- Inventory Quickstart — 4-way cross-validation framework
- Cross-Validation Guide — MCP vs AWS CLI accuracy validation
- Persona Guides — CFO/CTO/CloudOps role-specific workflows
Internal Documentation¶
- Reference:
/docs/runbooks/cli-catalog.md— All commands by group - Inventory Quickstart:
/docs/runbooks/inventory/quickstart.md— 4-way cross-validation framework - Cross-Validation Guide:
/docs/runbooks/inventory/cross-validation.md— MCP accuracy validation - Persona Guides:
/docs/runbooks/inventory/persona-guides.md— Role-specific workflows