Advanced Configuration Options

Complete guide to all available configuration options in CDK Insights. Customize analysis behavior, output format, performance, and filtering to match your specific needs.

Quick Reference

Configuration Options

Configuration Categories

100%

Source Verified

Core Analysis Settings

Control what gets analyzed and how

stackName

stringDefault: ""

Default stack name to analyze

Example:

"stackName": "MyProductionStack"

Use Case: Set default stack for repeated analysis

services

arrayDefault: []

Limit analysis to specific AWS services

Example:

"services": ["S3", "IAM", "Lambda"]

Use Case: Focus analysis on critical services only

ruleFilter

arrayDefault: []

Filter findings by rule categories

Example:

"ruleFilter": ["Security", "Cost Optimization"]

Use Case: Focus on specific compliance areas

synth

booleanDefault: false

Run cdk synth before analysis

Example:

"synth": true

Use Case: Ensure templates are up-to-date

Output Control

Customize output format and content

output

stringDefault: "table"

Output format for results (table, json, markdown, summary, sarif, github-actions)

Example:

"output": "json"

Use Case: Integration with other tools

summaryOnly

booleanDefault: false

Only show summary in console

Example:

"summaryOnly": true

Use Case: Reduce output verbosity

redact

booleanDefault: false

Redact sensitive resource names

Example:

"redact": true

Use Case: Protect sensitive information in logs

withIssue

booleanDefault: false

Create GitHub issues for findings (CLI flag: --with-issue)

Example:

"withIssue": true

Use Case: Automate issue tracking

Cache Configuration

Optimize analysis performance with caching

noCache

booleanDefault: false

Disable caching entirely

Example:

"noCache": true

Use Case: Force fresh analysis every time

cache.enabled

booleanDefault: true

Enable analysis result caching

Example:

"cache.enabled": true

Use Case: Speed up repeated analysis

cache.ttl

numberDefault: 300000

Cache time-to-live in milliseconds

Example:

"cache.ttl": 7200000

Use Case: Balance freshness vs performance

cache.maxSize

numberDefault: 1000

Maximum number of cache entries

Example:

"cache.maxSize": 2000

Use Case: Control memory usage

Behavior Control

Control analysis behavior and error handling

failOnCritical

booleanDefault: true

Exit with error code if critical issues found (CLI flag: --fail-on-critical)

Example:

"failOnCritical": false

Use Case: Continue CI/CD pipeline despite critical issues

feedback

booleanDefault: true

Enable/disable the interactive feedback prompt after analysis

Example:

"feedback": false

Use Case: Suppress feedback prompt in automated environments

allowOveruse

booleanDefault: false

Allow AI analysis to exceed your plan's quota

Example:

"allowOveruse": true

Use Case: Continue AI analysis beyond plan limits when needed

local

booleanDefault: false

Run static analysis only, skip AI recommendations

Example:

"local": true

Use Case: Offline analysis without requiring a license key

warnSensitive

booleanDefault: false

Treat sensitive data findings as warnings instead of errors

Example:

"warnSensitive": true

Use Case: Prevent sensitive data findings from failing CI pipelines

sensitiveDataDetection

objectDefault: {"enabled": true}

Configure sensitive data detection behavior with sub-options: enabled (boolean, default: true), warnOnly (boolean, default: false), strictMode (boolean, default: false), allowPatterns (string[], default: []), ignoreProperties (string[], default: [])

Example:

"sensitiveDataDetection": {"enabled": true, "warnOnly": true, "strictMode": false, "allowPatterns": ["^test-.*"], "ignoreProperties": ["metadata.tags"]}

Use Case: Fine-tune sensitive data detection to reduce false positives

Complete Configuration Example

{
  "// Basic Configuration": {
    "stackName": "MyProductionStack",
    "output": "table",
    "services": [
      "S3",
      "IAM",
      "Lambda",
      "EC2"
    ],
    "ruleFilter": [
      "Security",
      "Cost Optimization"
    ]
  },
  "// Cache Settings": {
    "cache": {
      "enabled": true,
      "ttl": 7200000,
      "maxSize": 200
    },
    "noCache": false
  },
  "// Analysis Control": {
    "synth": true,
    "summaryOnly": false,
    "redact": false,
    "withIssue": false,
    "local": false
  },
  "// Behavior Control": {
    "failOnCritical": true,
    "feedback": true,
    "allowOveruse": false,
    "warnSensitive": false,
    "sensitiveDataDetection": {
      "enabled": true,
      "warnOnly": false,
      "strictMode": false,
      "allowPatterns": [],
      "ignoreProperties": []
    }
  },
  "// GitHub Integration": {
    "withIssue": true,
    "redact": true
  }
}

This example shows a comprehensive configuration covering all major categories. Copy and customize for your specific needs.

Performance Optimization Tips

Use Service Filtering

High Impact

Limit analysis to only the services you care about

"services": ["S3", "IAM"]

Enable Caching

High Impact

Cache results to speed up repeated analysis

"cache": { "enabled": true, "ttl": 7200000 }

Use Rule Filtering

Medium Impact

Focus on specific compliance areas

"ruleFilter": ["Security", "Cost Optimization"]

Enable Synthesis

Medium Impact

Ensure templates are up-to-date before analysis

"synth": true

Use Summary Mode

Low Impact

Reduce output verbosity for faster processing

"summaryOnly": true

CLI Flags vs Configuration Options

📄 Configuration File Options

These options can be saved in your .cdk-insights.json file for persistent settings.

cdk-insights config set output json
cdk-insights config set services "S3,IAM"

🚀 CLI-Only Flags

These flags are only available at runtime and cannot be saved to configuration files.

cdk-insights scan --yes --ci
cdk-insights scan --all --no-cache

Note: The --yes and --ci flags are CLI-only options that cannot be saved to your configuration file. Use them directly in your commands or scripts.

Environment Variables

CDK_INSIGHTS_LICENSE_KEY

License key for AI-powered analysis features

export CDK_INSIGHTS_LICENSE_KEY="your-license-key"

CI

Enable CI mode for automated environments (auto-detected for most CI platforms)

export CI=true

GITHUB_TOKEN

GitHub token for issue creation (preferred over gh CLI)

export GITHUB_TOKEN="ghp_your_token_here"

AWS Credentials

AWS credentials for CDK operations (if not using AWS CLI)

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"

CDK_INSIGHTS_TEAM_ID

Team identifier for team-based subscriptions

export CDK_INSIGHTS_TEAM_ID="your-team-id"

CDK_INSIGHTS_API_URL

Override the default API endpoint URL

export CDK_INSIGHTS_API_URL="https://custom-api.example.com"

Ready to Customize Your Analysis?

Create a .cdk-insights.json file in your project root and start customizing CDK Insights for your specific needs.

Cache Management Learn About Analysis

Documentation

Advanced Options

Docs Home