vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/aws-cdk/references/bootstrap-and-project-setup.md

@@ -0,0 +1,257 @@
+# Bootstrap and Project Setup Reference
+
+## Table of Contents
+
+- [Bootstrap and Project Setup Reference](#bootstrap-and-project-setup-reference)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Bootstrap Procedure](#bootstrap-procedure)
+    - [What Bootstrap Creates](#what-bootstrap-creates)
+    - [Bootstrap Command](#bootstrap-command)
+    - [Cross-Account Trust](#cross-account-trust)
+    - [Custom Qualifier](#custom-qualifier)
+    - [Permissions Boundary](#permissions-boundary)
+    - [Custom Bootstrap Template](#custom-bootstrap-template)
+    - [Bootstrap Constraints](#bootstrap-constraints)
+  - [TypeScript Project Setup](#typescript-project-setup)
+    - [Prerequisites](#prerequisites)
+    - [Initialize Project](#initialize-project)
+    - [Project Structure](#project-structure)
+    - [Configure tsx](#configure-tsx)
+    - [Linting](#linting)
+    - [Common Commands](#common-commands)
+  - [Python Project Setup](#python-project-setup)
+    - [Prerequisites](#prerequisites-1)
+    - [Initialize Project](#initialize-project-1)
+    - [Virtual Environment](#virtual-environment)
+    - [Common Commands](#common-commands-1)
+  - [Version Management Best Practices](#version-management-best-practices)
+    - [CLI and Library Are Separate Release Tracks](#cli-and-library-are-separate-release-tracks)
+    - [Feature Flags](#feature-flags)
+
+---
+
+## Overview
+
+Every CDK deployment target (account + region pair) MUST be bootstrapped before the first
+deployment. Projects MUST commit a lockfile and SHOULD use strict tooling to ensure reproducible builds.
+
+---
+
+## Bootstrap Procedure
+
+### What Bootstrap Creates
+
+The `CDKToolkit` CloudFormation stack provisions:
+
+- An S3 bucket (file assets and CloudFormation templates)
+- An ECR repository (Docker image assets)
+- 4 IAM roles for user to assume (deploy, lookup, file-publishing, image-publishing)
+- A CloudFormation execution role
+- An SSM parameter (`/cdk-bootstrap/$QUALIFIER/version`)
+
+### Bootstrap Command
+
+```bash
+cdk bootstrap aws://$ACCOUNT_ID/$REGION
+```
+
+Bootstrap REQUIRES near-administrator permissions in the target account.
+
+### Cross-Account Trust
+
+To allow a CI/CD account to deploy into a target account:
+
+```bash
+cdk bootstrap aws://$TARGET_ACCOUNT/$REGION \
+  --trust $CI_ACCOUNT_ID \
+  --cloudformation-execution-policies arn:aws:iam::aws:policy/$POLICY_NAME
+```
+
+The `--trust` flag grants the specified account permission to assume the CDK roles.
+The `--cloudformation-execution-policies` flag MUST be provided with `--trust` to
+scope the CloudFormation execution role.
+
+### Custom Qualifier
+
+To run multiple independent CDK environments in the same account/region:
+
+```bash
+cdk bootstrap aws://$ACCOUNT_ID/$REGION --qualifier $QUALIFIER
+```
+
+The qualifier MUST be alphanumeric and at most 10 characters. It distinguishes
+bootstrap resources from other CDK environments in the same account.
+
+### Permissions Boundary
+
+To attach a permissions boundary to all IAM roles created by CDK:
+
+```bash
+cdk bootstrap aws://$ACCOUNT_ID/$REGION \
+  --custom-permissions-boundary $BOUNDARY_POLICY_NAME
+```
+
+### Custom Bootstrap Template
+
+To use an organization-approved bootstrap template:
+
+```bash
+cdk bootstrap aws://$ACCOUNT_ID/$REGION --template $TEMPLATE_PATH
+```
+
+### Bootstrap Constraints
+
+- Deleting the `CDKToolkit` stack MUST NOT be done — it breaks all deployments
+  in that account/region pair.
+- Termination protection SHOULD be enabled on the `CDKToolkit` stack.
+- Bootstrap MUST be re-run when upgrading to a CDK version that requires a newer
+  bootstrap stack version.
+
+---
+
+## TypeScript Project Setup
+
+### Prerequisites
+
+- Node.js ≥ 20 MUST be installed.
+
+### Initialize Project
+
+```bash
+cdk init app --language typescript
+```
+
+### Project Structure
+
+```
+$PROJECT_ROOT/
+├── bin/          # Entry point (App instantiation)
+├── lib/          # Stack and construct definitions
+├── cdk.json      # CDK configuration
+├── package.json
+└── tsconfig.json
+```
+
+### Configure tsx
+
+The `cdk.json` `app` field SHOULD use `tsx` instead of `ts-node` for faster startup:
+
+```json
+{
+  "app": "npx tsx bin/$APP_NAME.ts"
+}
+```
+
+### Linting
+
+Projects MUST enforce strict typing — `any` MUST NOT be used. Configure with:
+
+- `eslint` + `prettier`
+- `eslint-plugin-awscdk` for CDK-specific rules
+
+Construct props interfaces SHOULD use `readonly` on all properties:
+
+```typescript
+interface MyConstructProps {
+  readonly bucketName: string;
+  readonly enableVersioning: boolean;
+}
+```
+
+### Common Commands
+
+```bash
+cdk synth          # Synthesize CloudFormation template
+cdk diff           # Show pending changes
+cdk deploy         # Deploy stack(s)
+cdk destroy        # Tear down stack(s)
+cdk list           # List all stacks in the app
+```
+
+---
+
+## Python Project Setup
+
+### Prerequisites
+
+- Node.js ≥ 20 MUST be installed.
+- Python ≥ 3.9 MUST be installed.
+
+### Initialize Project
+
+```bash
+cdk init app --language python
+```
+
+### Virtual Environment
+
+After initialization, activate the virtualenv and install dependencies:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Dependencies SHOULD be captured in `requirements.txt` (or `poetry.lock` / `Pipfile.lock`) and committed for reproducible builds. See [Version Management Best Practices](#version-management-best-practices).
+
+### Common Commands
+
+```bash
+cdk synth           # Synthesize CloudFormation template
+cdk deploy          # Deploy stack(s)
+cdk bootstrap       # Bootstrap target environment
+cdk doctor          # Check for potential problems
+```
+
+---
+
+## Version Management Best Practices
+
+- **Commit lockfiles** (`package-lock.json` / `poetry.lock` / `Pipfile.lock`). Unlocked builds drift and lose determinism.
+- **For CDK applications**, use **caret (`^`) ranges** for `aws-cdk-lib` and `constructs` in `dependencies` — this is the officially recommended approach. The lockfile provides reproducibility; the caret range lets `npm update` pull compatible fixes and features.
+
+  ```json
+  {
+    "dependencies": {
+      "aws-cdk-lib": "^2.170.0",
+      "constructs": "^10.5.0"
+    }
+  }
+  ```
+
+  Teams that prefer exact pinning for stricter reproducibility SHOULD pair it with automated upgrade tooling (Dependabot, Renovate) to avoid falling behind.
+- **For construct libraries**, declare `aws-cdk-lib` and `constructs` as `peerDependencies` (caret, widest compatible) and as `devDependencies` at the oldest supported exact version.
+- **Experimental / alpha modules** (e.g. `@aws-cdk/aws-*-alpha`) SHOULD use exact versions — their APIs can change between releases without SemVer guarantees.
+- **Automate upgrades**: a weekly job that bumps `aws-cdk-lib`, runs `cdk synth` to catch breaking changes, deploys to a test environment, and opens a PR on success.
+
+### CLI and Library Are Separate Release Tracks
+
+The CDK CLI (`aws-cdk`) and the library (`aws-cdk-lib`) are **independent packages on different release tracks — their version numbers do NOT align**. A CLI at `2.1001.x` paired with a library at `2.200.x` is normal. The compatibility contract is one-way: a newer CLI can read assemblies produced by older libraries, but an older CLI CANNOT read assemblies produced by newer libraries. The mismatch surfaces as:
+
+```
+This CDK CLI is not compatible with the CDK library used by your application.
+(Cloud assembly schema version mismatch)
+```
+
+The fix is to upgrade the CLI to a specific newer version. You MUST install `aws-cdk` as a dev dependency at an **exact** version and invoke it via `npx cdk`; you MUST NOT use `aws-cdk@latest` anywhere — it is non-deterministic, so a broken release can reach your pipeline instantly.
+
+```json
+{
+  "devDependencies": {
+    "aws-cdk": "2.1010.0"
+  }
+}
+```
+
+```bash
+npx cdk synth
+npx cdk deploy $STACK_NAME
+```
+
+Bump the pinned CLI version regularly (Dependabot / Renovate), on the same cadence as `aws-cdk-lib`.
+
+### Feature Flags
+
+`cdk.json`'s `context` object carries CDK feature flags — per-release opt-ins to behaviour changes. When upgrading `aws-cdk-lib`, review new flags and adopt them incrementally (inspect via `cdk flags --unstable=flags`). Do not flip everything to recommended in one commit.

package/dist/global-skills/aws-cdk/references/compliance-and-drift.md

@@ -0,0 +1,193 @@
+# Compliance and Drift Reference
+
+## Table of Contents
+
+- [Overview](#overview)
+- [cdk-nag Setup and Rule Packs](#cdk-nag-setup-and-rule-packs)
+  - [Installation](#installation)
+  - [Available Rule Packs](#available-rule-packs)
+  - [Applying Rule Packs](#applying-rule-packs)
+- [Suppression Patterns](#suppression-patterns)
+- [Drift Detection](#drift-detection)
+  - [cdk drift vs cdk diff](#cdk-drift-vs-cdk-diff)
+  - [Running Drift Detection](#running-drift-detection)
+- [Drift Resolution Strategies](#drift-resolution-strategies)
+- [CI Integration](#ci-integration)
+  - [Strict Mode](#strict-mode)
+  - [cdk-nag in CI](#cdk-nag-in-ci)
+  - [Drift in CI](#drift-in-ci)
+  - [Security Scanning Layers](#security-scanning-layers)
+  - [Strict Mode Rollout](#strict-mode-rollout)
+
+---
+
+## Overview
+
+CDK applications MUST be scanned for compliance violations before deployment and
+monitored for drift after deployment. `cdk-nag` provides compile-time policy
+enforcement. `cdk drift` detects runtime configuration changes made outside CDK.
+
+---
+
+## cdk-nag Setup and Rule Packs
+
+### Installation
+
+```bash
+npm install cdk-nag
+```
+
+cdk-nag MUST be wired in before the first deploy to prevent non-compliant
+resources from ever reaching production.
+
+### Available Rule Packs
+
+| Rule Pack               | Use Case                                    |
+|-------------------------|---------------------------------------------|
+| `AwsSolutionsChecks`    | General AWS best practices                  |
+| `HIPAASecurityChecks`   | HIPAA compliance                            |
+| `NIST80053R5Checks`     | NIST 800-53 Rev 5 compliance                |
+| `PCIDSS321Checks`       | PCI DSS 3.2.1 compliance                    |
+
+For SOX compliance, apply both `NIST80053R5Checks` and `AwsSolutionsChecks` together.
+
+### Applying Rule Packs
+
+Rule packs are applied as CDK Aspects:
+
+```typescript
+import { Aspects } from 'aws-cdk-lib';
+import { AwsSolutionsChecks } from 'cdk-nag';
+
+Aspects.of($APP).add(new AwsSolutionsChecks());
+```
+
+Multiple rule packs MAY be applied simultaneously:
+
+```typescript
+Aspects.of($APP).add(new AwsSolutionsChecks());
+Aspects.of($APP).add(new NIST80053R5Checks());
+```
+
+---
+
+## Suppression Patterns
+
+When a finding is intentionally accepted, suppress it with
+`NagSuppressions.addResourceSuppressions()`. Every suppression MUST include a
+documented reason:
+
+```typescript
+import { NagSuppressions } from 'cdk-nag';
+
+NagSuppressions.addResourceSuppressions($CONSTRUCT, [
+  {
+    id: '$RULE_ID',
+    reason: '$DOCUMENTED_JUSTIFICATION',
+  },
+]);
+```
+
+Suppressions MUST NOT be used to bypass findings without genuine justification.
+
+---
+
+## Drift Detection
+
+### cdk drift vs cdk diff
+
+- `cdk diff` compares the local CDK app against the **last deployed template**.
+  It shows what a new deployment would change.
+- `cdk drift` compares the **deployed template** against the **actual live
+  resource state**. It shows out-of-band changes made outside CDK.
+
+### Running Drift Detection
+
+Single stack:
+
+```bash
+cdk drift $STACK_NAME
+```
+
+All stacks:
+
+```bash
+cdk drift
+```
+
+---
+
+## Drift Resolution Strategies
+
+When drift is detected, resolve it using one of these approaches (in order of
+preference):
+
+1. **Redeploy** — Run `cdk deploy $STACK_NAME` to overwrite the drifted state
+   with the CDK-defined state. This is the simplest resolution.
+
+2. **Adopt the change** — If the out-of-band change is desired, update the CDK
+   code to match the live state using `Cfn<Resource>PropsMixin` to adopt the drifted
+   property values.
+
+3. **Fallback overrides** — If `Cfn<Resource>PropsMixin` is not available for the
+   resource type, use `addPropertyOverride` or `node.defaultChild` to set the
+   property at the L1 level.
+
+4. **Handle deleted resources** — If a resource was deleted outside CDK,
+   remove it from the CDK code or re-import it.
+
+Drift SHOULD be prevented proactively using SCPs (Service Control Policies) that
+restrict manual changes to CDK-managed resources.
+
+---
+
+## CI Integration
+
+### Strict Mode
+
+`--strict` MUST be passed on every `cdk synth` and `cdk deploy` in CI. Strict
+mode promotes warnings to build failures:
+
+```bash
+npx cdk synth --strict
+npx cdk deploy $STACK_NAME --strict
+```
+
+Pair `--strict` with cdk-nag to catch both CDK warnings and compliance violations.
+
+### cdk-nag in CI
+
+cdk-nag MUST be enforced in CI pipelines. Because rule packs are applied as
+Aspects, `cdk synth` will fail if any violations are found (when using
+`--strict`), blocking the deployment.
+
+cdk-nag scans for:
+
+- Over-permissive IAM policies
+- Open security groups
+- Unencrypted resources
+- Missing logging
+
+### Drift in CI
+
+Automate drift detection in CI with the `--fail` flag:
+
+```bash
+cdk drift --fail
+```
+
+This exits with a non-zero code when drift is detected, failing the pipeline.
+
+### Security Scanning Layers
+
+1. Wire cdk-nag first as the primary compliance layer.
+2. Add Checkov as a second scanning layer for additional coverage.
+
+### Strict Mode Rollout
+
+To adopt `--strict` incrementally on an existing project:
+
+1. Collect current warnings with `cdk synth`.
+2. Triage each warning — determine if it is a real issue or acceptable.
+3. Fix genuine issues; suppress accepted findings with `NagSuppressions`.
+4. Enable `--strict` in CI once all warnings are resolved or suppressed.