container-image-scanner/USAGE.md

🚨 EMERGENCY Bitnami Migration Scanner - Critical Timeline Aug 28/Sep 29, 2025. Enterprise scanner for 280+ Bitnami images, 118+ Helm charts with emergency migration automation to AWS alternatives.

# Container Image Scanner - Usage Guide

🔍 **Enterprise tool for assessing Broadcom's impact on Bitnami containers across AWS EKS clusters**

## 🚨 Broadcom Bitnami Changes

**Broadcom is removing free access to Bitnami container images.** This tool helps you:
- **Identify impact**: Find all Bitnami dependencies in your EKS clusters
- **Assess risk**: Understand which deployments will break
- **Plan migration**: Get AWS-native alternatives and migration guidance

## 🚀 Quick Start

```bash
# 1. Install globally
npm install -g container-image-scanner@2.4.0

# 2. Verify installation
cis doctor

# 3. Configure AWS credentials (if not already done)
aws configure

# 4. Scan your AWS Organization for Bitnami impact
cis analyze --org-scan --regions us-east-1,us-west-2

# 5. Generate migration plan for at-risk deployments
cis migrate --input scan-results.json
```

## 📊 Impact Assessment

The tool distinguishes between safe and at-risk deployments:

### ✅ SAFE - Latest Tags
```
📦 bitnami/redis:latest
✅ GOOD: Using "latest" tag - no breaking changes expected
🥇 AWS Managed Service: Amazon ElastiCache for Redis
```

### 🚨 CRITICAL - Pinned Versions
```
📦 bitnami/mysql:8.0.35
🚨 CRITICAL: Pinned version may break - Broadcom removing free Bitnami images
📋 MIGRATION REQUIRED: Switch to AWS managed service or upstream alternative
🥇 AWS Managed Service: Amazon RDS for MySQL
🥈 Upstream: mysql:8.0
🥉 Partner: PlanetScale (AWS Marketplace)
```

## 🔧 Commands

### Analyze Command
```bash
# Scan entire AWS Organization
cis analyze --org-scan --regions us-east-1,us-west-2,eu-west-1

# Scan specific accounts
cis analyze --accounts 123456789012,987654321098 --regions us-east-1

# Show only critical breaking changes
cis analyze --critical-only --accounts 123456789012

# Verbose output with detailed logging
cis analyze --verbose --org-scan --regions us-east-1
```

### Migration Command
```bash
# Generate migration plan
cis migrate --input scan-results.json

# Specify output directory
cis migrate --input scan-results.json --output ./my-migration-plan

# Generate bash migration scripts
cis migrate --input scan-results.json --script-type bash

# Include updated Kubernetes manifests
cis migrate --input scan-results.json --update-manifests

# Generate updated Helm values
cis migrate --input scan-results.json --helm-values
```

### Other Commands
```bash
# System diagnostics
cis doctor

# Setup cross-account IAM roles
cis setup-roles --accounts 123456789012,987654321098

# Interactive query mode
cis analyze --interactive --accounts 123456789012

# Search for specific images
cis analyze --search mysql --accounts 123456789012
```

## ✅ Key Capabilities

- **280+ Bitnami Images**: Universal detection across all registries
- **118+ Helm Charts**: Bitnami Helm chart detection and alternatives
- **Multi-Account**: AWS Organizations + specific accounts
- **Private Registries**: ECR, Harbor, Artifactory support
- **AWS Alternatives**: 67+ service mappings to managed services
- **Migration Strategy**: AWS → Upstream → Partners → Bitnami Premium
- **Impact Assessment**: Breaking change analysis for pinned vs latest tags
- **EKS-Focused**: No ECS recommendations, pure EKS/managed services

## 📋 Migration Strategy (Broadcom Response)

1. **AWS Managed Services** (Primary)
   - Amazon RDS for MySQL/PostgreSQL
   - Amazon ElastiCache for Redis
   - Amazon MSK for Kafka
   - Amazon OpenSearch Service
   - Amazon DocumentDB for MongoDB

2. **Upstream Images** (Secondary)
   - Official Docker Hub images (mysql:8.0, redis:7-alpine, etc.)
   - Maintained by original project teams

3. **Partner Solutions** (Tertiary)
   - AWS Marketplace alternatives
   - Commercial support options

4. **Bitnami Premium** (Last Resort)
   - Commercial Bitnami support
   - Paid access to Bitnami images

## 🛠️ Prerequisites

### Required Tools
- **AWS CLI**: Configured with appropriate permissions
- **kubectl**: Access to EKS clusters
- **Node.js**: Version 16+ for the CLI tool

### AWS Permissions
The tool requires permissions to:
- List and describe EKS clusters
- Assume cross-account roles (for org scanning)
- Read container images from ECR

### Kubernetes Access
- kubectl configured for each EKS cluster
- Appropriate RBAC permissions to read:
  - Pods, Deployments, StatefulSets, DaemonSets
  - Helm releases (if using Helm)

## 📊 Output Formats

### Console Output
Rich terminal output with:
- Color-coded risk levels
- Progress indicators
- Summary tables
- Actionable recommendations

### JSON Output
```bash
cis analyze --output scan-results.json --accounts 123456789012
```

### Migration Plans
Generated markdown files with:
- Step-by-step migration instructions
- AWS service alternatives
- Kubernetes manifest updates
- Helm chart modifications

## 🔍 Advanced Features

### Organization Scanning
```bash
# Scan all accounts in AWS Organization
cis analyze --org-scan --regions us-east-1,us-west-2

# Use custom cross-account role pattern
cis analyze --org-scan --role-arn "arn:aws:iam::{account}:role/ContainerScanRole"
```

### Filtering and Search
```bash
# Show only critical risk images
cis analyze --critical-only --accounts 123456789012

# Search for specific images
cis analyze --search "mysql,postgres" --accounts 123456789012

# Filter by risk level
cis analyze --filter "riskLevel=CRITICAL" --accounts 123456789012
```

### Interactive Mode
```bash
# Start interactive query session after scan
cis analyze --interactive --accounts 123456789012
```

## 🤝 Support

For complex migration scenarios involving Broadcom's Bitnami changes:
- Engage **AWS Specialist SAs** for technical guidance
- Contact your **AWS account team** for strategic planning
- Use AWS Support for implementation assistance

## 🐛 Troubleshooting

### Common Issues

**"No EKS clusters found"**
- Verify AWS credentials and region settings
- Check EKS cluster permissions
- Ensure clusters exist in specified regions

**"kubectl not configured"**
- Run: `aws eks update-kubeconfig --region <region> --name <cluster-name>`
- Verify kubectl access: `kubectl get nodes`

**"Permission denied"**
- Check AWS IAM permissions for EKS and cross-account access
- Verify kubectl RBAC permissions

### Getting Help
```bash
# System diagnostics
cis doctor

# Command help
cis --help
cis analyze --help
cis migrate --help
```

## 📚 Examples

### Example 1: Quick Organization Assessment
```bash
# Install and run organization-wide scan
npm install -g container-image-scanner@2.4.0
cis analyze --org-scan --regions us-east-1,us-west-2
```

### Example 2: Specific Account Migration Planning
```bash
# Scan specific account and generate migration plan
cis analyze --accounts 123456789012 --regions us-east-1 --output results.json
cis migrate --input results.json --output ./migration-plan
```

### Example 3: Critical Issues Only
```bash
# Focus on breaking changes only
cis analyze --critical-only --org-scan --regions us-east-1,us-west-2
```

---

**This tool specifically addresses Broadcom's removal of free Bitnami access and helps customers plan their response strategy.**