cdk-insights/README.md

AWS CDK security and cost analysis tool with AI-powered insights

# 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**.  
Unlike tools like **cdk-nag**, CDK Insights adds **AI-powered recommendations** for smarter cloud infrastructure improvements.

👉 Learn more at [cdkinsights.dev](https://cdkinsights.dev)

---

## 🚀 Quick Start

```bash
# Try it immediately without installing
npx cdk-insights scan

# Or install in your project
npm install --save-dev cdk-insights
npx cdk-insights scan
```

### Development Setup

For contributors, git hooks are automatically installed via Husky when you run:

```bash
npm install
```

The hooks will:

- **Pre-commit**: Prompt for version bump and update changelog
- **Pre-push**: Run tests before pushing
- **Commit-msg**: Validate commit message format

You can also add convenience scripts to your `package.json`:

```json
{
  "scripts": {
    "scan": "cdk-insights scan",
    "scan:all": "cdk-insights scan --all",
    "scan:json": "cdk-insights scan --format json",
    "scan:markdown": "cdk-insights scan --format markdown",
    "scan:summary": "cdk-insights scan --format summary",
    "scan:with-issue": "cdk-insights scan --withIssue"
  }
}
```

Then run: `npm run scan`

### Quick Compatibility Check

```bash
node --version  # Should be 18+
ls cdk.json     # Should exist in CDK project
```

---

## ✨ Features — AWS CDK Security & Cost Analysis

- 🔍 **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

---

## 💡 Usage Examples for AWS CDK Projects

| Scenario               | Command Example                                                      |
| ---------------------- | -------------------------------------------------------------------- |
| Full project scan      | `npx cdk-insights scan --all --format summary`                       |
| Security-only focus    | `npx cdk-insights scan --services IAM,S3,KMS --rule-filter Security` |
| Markdown report output | `npx cdk-insights scan --format markdown > report.md`                |
| CI/CD pipeline check   | `npx cdk-insights scan --format json --fail-on-critical`             |

---

## ⚙️ Configuration & Advanced Usage

To set default configuration (output format, services, caching, etc.):

```bash
npx cdk-insights config setup
```

### Enhanced Analysis via CDK Insights Aspect

For precise file/line metadata and richer context, add the aspect in your CDK app:

```ts
import { App, Aspects } from 'aws-cdk-lib';
import { CdkInsightsAspect } from 'cdk-insights';

const app = new App();
Aspects.of(app).add(new CdkInsightsAspect());
// define stacks...
app.synth();
```

---

## 💰 Plans & Pricing

CDK Insights offers flexible tiers:

- 🆓 **Free** — Basic static scanning & essential checks
- 🚀 **Pro** — AI-powered insights, unlimited scanning, team features
- 🏢 **Enterprise** — Advanced compliance, unlimited usage, and dedicated support

👉 [View full pricing & details →](https://cdkinsights.dev/#pricing)

---

## 🧰 Requirements

- Node.js 18 or later
- AWS CDK v2 project

---

## 📚 Links & Resources

- [GitHub Repository & Issues](https://github.com/TheLeePriest/cdk-insights)
- [Documentation](https://github.com/TheLeePriest/cdk-insights/tree/main/docs)
- [Pricing & Tiers](https://cdkinsights.dev/#pricing)
- License: MIT

---

Start with:

```bash
npx cdk-insights scan
```

And explore outputs, configuration, and integrations from there. 🚀