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)

# Run immediately without installing anything
npx cdk-insights scan

That's it! CDK Insights will:

• Scan your CDK stacks
• Show you issues it found
• Provide recommendations to fix them

Install for Regular Use

For Teams (Recommended):

# Install in your project
npm install --save-dev cdk-insights

# Add to your package.json scripts

{
  "scripts": {
    "cdk-insights": "node scripts/cdk-insights-wrapper.js"
  }
}

Using NPM Scripts (Recommended):

After installing, you can use convenient npm scripts:

# 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:

# Install globally
npm install -g cdk-insights

# Use from anywhere
cdk-insights scan

📖 How to Use CDK Insights

Basic Commands

# 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:

# 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

# Focus on security issues
cdk-insights scan --services IAM,S3,KMS,SecretsManager

Cost Optimization

# Find cost savings opportunities
cdk-insights scan --services EC2,DynamoDB,RDS,EBS

Before Deployments

# Full scan before going to production
cdk-insights scan --all --output markdown

In Your CI/CD Pipeline

# 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:

# 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 →

💰 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 → | View Pro Plan → | Contact Sales →

For detailed pricing information, see our complete pricing guide.

🔗 GitHub Integration

Create GitHub issues directly from your findings:

# 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/
• Issues: GitHub Issues
• Discussions: GitHub 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! 🚀