Your First Scan
Learn how to run your first CDK Insights scan and understand the results. This guide will walk you through the complete process from setup to analysis interpretation.
Prerequisites
Before running your first scan, ensure you have:
- CDK Application - A working CDK app with at least one stack
- AWS Credentials - Configured AWS CLI or environment variables
- CDK Synthesized - Run
cdk synthsuccessfully - Node.js - Version 18 or higher installed
If you haven't set up a CDK project yet, follow the Quick Start guide first.
Step-by-Step Guide
Navigate to Your CDK Project
Open your terminal and go to your CDK project directory
cd my-cdk-projectTip: Make sure you have a valid CDK application with stacks defined
Verify CDK App Structure
Ensure your CDK app is properly set up and can synthesize
cdk synthTip: This generates CloudFormation templates that CDK Insights will analyze
Run Your First Scan
Execute CDK Insights to analyze your infrastructure
npx cdk-insights scanTip: The scan will analyze all stacks in your CDK application
Review the Results
Examine the analysis output and understand the findings
# Results will be displayed in the terminalTip: Pay attention to critical and high severity issues first
Understanding Your Results
Critical
Immediate security or compliance issues
Action Required:
Fix immediately before deploying
Common Examples:
- S3 buckets allowing public ACLs
- IAM policies with wildcard (*) permissions
- Unencrypted RDS databases
High
Security or configuration issues that should be addressed
Action Required:
Address within the current development cycle
Common Examples:
- S3 buckets missing encryption
- Security groups allowing unrestricted ingress
- Sensitive environment variables in Lambda
Medium
Best practice violations or optimization opportunities
Action Required:
Plan to address in upcoming iterations
Common Examples:
- S3 bucket versioning not enabled
- RDS instance not in Multi-AZ
- Lambda functions with high memory allocation
Low
Minor issues or suggestions for improvement
Action Required:
Address when convenient or during refactoring
Common Examples:
- S3 bucket not using Intelligent-Tiering
- NAT Gateway without route table association
- Cost optimization opportunities
Common First Scan Results
S3 bucket without encryption
HIGHYour S3 bucket is not encrypted, which could expose sensitive data
Recommendation:
Enable server-side encryption using S3 managed keys or KMS
encryption: s3.BucketEncryption.S3_MANAGEDIAM role with overly permissive policies
CRITICALIAM role has policies that grant more permissions than necessary
Recommendation:
Follow the principle of least privilege and restrict permissions
managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName("ReadOnlyAccess")]Lambda function with high memory allocation
MEDIUMLambda function has high memory allocation that may be unnecessary
Recommendation:
Consider reducing memory allocation to optimize costs
memorySize: 256, // Reduce from 3008MB if not neededS3 bucket not using Intelligent-Tiering
LOWS3 bucket could benefit from Intelligent-Tiering for automatic cost optimization
Recommendation:
Enable Intelligent-Tiering for automatic cost optimization of infrequently accessed objects
intelligentTieringConfigurations: [{ id: "archive", status: "Enabled" }]What's Next?
Address Critical Issues
Focus on fixing critical and high severity issues first
Action: Review and fix security vulnerabilities immediately
Set Up Configuration
Create a .cdk-insights.json file for consistent analysis
Action: Configure default settings for your team workflow
Integrate with CI/CD
Add CDK Insights to your continuous integration pipeline
Action: Prevent issues from reaching production
Troubleshooting Your First Scan
❌ "No stacks found to analyze"
Make sure you have defined stacks in your CDK app and run cdk synth first.
❌ "AWS credentials not configured"
Configure AWS credentials using AWS CLI or environment variables aws configure.
❌ "Analysis takes too long"
For large CDK apps, try limiting the scope with --services S3,IAM.
Ready to Dive Deeper?
Now that you've run your first scan, explore advanced features and configuration options to get the most out of CDK Insights.