Skip to main content
Skip to main content

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

22
Configuration Options
7
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: --withIssue)

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

Cache time-to-live in milliseconds. Default 6 hours. Cache lives in process memory and resets on each CLI run.

Example:

"cache.ttl": 7200000

Use Case: Shorten for very active development; lengthen for stable codebases

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

AI Recommendations

Configure model selection and batching for the AI tier

ai.model

stringDefault: tier default (free: nova-lite, pro/team: mistral-14b)

Bedrock model used for AI recommendations. Accepts: nova-lite, mistral-14b, haiku-4-5, sonnet-4-6.

Example:

"ai.model": "sonnet-4-6"

Use Case: Pick the cost/quality trade-off that suits your workflow. Free tier is always served Nova Lite regardless of selection.

ai.batchSize

numberDefault: 1

Resources per AI request. Default 1 (off — each resource is its own request). Increase to batch multiple resources into a single call. Maximum: 10.

Example:

"ai.batchSize": 5

Use Case: Reduce per-request overhead on large stacks at the cost of slightly larger individual prompts.

Scan History

Opt in to uploading each scan to your cdkinsights.dev dashboard

scanHistory.enabled

booleanDefault: false

When true, the CLI uploads each analysis report at the end of the run. Reports are license-keyed, viewable at https://cdkinsights.dev/scans, and auto-expire after 30 days. The upload is best-effort and never blocks the run.

Example:

"scanHistory.enabled": true

Use Case: Track scan history across CI runs without managing artifacts manually.

Telemetry

Anonymous opt-in usage analytics — see the dedicated telemetry page for the full schema

telemetry.enabled

booleanDefault: false

When true, the CLI emits anonymised events (cliVersion, tier, platform, command shape) to help us prioritise improvements. No source code, license keys, or stack contents are ever sent.

Example:

"telemetry.enabled": true

Use Case: Help shape the product roadmap by sharing what you actually use.

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 ManagementLearn About Analysis

Documentation

Advanced Options

Docs Home