cdk-insights 0.3.0 β 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +60 -653
- package/dist/cli/config/mergeUserConfig.d.ts +1 -1
- package/dist/cli/entry.js +3126 -2781
- package/dist/config/featureGating.d.ts +1 -1
- package/dist/index.js +115 -46
- package/dist/shared/analysisProgress.d.ts +5 -5
- package/dist/shared/featureFlags.d.ts +1 -1
- package/dist/shared/featureGating.d.ts +2 -2
- package/dist/shared/terminalOutput.d.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,57 +1,25 @@
|
|
|
1
1
|
# CDK Insights π
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**AI-powered AWS CDK analysis tool** for developers and teams.
|
|
4
|
+
Scan your AWS CDK stacks for **security vulnerabilities, cost optimization opportunities, and best practice issues**.
|
|
5
|
+
Unlike tools like **cdk-nag**, CDK Insights adds **AI-powered recommendations** for smarter cloud infrastructure improvements.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
π Learn more at [cdkinsights.dev](https://cdkinsights.dev)
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## π Quick Start (30 Seconds)
|
|
10
|
-
|
|
11
|
-
### Before You Start
|
|
12
|
-
|
|
13
|
-
**What You Need:**
|
|
14
|
-
|
|
15
|
-
- A CDK project with at least one stack
|
|
16
|
-
- Node.js installed
|
|
17
|
-
- AWS CDK CLI installed (`npm install -g aws-cdk`)
|
|
18
|
-
|
|
19
|
-
**Quick Check:**
|
|
20
|
-
Make sure you're in your CDK project directory:
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
ls -la
|
|
24
|
-
# Should see: cdk.json, bin/, lib/ (or src/)
|
|
25
|
-
```
|
|
9
|
+
---
|
|
26
10
|
|
|
27
|
-
|
|
11
|
+
## π Quick Start
|
|
28
12
|
|
|
29
13
|
```bash
|
|
30
|
-
#
|
|
14
|
+
# Try it immediately without installing
|
|
31
15
|
npx cdk-insights scan
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
This will:
|
|
35
|
-
|
|
36
|
-
1. Scan your CDK stacks
|
|
37
|
-
2. Show you issues it found
|
|
38
|
-
3. Provide recommendations to fix them
|
|
39
16
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
# 1. Install in your project
|
|
17
|
+
# Or install in your project
|
|
44
18
|
npm install --save-dev cdk-insights
|
|
45
|
-
|
|
46
|
-
# 2. Run your first scan (use npx)
|
|
47
19
|
npx cdk-insights scan
|
|
48
20
|
```
|
|
49
21
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
### Adding NPM Scripts for Convenience (Recommended)
|
|
53
|
-
|
|
54
|
-
**We recommend adding these scripts to your `package.json`** for shorter, more convenient commands:
|
|
22
|
+
You can also add convenience scripts to your `package.json`:
|
|
55
23
|
|
|
56
24
|
```json
|
|
57
25
|
{
|
|
@@ -61,662 +29,101 @@ npx cdk-insights scan
|
|
|
61
29
|
"scan:json": "cdk-insights scan --format json",
|
|
62
30
|
"scan:markdown": "cdk-insights scan --format markdown",
|
|
63
31
|
"scan:summary": "cdk-insights scan --format summary",
|
|
64
|
-
"scan:with-
|
|
32
|
+
"scan:with-issue": "cdk-insights scan --withIssue"
|
|
65
33
|
}
|
|
66
34
|
}
|
|
67
35
|
```
|
|
68
36
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
npm run scan # Interactive scan
|
|
73
|
-
npm run scan:all # Scan all stacks
|
|
74
|
-
npm run scan:json # Scan with JSON output
|
|
75
|
-
npm run scan:markdown # Scan with Markdown output
|
|
76
|
-
npm run scan:summary # Scan with summary output
|
|
77
|
-
npm run scan:with-issues # Scan and create GitHub issues
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
> **π‘ Why add scripts?** While `npx cdk-insights scan` works great, adding scripts makes commands shorter and more memorable. It's also the standard way most npm tools are used in projects.
|
|
81
|
-
|
|
82
|
-
## β¨ What CDK Insights Does
|
|
83
|
-
|
|
84
|
-
- **π Static Analysis**: Automatically checks your CDK code for 20+ AWS services
|
|
85
|
-
- **π€ AI-Powered Insights**: Gets intelligent recommendations using AWS Bedrock (Pro subscription)
|
|
86
|
-
- **π Multiple Output Formats**: View results as JSON, Markdown, Table, or Summary
|
|
87
|
-
- **π§ Easy to Use**: Simple CLI with interactive prompts
|
|
88
|
-
- **βοΈ Configurable**: Save your preferences and customize what gets analyzed
|
|
89
|
-
- **π GitHub Integration**: Create issues directly from findings
|
|
90
|
-
- **π‘οΈ Security Focus**: Comprehensive security checks and recommendations
|
|
91
|
-
- **π° Cost Optimization**: Find opportunities to reduce AWS costs
|
|
92
|
-
|
|
93
|
-
## π How to Use CDK Insights
|
|
94
|
-
|
|
95
|
-
### Basic Commands
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
# Scan a specific stack
|
|
99
|
-
npx cdk-insights scan MyStack
|
|
100
|
-
|
|
101
|
-
# Scan all stacks in your project
|
|
102
|
-
npx cdk-insights scan --all
|
|
103
|
-
|
|
104
|
-
# Interactive mode (recommended for first time)
|
|
105
|
-
npx cdk-insights scan
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
> **π‘ Tip**: After installing CDK Insights, you can use `npx cdk-insights <command>` for all commands. For convenience, we recommend adding scripts to your `package.json` (see section above) so you can use shorter commands like `npm run scan`.
|
|
109
|
-
|
|
110
|
-
### What You'll See
|
|
111
|
-
|
|
112
|
-
```
|
|
113
|
-
π Analyzing stack: MyStack
|
|
114
|
-
π Found 12 issues across 8 resources
|
|
115
|
-
|
|
116
|
-
π΄ CRITICAL (2)
|
|
117
|
-
β’ IAM policy allows full access to all resources
|
|
118
|
-
β’ S3 bucket allows public ACLs
|
|
119
|
-
|
|
120
|
-
π‘ MEDIUM (7)
|
|
121
|
-
β’ Lambda function has high memory allocation
|
|
122
|
-
β’ DynamoDB table has no auto-scaling enabled
|
|
123
|
-
|
|
124
|
-
π’ LOW (3)
|
|
125
|
-
β’ S3 bucket does not use Intelligent-Tiering
|
|
126
|
-
|
|
127
|
-
β
Analysis complete.
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
## π― What Happens Next?
|
|
131
|
-
|
|
132
|
-
### Understanding Your Results
|
|
133
|
-
|
|
134
|
-
**Severity Levels:**
|
|
135
|
-
|
|
136
|
-
- **π΄ CRITICAL**: Security vulnerabilities or major issues that need immediate attention
|
|
137
|
-
- **π‘ MEDIUM**: Issues that should be addressed soon for better security/cost
|
|
138
|
-
- **π’ LOW**: Minor optimizations and best practice recommendations
|
|
139
|
-
|
|
140
|
-
### Common Next Steps
|
|
141
|
-
|
|
142
|
-
**1. Fix Critical Issues First**
|
|
143
|
-
|
|
144
|
-
```bash
|
|
145
|
-
# Focus on critical security issues
|
|
146
|
-
npx cdk-insights scan --rule-filter Security --output table
|
|
147
|
-
# Or if you added scripts: npm run scan
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
**2. Generate a Report for Your Team**
|
|
151
|
-
|
|
152
|
-
```bash
|
|
153
|
-
# Create a markdown report for documentation
|
|
154
|
-
npx cdk-insights scan --output markdown > security-report.md
|
|
155
|
-
# Or if you added scripts: npm run scan:markdown > security-report.md
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
**3. Set Up Regular Checks**
|
|
159
|
-
|
|
160
|
-
```bash
|
|
161
|
-
# Add to your development workflow
|
|
162
|
-
npx cdk-insights scan
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
**4. Integrate with CI/CD**
|
|
166
|
-
|
|
167
|
-
```bash
|
|
168
|
-
# Fail builds on critical issues
|
|
169
|
-
cdk-insights scan --output json --fail-on-critical
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
### Output Formats
|
|
173
|
-
|
|
174
|
-
Choose how you want to see your results:
|
|
175
|
-
|
|
176
|
-
```bash
|
|
177
|
-
# Table format (default) - great for quick review
|
|
178
|
-
cdk-insights scan --output table
|
|
179
|
-
|
|
180
|
-
# Markdown format - perfect for GitHub issues and PRs
|
|
181
|
-
cdk-insights scan --output markdown
|
|
182
|
-
|
|
183
|
-
# JSON format - ideal for CI/CD pipelines
|
|
184
|
-
cdk-insights scan --output json
|
|
185
|
-
|
|
186
|
-
# Summary format - just the essentials
|
|
187
|
-
cdk-insights scan --output summary
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
## π What Gets Scanned
|
|
191
|
-
|
|
192
|
-
CDK Insights checks your infrastructure across these AWS services:
|
|
193
|
-
|
|
194
|
-
| Service | What It Checks | Focus Areas |
|
|
195
|
-
| ------------------- | ---------------------- | ------------------------------ |
|
|
196
|
-
| **IAM** | Policy permissions | Security, Least privilege |
|
|
197
|
-
| **S3** | Bucket settings | Security, Cost optimization |
|
|
198
|
-
| **Lambda** | Function configuration | Performance, Security |
|
|
199
|
-
| **DynamoDB** | Table settings | Cost optimization, Performance |
|
|
200
|
-
| **RDS** | Database configuration | Security, Cost optimization |
|
|
201
|
-
| **EC2** | Instance settings | Cost optimization, Security |
|
|
202
|
-
| **API Gateway** | Endpoint security | Security |
|
|
203
|
-
| **CloudTrail** | Logging setup | Security, Compliance |
|
|
204
|
-
| **KMS** | Key policies | Security |
|
|
205
|
-
| **SNS/SQS** | Message security | Security |
|
|
206
|
-
| **Step Functions** | Workflow configuration | Security, Performance |
|
|
207
|
-
| **EventBridge** | Rule configuration | Security, Performance |
|
|
208
|
-
| **Secrets Manager** | Secret configuration | Security |
|
|
209
|
-
|
|
210
|
-
## π― Common Use Cases
|
|
211
|
-
|
|
212
|
-
### Security Audits
|
|
213
|
-
|
|
214
|
-
```bash
|
|
215
|
-
# Focus on security issues
|
|
216
|
-
cdk-insights scan --services IAM,S3,KMS,SecretsManager
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
### Cost Optimization
|
|
220
|
-
|
|
221
|
-
```bash
|
|
222
|
-
# Find cost savings opportunities
|
|
223
|
-
cdk-insights scan --services EC2,DynamoDB,RDS
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
### Before Deployments
|
|
227
|
-
|
|
228
|
-
```bash
|
|
229
|
-
# Full scan before going to production
|
|
230
|
-
cdk-insights scan --all --output markdown
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
### In Your CI/CD Pipeline
|
|
234
|
-
|
|
235
|
-
```bash
|
|
236
|
-
# Automated checks in your deployment process
|
|
237
|
-
cdk-insights scan --output json | jq '.summary.totalIssues'
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
## βοΈ Configuration
|
|
37
|
+
Then run: `npm run scan`
|
|
241
38
|
|
|
242
|
-
|
|
39
|
+
### Quick Compatibility Check
|
|
243
40
|
|
|
244
41
|
```bash
|
|
245
|
-
#
|
|
246
|
-
cdk
|
|
247
|
-
# or
|
|
248
|
-
npm run cdk-insights config setup
|
|
249
|
-
|
|
250
|
-
# Set your preferred output format
|
|
251
|
-
cdk-insights config set output markdown
|
|
252
|
-
# or
|
|
253
|
-
npm run cdk-insights config set output markdown
|
|
254
|
-
|
|
255
|
-
# Set default services to scan
|
|
256
|
-
cdk-insights config set services IAM,S3,Lambda
|
|
257
|
-
# or
|
|
258
|
-
npm run cdk-insights config set services IAM,S3,Lambda
|
|
259
|
-
|
|
260
|
-
# View your current settings
|
|
261
|
-
cdk-insights config list
|
|
262
|
-
# or
|
|
263
|
-
npm run cdk-insights config list
|
|
264
|
-
|
|
265
|
-
# Clear your settings
|
|
266
|
-
cdk-insights config reset
|
|
267
|
-
# or
|
|
268
|
-
npm run cdk-insights config reset
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
### Configuration File
|
|
272
|
-
|
|
273
|
-
CDK Insights stores configuration in `.cdk-insights.json` in your project root:
|
|
274
|
-
|
|
275
|
-
```json
|
|
276
|
-
{
|
|
277
|
-
"stackName": "MyStack",
|
|
278
|
-
"output": "table",
|
|
279
|
-
"services": ["IAM", "S3", "Lambda"],
|
|
280
|
-
"redact": false,
|
|
281
|
-
"withIssue": false,
|
|
282
|
-
"summaryOnly": false,
|
|
283
|
-
"synth": false,
|
|
284
|
-
"ruleFilter": ["Security", "Cost Optimization"],
|
|
285
|
-
"failOnCritical": true,
|
|
286
|
-
"noCache": false,
|
|
287
|
-
"cache": {
|
|
288
|
-
"enabled": true,
|
|
289
|
-
"ttl": 600000,
|
|
290
|
-
"maxSize": 2000
|
|
291
|
-
}
|
|
292
|
-
}
|
|
293
|
-
```
|
|
294
|
-
|
|
295
|
-
### π Configuration Reference
|
|
296
|
-
|
|
297
|
-
| Field | Type | Default | Description |
|
|
298
|
-
| ---------------- | -------- | ------- | -------------------------------------------------------- |
|
|
299
|
-
| `stackName` | string | "" | Default stack to analyze |
|
|
300
|
-
| `output` | string | "table" | Output format: json/table/markdown/summary |
|
|
301
|
-
| `services` | string[] | [] | AWS services to scan (comma-separated) |
|
|
302
|
-
| `redact` | boolean | false | Redact sensitive resource names in output |
|
|
303
|
-
| `withIssue` | boolean | false | Create GitHub issues for findings (markdown output only) |
|
|
304
|
-
| `summaryOnly` | boolean | false | Only show summary in console |
|
|
305
|
-
| `synth` | boolean | false | Run cdk synth automatically before analysis |
|
|
306
|
-
| `ruleFilter` | string[] | [] | Filter rules by category (comma-separated) |
|
|
307
|
-
| `failOnCritical` | boolean | true | Exit with error code if critical issues found |
|
|
308
|
-
| `noCache` | boolean | false | Disable cache and force fresh analysis |
|
|
309
|
-
| `cache.enabled` | boolean | true | Enable/disable caching |
|
|
310
|
-
| `cache.ttl` | number | 300000 | Cache TTL in milliseconds (5 minutes) |
|
|
311
|
-
| `cache.maxSize` | number | 1000 | Maximum number of cached entries |
|
|
312
|
-
|
|
313
|
-
### Example Configurations
|
|
314
|
-
|
|
315
|
-
#### Security-Focused
|
|
316
|
-
|
|
317
|
-
```json
|
|
318
|
-
{
|
|
319
|
-
"services": ["IAM", "S3", "KMS"],
|
|
320
|
-
"ruleFilter": ["Security"],
|
|
321
|
-
"output": "markdown",
|
|
322
|
-
"withIssue": true,
|
|
323
|
-
"failOnCritical": true
|
|
324
|
-
}
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
#### Performance-Optimized
|
|
328
|
-
|
|
329
|
-
```json
|
|
330
|
-
{
|
|
331
|
-
"cache": {
|
|
332
|
-
"enabled": true,
|
|
333
|
-
"ttl": 1800000,
|
|
334
|
-
"maxSize": 3000
|
|
335
|
-
},
|
|
336
|
-
"output": "summary",
|
|
337
|
-
"summaryOnly": true
|
|
338
|
-
}
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
#### CI/CD Pipeline
|
|
342
|
-
|
|
343
|
-
```json
|
|
344
|
-
{
|
|
345
|
-
"ci": true,
|
|
346
|
-
"failOnCritical": true,
|
|
347
|
-
"output": "json",
|
|
348
|
-
"noCache": true,
|
|
349
|
-
"services": ["IAM", "S3", "Lambda"]
|
|
350
|
-
}
|
|
42
|
+
node --version # Should be 18+
|
|
43
|
+
ls cdk.json # Should exist in CDK project
|
|
351
44
|
```
|
|
352
45
|
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
```json
|
|
356
|
-
{
|
|
357
|
-
"output": "table",
|
|
358
|
-
"services": ["All"],
|
|
359
|
-
"cache": {
|
|
360
|
-
"enabled": true,
|
|
361
|
-
"ttl": 600000,
|
|
362
|
-
"maxSize": 2000
|
|
363
|
-
},
|
|
364
|
-
"synth": true
|
|
365
|
-
}
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
## π GitHub Integration
|
|
369
|
-
|
|
370
|
-
Create GitHub issues directly from your findings:
|
|
371
|
-
|
|
372
|
-
```bash
|
|
373
|
-
# Create issues for all findings (markdown output only)
|
|
374
|
-
cdk-insights scan --output markdown --with-issue
|
|
375
|
-
# or
|
|
376
|
-
npm run cdk-insights scan --withIssue
|
|
377
|
-
|
|
378
|
-
# Create issues for critical findings only
|
|
379
|
-
cdk-insights scan --output markdown --with-issue --rule-filter Security
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
> **Note**: GitHub issue creation is only available with markdown output format.
|
|
383
|
-
|
|
384
|
-
## π οΈ Available Commands
|
|
385
|
-
|
|
386
|
-
### Analysis Commands
|
|
387
|
-
|
|
388
|
-
```bash
|
|
389
|
-
# Main analysis command
|
|
390
|
-
npx cdk-insights scan [stackName] [options]
|
|
391
|
-
|
|
392
|
-
# Scan all stacks
|
|
393
|
-
npx cdk-insights scan --all
|
|
394
|
-
|
|
395
|
-
# Different output formats
|
|
396
|
-
npx cdk-insights scan --output table|json|markdown|summary
|
|
397
|
-
|
|
398
|
-
# Filter by services
|
|
399
|
-
npx cdk-insights scan --services IAM,S3,Lambda
|
|
400
|
-
|
|
401
|
-
# Create GitHub issues (markdown output only)
|
|
402
|
-
npx cdk-insights scan --output markdown --with-issue
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
### Configuration Commands
|
|
406
|
-
|
|
407
|
-
```bash
|
|
408
|
-
# List current configuration
|
|
409
|
-
npx cdk-insights config list
|
|
410
|
-
|
|
411
|
-
# Set configuration values
|
|
412
|
-
npx cdk-insights config set <key> <value>
|
|
413
|
-
|
|
414
|
-
# Remove configuration values
|
|
415
|
-
npx cdk-insights config unset <key>
|
|
416
|
-
|
|
417
|
-
# Edit configuration file
|
|
418
|
-
npx cdk-insights config edit
|
|
419
|
-
```
|
|
420
|
-
|
|
421
|
-
### Cache Commands
|
|
422
|
-
|
|
423
|
-
```bash
|
|
424
|
-
# Show cache status
|
|
425
|
-
npx cdk-insights cache-status
|
|
426
|
-
|
|
427
|
-
# Clear the cache
|
|
428
|
-
npx cdk-insights clear-cache
|
|
429
|
-
```
|
|
46
|
+
---
|
|
430
47
|
|
|
431
|
-
|
|
48
|
+
## β¨ Features β AWS CDK Security & Cost Analysis
|
|
432
49
|
|
|
433
|
-
|
|
50
|
+
- π **Static analysis** across 20+ AWS services (IAM, S3, Lambda, DynamoDB, RDS, EC2, API Gateway, and more)
|
|
51
|
+
- π€ **AI-powered recommendations** using AWS Bedrock (Pro & Enterprise tiers)
|
|
52
|
+
- π Multiple output formats: **table**, **JSON**, **Markdown**, or **summary**
|
|
53
|
+
- βοΈ **Configurable** via `.cdk-insights.json`
|
|
54
|
+
- π **GitHub integration**: create issues directly from findings
|
|
55
|
+
- π‘οΈ **Security checks** for IAM policies, S3 buckets, encryption, secrets, and more
|
|
56
|
+
- π° **Cost optimization insights** for EC2, DynamoDB, RDS, and Lambda usage
|
|
434
57
|
|
|
435
|
-
|
|
436
|
-
{
|
|
437
|
-
"cache": {
|
|
438
|
-
"enabled": true, // Enable/disable cache (default: true)
|
|
439
|
-
"ttl": 600000, // Cache TTL in milliseconds (default: 300000 = 5 minutes)
|
|
440
|
-
"maxSize": 2000 // Maximum cache entries (default: 1000)
|
|
441
|
-
}
|
|
442
|
-
}
|
|
443
|
-
```
|
|
444
|
-
|
|
445
|
-
**Cache Features:**
|
|
446
|
-
|
|
447
|
-
- **Persistent storage** across CLI sessions (non-CI environments only)
|
|
448
|
-
- **Deterministic keys** that only change when CDK code changes
|
|
449
|
-
- **Automatic invalidation** when resources are modified
|
|
450
|
-
- **Performance tracking** with hit rates and statistics
|
|
451
|
-
- **CI-safe** - no disk operations in CI environments
|
|
58
|
+
---
|
|
452
59
|
|
|
453
|
-
|
|
60
|
+
## π‘ Usage Examples for AWS CDK Projects
|
|
454
61
|
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
62
|
+
| Scenario | Command Example |
|
|
63
|
+
| ---------------------- | -------------------------------------------------------------------- |
|
|
64
|
+
| Full project scan | `npx cdk-insights scan --all --format summary` |
|
|
65
|
+
| Security-only focus | `npx cdk-insights scan --services IAM,S3,KMS --rule-filter Security` |
|
|
66
|
+
| Markdown report output | `npx cdk-insights scan --format markdown > report.md` |
|
|
67
|
+
| CI/CD pipeline check | `npx cdk-insights scan --format json --fail-on-critical` |
|
|
458
68
|
|
|
459
|
-
|
|
69
|
+
---
|
|
460
70
|
|
|
461
|
-
|
|
462
|
-
# Force fresh analysis (bypass cache)
|
|
463
|
-
npx cdk-insights scan --no-cache
|
|
464
|
-
```
|
|
71
|
+
## βοΈ Configuration & Advanced Usage
|
|
465
72
|
|
|
466
|
-
|
|
73
|
+
To set default configuration (output format, services, caching, etc.):
|
|
467
74
|
|
|
468
75
|
```bash
|
|
469
|
-
|
|
470
|
-
npx cdk-insights reset
|
|
471
|
-
|
|
472
|
-
# Setup basic cdk-nag integration (for basic static analysis)
|
|
473
|
-
npx cdk-insights setup-cdk-nag
|
|
474
|
-
|
|
475
|
-
# Install Git pre-commit hooks
|
|
476
|
-
npx cdk-insights hook
|
|
477
|
-
|
|
478
|
-
# Synthesize CDK stacks
|
|
479
|
-
npx cdk-insights synth [--path <path>]
|
|
76
|
+
npx cdk-insights config setup
|
|
480
77
|
```
|
|
481
78
|
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
### Severity Levels
|
|
485
|
-
|
|
486
|
-
- **π΄ CRITICAL**: Security vulnerabilities or major issues that need immediate attention
|
|
487
|
-
- **π‘ MEDIUM**: Issues that should be addressed soon for better security/cost
|
|
488
|
-
- **π’ LOW**: Minor optimizations and best practice recommendations
|
|
489
|
-
|
|
490
|
-
### Issue Types
|
|
491
|
-
|
|
492
|
-
- **Security**: IAM policies, encryption, access controls
|
|
493
|
-
- **Cost Optimization**: Resource sizing, unused resources, better pricing models
|
|
494
|
-
- **Performance**: Configuration that could impact speed or efficiency
|
|
495
|
-
- **Compliance**: Best practices and industry standards
|
|
496
|
-
|
|
497
|
-
## π οΈ Troubleshooting
|
|
498
|
-
|
|
499
|
-
### Common Issues
|
|
500
|
-
|
|
501
|
-
**"No stacks found"**
|
|
502
|
-
|
|
503
|
-
- Make sure you're in a CDK project directory
|
|
504
|
-
- Run `cdk synth` first to generate CloudFormation templates
|
|
505
|
-
|
|
506
|
-
**"Permission denied"**
|
|
507
|
-
|
|
508
|
-
- Ensure you have read access to your CDK project files
|
|
509
|
-
- Check that your AWS credentials are configured
|
|
510
|
-
|
|
511
|
-
**"Scan is slow"**
|
|
512
|
-
|
|
513
|
-
- Use `--services` to limit what gets scanned
|
|
514
|
-
- Try `--output summary` for faster results
|
|
79
|
+
### Enhanced Analysis via CDK Insights Aspect
|
|
515
80
|
|
|
516
|
-
|
|
81
|
+
For precise file/line metadata and richer context, add the aspect in your CDK app:
|
|
517
82
|
|
|
518
|
-
|
|
519
|
-
- Use `cdk-insights config list` to see current settings
|
|
520
|
-
- Use `cdk-insights config setup` for interactive configuration
|
|
521
|
-
- Use `cdk-insights config set <field> --help` for field-specific help
|
|
522
|
-
- Use `cdk-insights reset` to clear and start fresh
|
|
523
|
-
|
|
524
|
-
**"Invalid configuration value"**
|
|
525
|
-
|
|
526
|
-
- Use `cdk-insights config set <field> --help` to see valid values
|
|
527
|
-
- Check the [Configuration Reference](#-configuration-reference) table above
|
|
528
|
-
- Ensure boolean values are `true`/`false` (not strings)
|
|
529
|
-
- Ensure arrays are comma-separated strings or JSON arrays
|
|
530
|
-
|
|
531
|
-
**"Cache not working"**
|
|
532
|
-
|
|
533
|
-
- Check cache status with `cdk-insights cache-status`
|
|
534
|
-
- Verify cache is enabled in your configuration
|
|
535
|
-
- Use `--no-cache` flag to bypass cache for testing
|
|
536
|
-
- Clear cache with `cdk-insights clear-cache`
|
|
537
|
-
|
|
538
|
-
**"Output format issues"**
|
|
539
|
-
|
|
540
|
-
- `withIssue` only works with `markdown` output
|
|
541
|
-
- `summaryOnly` works with all output formats
|
|
542
|
-
- `table` output is best for console display
|
|
543
|
-
- `json` output is best for CI/CD integration
|
|
544
|
-
|
|
545
|
-
### Configuration Migration
|
|
546
|
-
|
|
547
|
-
If you're upgrading from an older version of CDK Insights, your configuration will be automatically migrated. Here's what changed:
|
|
548
|
-
|
|
549
|
-
**New Fields Added:**
|
|
550
|
-
|
|
551
|
-
- `failOnCritical`: Controls whether to exit with error code on critical issues
|
|
552
|
-
- `noCache`: Disable cache globally
|
|
553
|
-
- `cache`: Object with `enabled`, `ttl`, and `maxSize` properties
|
|
554
|
-
|
|
555
|
-
**Deprecated Fields:**
|
|
556
|
-
|
|
557
|
-
- None currently
|
|
558
|
-
|
|
559
|
-
**Migration Steps:**
|
|
560
|
-
|
|
561
|
-
1. Run `cdk-insights config list` to see your current configuration
|
|
562
|
-
2. Use `cdk-insights config setup` to add any new fields interactively
|
|
563
|
-
3. Test your configuration with `cdk-insights scan`
|
|
564
|
-
4. Update CI/CD scripts if using `failOnCritical: true`
|
|
565
|
-
|
|
566
|
-
### Getting Help
|
|
567
|
-
|
|
568
|
-
- **Documentation**: [docs/](docs/)
|
|
569
|
-
- **Issues**: [GitHub Issues](https://github.com/TheLeePriest/cdk-insights/issues)
|
|
570
|
-
- **Discussions**: [GitHub Discussions](https://github.com/TheLeePriest/cdk-insights/discussions)
|
|
571
|
-
|
|
572
|
-
## π§ Advanced: Enhanced Analysis with CDK Insights Aspect
|
|
573
|
-
|
|
574
|
-
> **For Advanced Users**: This section is for users who want the most detailed analysis possible. The basic scanning above works great for most use cases.
|
|
575
|
-
|
|
576
|
-
For the most detailed and accurate analysis, integrate the CDK Insights aspect into your CDK app. This provides enhanced metadata, better source location tracking, and more precise issue identification.
|
|
577
|
-
|
|
578
|
-
### Why Use the CDK Insights Aspect?
|
|
579
|
-
|
|
580
|
-
The CDK Insights aspect provides several advantages over basic CDK Nag integration:
|
|
581
|
-
|
|
582
|
-
- **π― Precise Source Location**: Pinpoints exact file, line, and column where issues occur
|
|
583
|
-
- **π Enhanced Metadata**: Captures stack names, construct types, and resource relationships
|
|
584
|
-
- **π Better Issue Mapping**: Maps CDK constructs to CloudFormation resources accurately
|
|
585
|
-
- **π Improved Analysis**: Provides richer context for AI-powered recommendations
|
|
586
|
-
- **π·οΈ Friendly Names**: Generates human-readable resource names for better reporting
|
|
587
|
-
|
|
588
|
-
### Integration Options
|
|
589
|
-
|
|
590
|
-
#### Option 1: CDK Insights Aspect (Recommended)
|
|
591
|
-
|
|
592
|
-
For the best analysis experience, use the CDK Insights aspect:
|
|
593
|
-
|
|
594
|
-
```typescript
|
|
595
|
-
// bin/app.ts
|
|
83
|
+
```ts
|
|
596
84
|
import { App, Aspects } from 'aws-cdk-lib';
|
|
597
85
|
import { CdkInsightsAspect } from 'cdk-insights';
|
|
598
86
|
|
|
599
87
|
const app = new App();
|
|
600
|
-
|
|
601
|
-
// Add CDK Insights aspect for enhanced analysis
|
|
602
88
|
Aspects.of(app).add(new CdkInsightsAspect());
|
|
603
|
-
|
|
604
|
-
// Your stacks...
|
|
89
|
+
// define stacks...
|
|
605
90
|
app.synth();
|
|
606
91
|
```
|
|
607
92
|
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
For basic static analysis without enhanced features:
|
|
611
|
-
|
|
612
|
-
```typescript
|
|
613
|
-
// bin/app.ts
|
|
614
|
-
import { App, Aspects } from 'aws-cdk-lib';
|
|
615
|
-
import { AwsSolutionsChecks } from 'cdk-nag';
|
|
616
|
-
|
|
617
|
-
const app = new App();
|
|
618
|
-
|
|
619
|
-
// Basic CDK Nag integration
|
|
620
|
-
Aspects.of(app).add(new AwsSolutionsChecks());
|
|
621
|
-
|
|
622
|
-
// Your stacks...
|
|
623
|
-
app.synth();
|
|
624
|
-
```
|
|
625
|
-
|
|
626
|
-
#### Option 3: Automated Setup
|
|
627
|
-
|
|
628
|
-
Use the CLI to automatically set up CDK Nag integration:
|
|
629
|
-
|
|
630
|
-
```bash
|
|
631
|
-
# Interactive setup (installs cdk-nag and adds to your app)
|
|
632
|
-
cdk-insights setup-cdk-nag
|
|
633
|
-
# or
|
|
634
|
-
npm run cdk-insights setup-cdk-nag
|
|
635
|
-
```
|
|
636
|
-
|
|
637
|
-
### Comparison: CDK Insights Aspect vs Basic CDK Nag
|
|
638
|
-
|
|
639
|
-
| Feature | CDK Insights Aspect | Basic CDK Nag |
|
|
640
|
-
| ---------------------- | --------------------------------- | ------------------------- |
|
|
641
|
-
| **Source Location** | β
Exact file/line/column | β No source tracking |
|
|
642
|
-
| **Stack Names** | β
Accurate stack identification | β Generic stack names |
|
|
643
|
-
| **Construct Types** | β
Precise construct mapping | β Limited type info |
|
|
644
|
-
| **Friendly Names** | β
Human-readable resource names | β Technical resource IDs |
|
|
645
|
-
| **Enhanced Metadata** | β
Rich context for analysis | β Basic issue reporting |
|
|
646
|
-
| **AI Recommendations** | β
Better context for AI analysis | β οΈ Limited context |
|
|
647
|
-
|
|
648
|
-
### Installation for Enhanced Analysis
|
|
93
|
+
---
|
|
649
94
|
|
|
650
|
-
|
|
95
|
+
## π° Plans & Pricing
|
|
651
96
|
|
|
652
|
-
|
|
653
|
-
npm install --save-dev cdk-insights
|
|
654
|
-
```
|
|
97
|
+
CDK Insights offers flexible tiers:
|
|
655
98
|
|
|
656
|
-
|
|
99
|
+
- π **Free** β Basic static scanning & essential checks
|
|
100
|
+
- π **Pro** β AI-powered insights, unlimited scanning, team features
|
|
101
|
+
- π’ **Enterprise** β Advanced compliance, unlimited usage, and dedicated support
|
|
657
102
|
|
|
658
|
-
|
|
659
|
-
// bin/app.ts
|
|
660
|
-
import { App, Aspects } from 'aws-cdk-lib';
|
|
661
|
-
import { CdkInsightsAspect } from 'cdk-insights';
|
|
103
|
+
π [View full pricing & details β](https://cdkinsights.dev/#pricing)
|
|
662
104
|
|
|
663
|
-
|
|
664
|
-
Aspects.of(app).add(new CdkInsightsAspect());
|
|
105
|
+
---
|
|
665
106
|
|
|
666
|
-
|
|
667
|
-
app.synth();
|
|
668
|
-
```
|
|
107
|
+
## π§° Requirements
|
|
669
108
|
|
|
670
|
-
|
|
109
|
+
- Node.js 18 or later
|
|
110
|
+
- AWS CDK v2 project
|
|
671
111
|
|
|
672
|
-
|
|
673
|
-
cdk synth
|
|
674
|
-
```
|
|
112
|
+
---
|
|
675
113
|
|
|
676
|
-
|
|
114
|
+
## π Links & Resources
|
|
677
115
|
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
116
|
+
- [GitHub Repository & Issues](https://github.com/TheLeePriest/cdk-insights)
|
|
117
|
+
- [Documentation](https://github.com/TheLeePriest/cdk-insights/tree/main/docs)
|
|
118
|
+
- [Pricing & Tiers](https://cdkinsights.dev/#pricing)
|
|
119
|
+
- License: MIT
|
|
681
120
|
|
|
682
|
-
|
|
121
|
+
---
|
|
683
122
|
|
|
684
|
-
|
|
123
|
+
Start with:
|
|
685
124
|
|
|
686
125
|
```bash
|
|
687
|
-
|
|
688
|
-
π Found 3 issues with enhanced metadata
|
|
689
|
-
|
|
690
|
-
βββββββββββββββ¬ββββββββββββββ¬βββββββββββ¬ββββββββββββββββββββββ¬ββββββββββββββββββ
|
|
691
|
-
β Resource β Stack β Severity β Service β Issue β
|
|
692
|
-
βββββββββββββββΌββββββββββββββΌβββββββββββΌββββββββββββββββββββββΌββββββββββββββββββ€
|
|
693
|
-
β MyFunction β MyAppStack β π΄ HIGH β Lambda β Missing VPC β
|
|
694
|
-
β MyBucket β MyAppStack β π‘ MEDIUMβ S3 β No encryption β
|
|
695
|
-
β MyRole β MyAppStack β π΄ HIGH β IAM β Wildcard policy β
|
|
696
|
-
βββββββββββββββ΄ββββββββββββββ΄βββββββββββ΄ββββββββββββββββββββββ΄ββββββββββββββββββ
|
|
697
|
-
|
|
698
|
-
π Source Locations:
|
|
699
|
-
- MyFunction: src/stacks/MyStack.ts:45:12
|
|
700
|
-
- MyBucket: src/stacks/MyStack.ts:67:8
|
|
701
|
-
- MyRole: src/stacks/MyStack.ts:23:15
|
|
126
|
+
npx cdk-insights scan
|
|
702
127
|
```
|
|
703
128
|
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
CDK Insights offers flexible plans for teams of all sizes:
|
|
707
|
-
|
|
708
|
-
- **π Free Tier**: Basic static scanning with essential security checks
|
|
709
|
-
- **π Pro Tier**: AI-powered insights, unlimited scanning, and team features
|
|
710
|
-
- **π’ Enterprise**: Advanced compliance, unlimited usage, and dedicated support
|
|
711
|
-
|
|
712
|
-
[**View all plans and pricing β**](https://cdkinsights.dev/#pricing)
|
|
713
|
-
|
|
714
|
-
## π License
|
|
715
|
-
|
|
716
|
-
CDK Insights is licensed under the MIT License. Some functionality integrates with cdk-nag, which is licensed under Apache License 2.0.
|
|
717
|
-
|
|
718
|
-
---
|
|
719
|
-
|
|
720
|
-
**Ready to improve your CDK infrastructure?** Start with `npx cdk-insights scan` and discover what insights await!
|
|
721
|
-
|
|
722
|
-
> π‘ **Pro tip**: Add the convenience scripts to your `package.json` (see above) for shorter commands like `npm run scan` π
|
|
129
|
+
And explore outputs, configuration, and integrations from there. π
|