cdk-insights 0.17.1 → 1.0.0

package/README.md

@@ -1,35 +1,55 @@
 # 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.
+**Catch security issues in your AWS CDK before they reach production.**
 
-👉 Learn more at [cdkinsights.dev](https://cdkinsights.dev)
+Scan your CDK stacks for security vulnerabilities, cost waste, compliance violations, and best practice issues — across 100+ rules and 35+ AWS services. Your source code never leaves your machine.
+
+[![npm version](https://img.shields.io/npm/v/cdk-insights.svg)](https://www.npmjs.com/package/cdk-insights)
+[![npm downloads](https://img.shields.io/npm/dw/cdk-insights.svg)](https://www.npmjs.com/package/cdk-insights)
+
+👉 **[cdkinsights.dev](https://cdkinsights.dev)** | **[Full Documentation](https://cdkinsights.dev/docs)**
+
+---
+
+## Why CDK Insights?
+
+Existing tools (Checkov, cfn-lint, cfn_nag) scan raw CloudFormation. They don't understand CDK constructs, L2/L3 patterns, or developer intent.
+
+CDK Insights is **purpose-built for CDK** — it synthesizes your stacks and analyzes them with CDK context, integrating CDK Nag alongside 100+ custom rules.
+
+**Key differences:**
+- **Local-first** — static analysis runs entirely on your machine, no code uploaded
+- **Zero friction** — no signup, no account, no API keys
+- **Free forever** — static analysis with 100+ rules, JSON/Table/Markdown output, no limits
+- **CDK-native** — understands constructs and patterns, not just CloudFormation
+- **CI/CD ready** — GitHub Action with PR comments and merge blocking
 
 ---
 
 ## 🚀 Quick Start
 
 ```bash
-# Try it immediately without installing
+# Run instantly — no install needed
 npx cdk-insights scan
+```
+
+That's it. CDK Insights will synthesize your stacks and scan them.
+
+### Install in your project
 
-# Or install in your project
+```bash
+# Add to your project
 npm install --save-dev cdk-insights
 
-# Initialize npm scripts automatically
+# Set up npm scripts automatically
 npx cdk-insights init
 
-# Then use familiar npm commands
+# Then use familiar 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`:
-
 ```json
 {
   "scripts": {
@@ -44,47 +64,68 @@ The `init` command adds these npm scripts to your `package.json`:
 
 Use `npx cdk-insights init --all` to include additional scripts for GitHub issues and summary output.
 
-### Quick Compatibility Check
+---
 
-```bash
-node --version  # Should be 20+
-ls cdk.json     # Should exist in CDK project
-```
+## 🔍 What It Catches
+
+CDK Insights scans for real problems across **35+ AWS services**:
+
+| Category | Examples |
+|----------|---------|
+| **Security** | Public S3 buckets, wildcard IAM policies, unencrypted RDS/DynamoDB/SQS, open security groups |
+| **Cost** | Over-provisioned Lambda memory, missing S3 lifecycle policies, unused resources |
+| **Best Practices** | Missing CloudWatch alarms, no VPC flow logs, missing point-in-time recovery |
+| **Compliance** | Encryption at rest, logging enabled, backup configuration |
+
+**Services covered:** S3, IAM, Lambda, RDS, EC2, DynamoDB, SQS, SNS, CloudFront, ECS/Fargate, API Gateway, Cognito, KMS, Secrets Manager, Step Functions, CloudTrail, EventBridge, EBS, WAF, CloudWatch, Route53, ElastiCache, ECR, OpenSearch, VPC, EKS, and more.
 
 ---
 
-## ✨ Features — AWS CDK Security & Cost Analysis
+## 📊 Output Formats
 
-- 🔍 **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
+| Format | Use Case | Command |
+|--------|----------|---------|
+| **Table** | Terminal review (default) | `npx cdk-insights scan` |
+| **JSON** | CI/CD pipelines, automation | `--output json` |
+| **Markdown** | Reports, documentation | `--output markdown` |
+| **Summary** | Quick overview | `--output summary` |
+| **SARIF** | GitHub Code Scanning | `--output sarif` |
 
 ---
 
-## 💡 Usage Examples for AWS CDK Projects
+## 💡 Usage Examples
 
-| 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`                |
+| Scenario | Command |
+|----------|---------|
+| 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 | `npx cdk-insights scan --output markdown > report.md` |
+| CI/CD with fail gate | `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:
+CDK Insights automatically detects CI environments (GitHub Actions, GitLab CI, Jenkins, CircleCI, AWS CodeBuild, and more) and adjusts behavior accordingly.
+
+### GitHub Action
+
+```yaml
+- name: Run CDK Insights
+  uses: instance-labs/cdk-insights-action@v1
+  with:
+    license-key: ${{ secrets.CDK_INSIGHTS_LICENSE_KEY }}
+    fail-on-critical: true
+```
+
+The GitHub Action posts findings as **PR comments**, uploads **SARIF for Code Scanning**, and supports **configurable severity thresholds** for merge blocking.
+
+### Manual CI Setup
 
 ```yaml
-# GitHub Actions example
 - name: Run CDK Insights
-  run: npx cdk-insights scan --fail-on-critical
+  run: npx cdk-insights scan --all --output json --fail-on-critical
   env:
     CDK_INSIGHTS_LICENSE_KEY: ${{ secrets.CDK_INSIGHTS_LICENSE_KEY }}
 ```
@@ -95,19 +136,17 @@ In CI mode, CDK Insights will:
 - Skip interactive prompts
 - Exit with code 1 on critical issues (with `--fail-on-critical`)
 
-👉 [Full CI/CD Setup Guide →](https://github.com/instancelabs/cdk-insights/blob/main/docs/ci-setup.md)
-
 ---
 
-## ⚙️ Configuration & Advanced Usage
+## ⚙️ Configuration
 
-To set default configuration (output format, services, caching, etc.):
+Create a `.cdk-insights.json` in your project root, or run:
 
 ```bash
 npx cdk-insights config setup
 ```
 
-### Enhanced Analysis via CDK Insights Aspect
+### CDK Aspect (Enhanced Analysis)
 
 For precise file/line metadata and richer context, add the aspect in your CDK app:
 
@@ -123,47 +162,49 @@ app.synth();
 
 ---
 
-## 💰 Plans & Pricing
+## 💰 Pricing
+
+| Plan | Price | What's Included |
+|------|-------|-----------------|
+| **Free** | £0 forever | Static analysis (100+ rules), JSON/Table/Markdown/SARIF output, multi-stack analysis, CLI access |
+| **Pro** | £9.99/mo | Everything in Free + AI analysis (Bedrock), GitHub integration, dashboard, PDF reports, 10,000 resources/mo |
+| **Team** | £7.99/member/mo | Everything in Pro + team management, shared configs, audit trails, 15,000 resources/member |
 
-CDK Insights offers flexible tiers:
+Static analysis is **free forever** — no trial, no credit card, no signup required.
 
-- 🆓 **Free** — Basic static scanning & essential checks
-- 🚀 **Pro** — AI-powered insights, unlimited scanning, team features
-- 🏢 **Enterprise** — Advanced compliance, unlimited usage, and dedicated support
+The AI tier adds deep analysis via AWS Bedrock: security analysis, findings categorised by Well-Architected Framework pillar, and context-aware recommendations.
 
-👉 [View full pricing & details →](https://cdkinsights.dev/#pricing)
+👉 [View full pricing](https://cdkinsights.dev/pricing)
 
 ---
 
 ## 🧰 Requirements
 
-- Node.js 18 or later
+- Node.js 22 or later
 - AWS CDK v2 project
 
+### Quick Compatibility Check
+
+```bash
+node --version  # Should be 22+
+ls cdk.json     # Should exist in CDK project
+```
+
 ---
 
 ## 🔧 Troubleshooting
 
 ### Cache Management
 
-CDK Insights caches analysis results to speed up subsequent runs:
-
 ```bash
-# 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
+npx cdk-insights clear-cache    # Clear all caches
+npx cdk-insights cache-status   # Check cache status
+npx cdk-insights scan --no-cache # Run without cache
 ```
 
 ### Authentication Issues
 
-If you encounter license validation errors:
-
-1. Check your license key is correctly set: `echo $CDK_INSIGHTS_LICENSE_KEY`
+1. Check your license key: `echo $CDK_INSIGHTS_LICENSE_KEY`
 2. Clear the auth cache: `npx cdk-insights clear-cache`
 3. Verify your internet connection
 
@@ -172,41 +213,16 @@ If you encounter license validation errors:
 CDK Insights detects potentially sensitive data in your CloudFormation templates:
 
 ```bash
-# 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`:
-
-```json
-{
-  "sensitiveDataDetection": {
-    "enabled": true,
-    "warnOnly": false,
-    "allowPatterns": ["^test-"],
-    "ignoreProperties": ["Description"]
-  }
-}
+npx cdk-insights scan --fail-on-critical  # Fail on sensitive data (default)
+npx cdk-insights scan --warn-sensitive     # Warn but continue
 ```
 
 ---
 
-## 📚 Links & Resources
-
-- [GitHub Repository & Issues](https://github.com/instancelabs/cdk-insights)
-- [Documentation](https://github.com/instancelabs/cdk-insights/tree/main/docs)
-- [Pricing & Tiers](https://cdkinsights.dev/#pricing)
-- License: MIT
-
----
-
-Start with:
-
-```bash
-npx cdk-insights scan
-```
+## 📚 Links
 
-And explore outputs, configuration, and integrations from there. 🚀
+- **Website:** [cdkinsights.dev](https://cdkinsights.dev)
+- **Documentation:** [cdkinsights.dev/docs](https://cdkinsights.dev/docs)
+- **Pricing:** [cdkinsights.dev/pricing](https://cdkinsights.dev/pricing)
+- **npm:** [npmjs.com/package/cdk-insights](https://www.npmjs.com/package/cdk-insights)
+- **License:** MIT

package/dist/analysis/static/staticAnalysis.d.ts

@@ -1,5 +1,6 @@
 import type { AnalysisResults, CloudFormationStack, CreateFindingFunction, ServiceName, Severity } from '../../types/analysis.types';
 import type { ConstructMetadata } from './solutionConstructs/loadConstructMetadata';
+import type { CustomRuleDefinition } from '../../rules/customRules.types';
 export type AnalysisStatistics = {
     totalResources: number;
     analyzedResources: number;
@@ -19,12 +20,14 @@ export type StaticAnalysisOptions = {
     deduplicateFindings?: boolean;
     /** Whether to include statistics in result (default: false) */
     includeStatistics?: boolean;
+    /** User-defined custom rules to evaluate */
+    customRules?: CustomRuleDefinition[];
 };
 export type StaticAnalysisResultWithStats = {
     findings: AnalysisResults;
     statistics: AnalysisStatistics;
 };
-export declare const runStaticAnalysis: (cloudformationTemplate: CloudFormationStack, createFinding: CreateFindingFunction, selectedServices?: ServiceName[], solutionsRegistry?: Record<string, ConstructMetadata>) => AnalysisResults;
+export declare const runStaticAnalysis: (cloudformationTemplate: CloudFormationStack, createFinding: CreateFindingFunction, selectedServices?: ServiceName[], solutionsRegistry?: Record<string, ConstructMetadata>, customRules?: CustomRuleDefinition[]) => AnalysisResults;
 export declare const runStaticAnalysisWithOptions: (cloudformationTemplate: CloudFormationStack, createFinding: CreateFindingFunction, options?: StaticAnalysisOptions) => StaticAnalysisResultWithStats;
 export type BatchAnalysisResult = {
     results: Record<string, AnalysisResults>;

package/dist/cli/config/userConfig.d.ts

@@ -1,4 +1,8 @@
 import type { UserConfig } from '../types/cli.types';
+/**
+ * Recursively strip dangerous keys from an object to prevent prototype pollution.
+ */
+export declare function sanitizeObject<T extends Record<string, unknown>>(obj: T): T;
 export declare const loadUserConfig: () => UserConfig;
 export declare const saveUserConfig: (config: UserConfig) => void;
 export declare const resetUserConfig: () => void;

package/dist/cli/types/cli.types.d.ts

@@ -1,5 +1,5 @@
 import type { Issue, ServiceName } from '../../types/analysis.types';
-export type OutputFormat = 'json' | 'table' | 'markdown' | 'summary' | 'sarif' | 'github-actions';
+export type OutputFormat = 'json' | 'table' | 'markdown' | 'summary' | 'sarif' | 'github-actions' | 'pdf';
 export interface AnalyzeCommandArgs {
     stackName?: string;
     ci?: boolean;
@@ -56,6 +56,8 @@ export interface UserConfig {
     local?: boolean;
     warnSensitive?: boolean;
     allowSensitive?: boolean;
+    /** Disable the interactive feedback prompt after analysis (default: true) */
+    feedback?: boolean;
     /** Sensitive data detection configuration */
     sensitiveDataDetection?: SensitiveDataDetectionConfig;
     cache?: {