CDK Insights 🔍

AI-powered AWS CDK analysis tool for developers and teams.
Scan your AWS CDK stacks for security vulnerabilities, cost optimization opportunities, and best practice issues.
Integrating and building upon tool like cdk-nag, CDK Insights adds AI-powered recommendations for smarter cloud infrastructure improvements.

👉 Learn more at cdkinsights.dev

🚀 Quick Start

# Try it immediately without installing
npx cdk-insights scan

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

# Initialize npm scripts automatically
npx cdk-insights init

# Then use familiar npm commands
npm run cdk-insights
npm run cdk-insights:all
npm run cdk-insights:ci

What cdk-insights init adds

The init command adds these npm scripts to your package.json:

{
  "scripts": {
    "cdk-insights": "cdk-insights scan",
    "cdk-insights:all": "cdk-insights scan --all",
    "cdk-insights:json": "cdk-insights scan --output json",
    "cdk-insights:markdown": "cdk-insights scan --output markdown",
    "cdk-insights:ci": "cdk-insights scan --all --output json --fail-on-critical"
  }
}

Use npx cdk-insights init --all to include additional scripts for GitHub issues and summary output.

Quick Compatibility Check

node --version  # Should be 20+
ls cdk.json     # Should exist in CDK project

✨ Features — AWS CDK Security & Cost Analysis

• 🔍 Static analysis across 20+ AWS services (IAM, S3, Lambda, DynamoDB, RDS, EC2, API Gateway, and more)
• 🤖 AI-powered recommendations using AWS Bedrock (Pro & Enterprise tiers)
• 📊 Multiple output formats: table, JSON, Markdown, or summary
• ⚙️ Configurable via .cdk-insights.json
• 🔗 GitHub integration: create issues directly from findings
• 🛡️ Security checks for IAM policies, S3 buckets, encryption, secrets, and more
• 💰 Cost optimization insights for EC2, DynamoDB, RDS, and Lambda usage

💡 Usage Examples for AWS CDK Projects

| Scenario | Command Example | | ---------------------- | --------------------------------------------------------------------- | | Full project scan | npx cdk-insights scan --all --output summary | | Security-only focus | npx cdk-insights scan --services IAM,S3,KMS --rule-filter Security | | Markdown report output | npx cdk-insights scan --output markdown > report.md | | CI/CD pipeline check | npx cdk-insights scan --all --output json --fail-on-critical | | Create GitHub issue | npx cdk-insights scan --output markdown --with-issue |

🔄 CI/CD Integration

CDK Insights automatically detects CI environments (GitHub Actions, GitLab CI, Jenkins, etc.) and adjusts behavior accordingly:

# GitHub Actions example
- name: Run CDK Insights
  run: npx cdk-insights scan --fail-on-critical
  env:
    CDK_INSIGHTS_LICENSE_KEY: ${{ secrets.CDK_INSIGHTS_LICENSE_KEY }}

In CI mode, CDK Insights will:

• Automatically analyze all stacks
• Output JSON format for easy parsing
• Skip interactive prompts
• Exit with code 1 on critical issues (with --fail-on-critical)

👉 Full CI/CD Setup Guide →

⚙️ Configuration & Advanced Usage

To set default configuration (output format, services, caching, etc.):

npx cdk-insights config setup

Enhanced Analysis via CDK Insights Aspect

For precise file/line metadata and richer context, add the aspect in your CDK app:

import { App, Aspects } from 'aws-cdk-lib';
import { CdkInsightsAspect } from 'cdk-insights';

const app = new App();
Aspects.of(app).add(new CdkInsightsAspect());
// define stacks...
app.synth();

💰 Plans & Pricing

CDK Insights offers flexible tiers:

• 🆓 Free — Basic static scanning & essential checks
• 🚀 Pro — AI-powered insights, unlimited scanning, team features
• 🏢 Enterprise — Advanced compliance, unlimited usage, and dedicated support

👉 View full pricing & details →

🧰 Requirements

• Node.js 18 or later
• AWS CDK v2 project

🔧 Troubleshooting

Cache Management

CDK Insights caches analysis results to speed up subsequent runs:

# Clear all caches (analysis + auth tokens)
npx cdk-insights clear-cache

# Check cache status
npx cdk-insights cache-status

# Run analysis without using cache
npx cdk-insights scan --no-cache

Authentication Issues

If you encounter license validation errors:

1. Check your license key is correctly set: echo $CDK_INSIGHTS_LICENSE_KEY
2. Clear the auth cache: npx cdk-insights clear-cache
3. Verify your internet connection

Sensitive Data Detection

CDK Insights detects potentially sensitive data in your CloudFormation templates:

# Fail on sensitive data detection (default)
npx cdk-insights scan --fail-on-critical

# Warn but continue on sensitive data
npx cdk-insights scan --warn-sensitive

Configure detection in .cdk-insights.json:

{
  "sensitiveDataDetection": {
    "enabled": true,
    "warnOnly": false,
    "allowPatterns": ["^test-"],
    "ignoreProperties": ["Description"]
  }
}

📚 Links & Resources

• GitHub Repository & Issues
• Documentation
• Pricing & Tiers
• License: MIT

Start with:

npx cdk-insights scan

And explore outputs, configuration, and integrations from there. 🚀