cdk-insights

# CDK Insights 🔍 > **AI-Powered Analysis Tool for AWS CDK Stacks** CDK Insights helps you identify security vulnerabilities, cost optimization opportunities, and best practice issues in your AWS CDK infrastructure. It combines static analysis with AI-powered recommendations to provide actionable insights for improving your cloud infrastructure. > **🚧 Currently in Beta** - We're actively developing and improving CDK Insights. The current version is stable for testing and early adoption, but we recommend using it in development environments first. ## ✨ What CDK Insights Does - **🔍 Static Analysis**: Automatically checks your CDK code for 20+ AWS services - **🤖 AI-Powered Insights**: Gets intelligent recommendations using AWS Bedrock (Pro subscription) - **📊 Multiple Output Formats**: View results as JSON, Markdown, Table, or Summary - **🔧 Easy to Use**: Simple CLI with interactive prompts - **⚙️ Configurable**: Save your preferences and customize what gets analyzed - **🔗 GitHub Integration**: Create issues directly from findings - **🛡️ Security Focus**: Comprehensive security checks and recommendations - **💰 Cost Optimization**: Find opportunities to reduce AWS costs ## 🚀 Get Started in 30 Seconds ### Try It Now (No Installation Required) ```bash # Run immediately without installing anything npx cdk-insights scan ``` That's it! CDK Insights will: 1. Scan your CDK stacks 2. Show you issues it found 3. Provide recommendations to fix them ### Install for Regular Use **For Teams (Recommended):** ```bash # Install in your project npm install --save-dev cdk-insights # Add to your package.json scripts ``` ```json { "scripts": { "cdk-insights": "node scripts/cdk-insights-wrapper.js" } } ``` **Using NPM Scripts (Recommended):** After installing, you can use convenient npm scripts: ```bash # Basic scan npm run scan # Scan all stacks npm run scan:all # Different output formats npm run scan:json npm run scan:markdown npm run scan:summary # Setup CDK Nag integration npm run cdk-insights -- setup-cdk-nag # Install Git pre-commit hooks npm run cdk-insights -- hook # Cache management npm run cdk-insights -- cache-status npm run cdk-insights -- cache:clear # Configuration npm run cdk-insights -- config list ``` **For Personal Use:** ```bash # Install globally npm install -g cdk-insights # Use from anywhere cdk-insights scan ``` ## 📖 How to Use CDK Insights ### Basic Commands ```bash # Scan a specific stack cdk-insights scan MyStack # Scan all stacks in your project cdk-insights scan --all # Interactive mode (recommended for first time) cdk-insights scan ``` ### What You'll See ``` 🔍 Analyzing stack: MyStack 📊 Found 12 issues across 8 resources 🔴 CRITICAL (2) • IAM policy allows full access to all resources • S3 bucket allows public ACLs 🟡 MEDIUM (7) • Lambda function has high memory allocation • DynamoDB table has no auto-scaling enabled 🟢 LOW (3) • S3 bucket does not use Intelligent-Tiering ✅ Analysis complete. ``` ### Output Formats Choose how you want to see your results: ```bash # Table format (default) - great for quick review cdk-insights scan --output table # Markdown format - perfect for GitHub issues and PRs cdk-insights scan --output markdown # JSON format - ideal for CI/CD pipelines cdk-insights scan --output json # Summary format - just the essentials cdk-insights scan --output summary ``` ## 🔍 What Gets Scanned CDK Insights checks your infrastructure across these AWS services: | Service | What It Checks | Focus Areas | | ------------------- | ---------------------- | ------------------------------ | | **IAM** | Policy permissions | Security, Least privilege | | **S3** | Bucket settings | Security, Cost optimization | | **Lambda** | Function configuration | Performance, Security | | **DynamoDB** | Table settings | Cost optimization, Performance | | **RDS** | Database configuration | Security, Cost optimization | | **EC2** | Instance settings | Cost optimization, Security | | **API Gateway** | Endpoint security | Security | | **CloudTrail** | Logging setup | Security, Compliance | | **KMS** | Key policies | Security | | **SNS/SQS** | Message security | Security | | **Step Functions** | Workflow configuration | Security, Performance | | **EventBridge** | Rule configuration | Security, Performance | | **Secrets Manager** | Secret configuration | Security | | **EBS** | Volume management | Cost optimization | ## 🎯 Common Use Cases ### Security Audits ```bash # Focus on security issues cdk-insights scan --services IAM,S3,KMS,SecretsManager ``` ### Cost Optimization ```bash # Find cost savings opportunities cdk-insights scan --services EC2,DynamoDB,RDS,EBS ``` ### Before Deployments ```bash # Full scan before going to production cdk-insights scan --all --output markdown ``` ### In Your CI/CD Pipeline ```bash # Automated checks in your deployment process cdk-insights scan --output json | jq '.summary.totalIssues' ``` ## ⚙️ Configuration Set your preferences once and CDK Insights will remember them: ```bash # Set your preferred output format cdk-insights config set output markdown # Set default services to scan cdk-insights config set services IAM,S3,Lambda # View your current settings cdk-insights config list # Clear your settings cdk-insights config reset ``` ## 🤖 AI-Powered Analysis (Pro Feature) Upgrade to Pro for intelligent, context-aware recommendations: - **Smart Suggestions**: AI understands your specific infrastructure - **Custom Fixes**: Get code examples tailored to your setup - **Pattern Recognition**: AI spots complex architectural issues - **Natural Language**: Clear explanations of what's wrong and how to fix it [Learn more about AI features →](docs/ai-features.md) ## 💰 Pricing & Plans CDK Insights offers three flexible tiers to meet your needs: ### 🆓 Free Tier **Perfect for getting started and small projects** **Price**: $0/month **Core Features**: - ✅ Basic static scanning (5 scans/month) - ✅ Multi-stack scanning (10 stacks/month) - ✅ Table, JSON, and Markdown output formats - ✅ CLI tool access - ✅ Local scanning - ✅ Community support - ✅ Basic security checks - ✅ Basic reporting **Limits**: - 5 basic scans per month - 10 multi-stack scans per month - 1 team member - 5 project fingerprints --- ### 🚀 Pro Tier **Ideal for development teams and growing projects** **Price**: $29/month **Everything in Free, plus**: - ✅ **Unlimited** basic and multi-stack scanning - ✅ AI-powered recommendations (100/month) - ✅ Contextual fix suggestions (100/month) - ✅ Smart prioritization - ✅ Natural language explanations - ✅ Custom rule creation (50 rules) - ✅ Advanced compliance frameworks - ✅ PDF reports (20/month) - ✅ GitHub integration (100 integrations/month) - ✅ Team dashboards - ✅ Shared configurations (10 configs) - ✅ Cloud-based scanning - ✅ Parallel scanning - ✅ Caching & incremental scanning - ✅ Large project support (1000+ resources) - ✅ Email support - ✅ SOC2 & HIPAA compliance - ✅ Advanced analytics **Limits**: - 100 AI recommendations per month - 100 contextual fixes per month - 50 custom rules - 20 PDF reports per month - 100 GitHub integrations per month - 10 shared configurations - 5 team members - 10 project fingerprints --- ### 🏢 Enterprise Tier **For large organizations with advanced requirements** **Price**: Contact sales **Everything in Pro, plus**: - ✅ **Unlimited** AI recommendations and contextual fixes - ✅ Historical trend scanning - ✅ Dependency mapping - ✅ Custom AI training - ✅ Executive summaries - ✅ Custom branded reports - ✅ Role-based access control - ✅ Collaborative commenting - ✅ Team analytics - ✅ API access (10,000 calls/month) - ✅ Webhook notifications - ✅ CI/CD integration - ✅ Custom integrations - ✅ Advanced filtering & search - ✅ Priority support - ✅ Dedicated account manager - ✅ Custom training - ✅ FedRAMP compliance - ✅ Custom compliance frameworks - ✅ Audit trails - ✅ SSO integration - ✅ Custom dashboards - ✅ White-labeling - ✅ Custom branding - ✅ Multi-tenant support **Limits**: - 10,000 API calls per month - Unlimited team members - Unlimited project fingerprints - Unlimited custom rules - Unlimited PDF reports --- ### 🔄 Upgrade Path **Free → Pro**: Unlock AI-powered insights and team features **Pro → Enterprise**: Get enterprise-grade features and unlimited usage ### 💳 Billing & Support - **Free Tier**: No credit card required - **Pro Tier**: Monthly billing, cancel anytime - **Enterprise**: Annual billing with volume discounts - **Support**: Email support for Pro+, priority support for Enterprise ### 🎯 Choose Your Plan | Feature Category | Free | Pro | Enterprise | | ----------------- | --------- | ---------- | ---------- | | **Scanning** | 5/month | Unlimited | Unlimited | | **AI Features** | ❌ | 100/month | Unlimited | | **Team Features** | 1 user | 5 users | Unlimited | | **Integrations** | Basic | GitHub | All | | **Support** | Community | Email | Priority | | **Compliance** | Basic | SOC2/HIPAA | FedRAMP | [Get Started Free →](https://cdkinsights.dev/signup) | [View Pro Plan →](https://cdkinsights.dev/pricing) | [Contact Sales →](https://cdkinsights.dev/enterprise) For detailed pricing information, see our [complete pricing guide](docs/pricing.md). ## 🔗 GitHub Integration Create GitHub issues directly from your findings: ```bash # Create issues for all findings cdk-insights scan --with-issue # Create issues for critical findings only cdk-insights scan --with-issue --rule-filter Security ``` ## 📊 Understanding Your Results ### Severity Levels - **🔴 CRITICAL**: Security vulnerabilities or major issues that need immediate attention - **🟡 MEDIUM**: Issues that should be addressed soon for better security/cost - **🟢 LOW**: Minor optimizations and best practice recommendations ### Issue Types - **Security**: IAM policies, encryption, access controls - **Cost Optimization**: Resource sizing, unused resources, better pricing models - **Performance**: Configuration that could impact speed or efficiency - **Compliance**: Best practices and industry standards ## 🛠️ Troubleshooting ### Common Issues **"No stacks found"** - Make sure you're in a CDK project directory - Run `cdk synth` first to generate CloudFormation templates **"Permission denied"** - Ensure you have read access to your CDK project files - Check that your AWS credentials are configured **"Scan is slow"** - Use `--services` to limit what gets scanned - Try `--output summary` for faster results ### Getting Help - **Documentation**: [docs/](docs/) - **Issues**: [GitHub Issues](https://github.com/TheLeePriest/cdk-insights/issues) - **Discussions**: [GitHub Discussions](https://github.com/TheLeePriest/cdk-insights/discussions) ## 📄 License CDK Insights is licensed under the MIT License. Some functionality integrates with cdk-nag, which is licensed under Apache License 2.0. --- **Ready to improve your CDK infrastructure?** Start with `npx cdk-insights scan` and discover what insights await! 🚀