@aws/nx-plugin 0.1.6 → 0.2.0

package/src/infra/app/README.md

@@ -1,7 +1,8 @@
 # Infrastructure App Generator
 
 ## Overview
-This generator creates a new AWS CDK infrastructure application. The generated application includes security best practices through PDK Nag checks and provides infrastructure visualization. The codebase is structured using TypeScript and ES Modules (ESM) for modern development practices.
+
+This generator creates a new AWS CDK infrastructure application. The generated application includes security best practices through CFN guard checks. The codebase is structured using TypeScript and ES Modules (ESM) for modern development practices.
 
 ## Usage
 
@@ -10,12 +11,14 @@ You can generate a new infrastructure application in two ways:
 ### 1. Using VSCode IDE
 
 First, install the NX Console extension for VSCode:
+
 1. Open VSCode
 2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
 3. Search for "Nx Console"
 4. Install [Nx Console](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console)
 
 Then generate your application:
+
 1. Open the NX Console in VSCode
 2. Click on "Generate"
 3. Search for "infra#app"
@@ -25,33 +28,38 @@ Then generate your application:
 ### 2. Using CLI
 
 Generate the application:
+
 ```bash
 nx g @aws/nx-plugin:infra#app my-infra --directory=apps/infrastructure
 ```
 
 You can also perform a dry-run to see what files would be generated without actually creating them:
+
 ```bash
 nx g @aws/nx-plugin:infra#app my-infra --directory=apps/infrastructure --dry-run
 ```
 
 ## Input Parameters
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| name* | string | - | The name of the application (required). Must start with a letter and not contain colons. |
-| directory | string | "packages" | The directory to store the application in. |
-| unitTestRunner | string | "vitest" | Test runner for unit tests. Options: jest, vitest, none |
+| Parameter      | Type   | Default         | Description                                                                              |
+| -------------- | ------ | --------------- | ---------------------------------------------------------------------------------------- |
+| name\*         | string | -               | The name of the application (required). Must start with a letter and not contain colons. |
+| ruleSet\*      | string | aws_prototyping | cfn guard ruleset to use                                                                 |
+| directory      | string | "packages"      | The directory to store the application in.                                               |
+| unitTestRunner | string | "vitest"        | Test runner for unit tests. Options: jest, vitest, none                                  |
 
-*Required parameter
+\*Required parameter
 
 ## Expected Output
 
-The generator creates an infrastructure application with the following structure:
+The generator creates two main components:
+
+### 1. Infra app code
 
 ```
 <directory>/<name>/
 ├── src/
-│   ├── main.ts           # Application entry point with CDK and PDK setup
+│   └── main.ts           # Application entry point with CDK and PDK setup
 │   └── stacks/          # CDK stack definitions
 │       └── application-stack.ts  # Main application stack
 ├── cdk.json            # CDK configuration
@@ -59,12 +67,24 @@ The generator creates an infrastructure application with the following structure
 └── project.json       # Project configuration and build targets
 ```
 
+### 2. Infra library code
+
+```
+common/constructs
+    └── src
+        └── core
+            └── cfn-guard.ts      # Provides a wrapper around @cdklabs/cdk-validator-cfnguard along with a suppressRule function
+            └── cfn-guard-rules
+                └── *.guard       # cfn guard ruleset definitions
+```
+
 Additionally, it:
+
 1. Configures build settings for CDK synthesis and deployment
 2. Installs required dependencies:
-   - @aws/pdk
    - aws-cdk-lib
    - aws-cdk
+   - @cdklabs/cdk-validator-cfnguard
    - constructs
    - esbuild
    - source-map-support
@@ -72,42 +92,24 @@ Additionally, it:
 
 ## Features
 
-### 1. PDK Integration
-The generated application includes PDK (Project Development Kit) integration which provides:
-- Security best practices through PDK Nag checks
-- Infrastructure visualization with CDK Graph
-- Threat modeling capabilities through Threat Composer
+### 1. Cfn Guard integration
 
-### 2. Infrastructure Visualization
-The application automatically generates infrastructure diagrams using CDK Graph:
-```typescript
-const graph = new CdkGraph(app, {
-  plugins: [
-    new CdkGraphDiagramPlugin({
-      defaults: {
-        filterPlan: {
-          preset: FilterPreset.COMPACT,
-          filters: [{ store: Filters.pruneCustomResources() }],
-        },
-      },
-    }),
-    new CdkGraphThreatComposerPlugin(),
-  ],
-});
-```
+The generated application includes Cfn guard integration which ensures security best practices via automated policy checks.
 
-### 3. Security Checks
-PDK Nag is configured with AWS Prototyping Checks to ensure infrastructure security:
 ```typescript
-const app = PDKNag.app({
-  nagPacks: [new AwsPrototypingChecks()],
+import { CfnGuardValidator, RuleSet } from ':e2e-test/common-constructs';
+
+const app = new App({
+  policyValidationBeta1: [new CfnGuardValidator(RuleSet.AWS_PROTOTYPING)],
 });
 ```
 
-### 4. Build and Deploy Targets
+### 2. Build and Deploy Targets
+
 The generator configures two main targets in your project.json:
 
 1. **Build Target**
+
    - Synthesizes CDK templates
    - Caches results for faster subsequent builds
    - Outputs to `dist/<directory>/cdk.out`
@@ -126,19 +128,17 @@ Add AWS resources to your stack in `src/stacks/application-stack.ts`:
 ```typescript
 import * as cdk from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { UserIdentity, StaticWebsite, MyApi } from ':my-org/common-constructs'
-import { HttpIamAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2-authorizers';
+/* Replace MyWebsite and MyApi with whatever you called them */
+import { UserIdentity, MyWebsite, MyApi } from ':my-org/common-constructs';
 
 export class ApplicationStack extends cdk.Stack {
   constructor(scope: Construct, id: string, props?: cdk.StackProps) {
     super(scope, id, props);
 
     const identity = new UserIdentity(this, 'UserIdentity');
-    const myapi = new MyApi(this, 'MyApi', {
-      defaultAuthorizer: new HttpIamAuthorizer(),
-    });
+    const myapi = new MyApi(this, 'MyApi');
     myapi.grantInvokeAccess(identity.identityPool.authenticatedRole);
-    new StaticWebsite(this, 'Website');
+    new MyWebsite(this, 'Website');
   }
 }
 ```
@@ -148,14 +148,15 @@ The generated code serves as a starting point that you can adapt to your specifi
 ### Building the Application
 
 To create a production build:
+
 ```bash
 nx build my-infra
 ```
 
 All built code is located in the `dist` folder at the root of your workspace. For example, if your infrastructure application is in `apps/infrastructure/my-infra`, the built code will be in `dist/apps/infrastructure/my-infra`. This includes:
+
 - Compiled TypeScript files
 - CDK synthesized templates in `dist/apps/infrastructure/my-infra/cdk.out`
-- Generated infrastructure diagrams
 - Source maps for debugging
 
 ### Deploying to AWS
@@ -163,7 +164,7 @@ All built code is located in the `dist` folder at the root of your workspace. Fo
 To deploy your infrastructure:
 
 ```bash
-nx deploy my-infra
+nx deploy my-infra --all
 ```
 
 This command will deploy your infrastructure to AWS using the account and region configured in your AWS CLI.
@@ -172,4 +173,28 @@ You can also perform a hotswap deployment if you are only making modifications t
 
 ```bash
 nx deploy my-infra --hotswap
-```
+```
+
+### Cfn Guard Suppressions
+
+There may be instances where you want to suppress certain rules on resources. You can do this in two ways:
+
+#### Supress a rule on a given construct
+
+```typescript
+import { suppressRule } from ':my-org/common-constructs';
+
+...
+// suppresses the RULE_NAME for the given construct.
+suppressRule(construct, 'RULE_NAME');
+```
+
+#### Supress a rule on a descendant construct
+
+```typescript
+import { suppressRule } from ':my-org/common-constructs';
+
+...
+// Supresses the RULE_NAME for the construct or any of its descendants if it is an instance of Bucket
+suppressRule(construct, 'RULE_NAME', (construct) => construct instanceof Bucket);
+```