@Stability(Stable)

Package io.github.cdklabs.cdknag

cdk-nag

Check CDK applications or CloudFormation templates for best practices using a combination of available rule packs. Inspired by cfn_nag.

Check out this blog post for a guided overview!

Available Rules and Packs

See RULES for more information on all the available packs.

1. AWS Solutions
2. HIPAA Security
3. NIST 800-53 rev 4
4. NIST 800-53 rev 5
5. PCI DSS 3.2.1

RULES also includes a collection of additional rules that are not currently included in any of the pre-built NagPacks, but are still available for inclusion in custom NagPacks.

Read the NagPack developer docs if you are interested in creating your own pack.

Usage

For a full list of options See NagPackProps in the API.md

Including in an application

 import { App, Aspects } from 'aws-cdk-lib';
 import { CdkTestStack } from '../lib/cdk-test-stack';
 import { AwsSolutionsChecks } from 'cdk-nag';
 
 const app = new App();
 new CdkTestStack(app, 'CdkNagDemo');
 // Simple rule informational messages
 Aspects.of(app).add(new AwsSolutionsChecks());
 // Additional explanations on the purpose of triggered rules
 // Aspects.of(stack).add(new AwsSolutionsChecks({ verbose: true }));
 

Suppressing a Rule

Example 1) Default Construct

 import { SecurityGroup, Vpc, Peer, Port } from 'aws-cdk-lib/aws-ec2';
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { NagSuppressions } from 'cdk-nag';
 
 export class CdkTestStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
     const test = new SecurityGroup(this, 'test', {
       vpc: new Vpc(this, 'vpc'),
     });
     test.addIngressRule(Peer.anyIpv4(), Port.allTraffic());
     NagSuppressions.addResourceSuppressions(test, [
       { id: 'AwsSolutions-EC23', reason: 'lorem ipsum' },
     ]);
   }
 }
 

Example 2) On Multiple Constructs

 import { SecurityGroup, Vpc, Peer, Port } from 'aws-cdk-lib/aws-ec2';
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { NagSuppressions } from 'cdk-nag';
 
 export class CdkTestStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
     const vpc = new Vpc(this, 'vpc');
     const test1 = new SecurityGroup(this, 'test', { vpc });
     test1.addIngressRule(Peer.anyIpv4(), Port.allTraffic());
     const test2 = new SecurityGroup(this, 'test', { vpc });
     test2.addIngressRule(Peer.anyIpv4(), Port.allTraffic());
     NagSuppressions.addResourceSuppressions(
       [test1, test2],
       [{ id: 'AwsSolutions-EC23', reason: 'lorem ipsum' }]
     );
   }
 }
 

Example 3) Child Constructs

 import { User, PolicyStatement } from 'aws-cdk-lib/aws-iam';
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { NagSuppressions } from 'cdk-nag';
 
 export class CdkTestStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
     const user = new User(this, 'rUser');
     user.addToPolicy(
       new PolicyStatement({
         actions: ['s3:PutObject'],
         resources: ['arn:aws:s3:::bucket_name/*'],
       })
     );
     // Enable adding suppressions to child constructs
     NagSuppressions.addResourceSuppressions(
       user,
       [
         {
           id: 'AwsSolutions-IAM5',
           reason: 'lorem ipsum',
           appliesTo: ['Resource::arn:aws:s3:::bucket_name/*'], // optional
         },
       ],
       true
     );
   }
 }
 

Example 4) Stack Level

 import { App, Aspects } from 'aws-cdk-lib';
 import { CdkTestStack } from '../lib/cdk-test-stack';
 import { AwsSolutionsChecks, NagSuppressions } from 'cdk-nag';
 
 const app = new App();
 const stack = new CdkTestStack(app, 'CdkNagDemo');
 Aspects.of(app).add(new AwsSolutionsChecks());
 NagSuppressions.addStackSuppressions(stack, [
   { id: 'AwsSolutions-EC23', reason: 'lorem ipsum' },
 ]);
 

Example 5) Construct path

If you received the following error on synth/deploy

 [Error at /StackName/Custom::CDKBucketDeployment8675309/ServiceRole/Resource] AwsSolutions-IAM4: The IAM user, role, or group uses AWS managed policies
 

 import { Bucket } from 'aws-cdk-lib/aws-s3';
 import { BucketDeployment } from 'aws-cdk-lib/aws-s3-deployment';
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { NagSuppressions } from 'cdk-nag';
 
 export class CdkTestStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
     new BucketDeployment(this, 'rDeployment', {
       sources: [],
       destinationBucket: Bucket.fromBucketName(this, 'rBucket', 'foo'),
     });
     NagSuppressions.addResourceSuppressionsByPath(
       this,
       '/StackName/Custom::CDKBucketDeployment8675309/ServiceRole/Resource',
       [{ id: 'AwsSolutions-IAM4', reason: 'at least 10 characters' }]
     );
   }
 }
 

Example 6) Granular Suppressions of findings

Certain rules support granular suppressions of findings. If you received the following errors on synth/deploy

 [Error at /StackName/rFirstUser/DefaultPolicy/Resource] AwsSolutions-IAM5[Action::s3:*]: The IAM entity contains wildcard permissions and does not have a cdk-nag rule suppression with evidence for those permission.
 [Error at /StackName/rFirstUser/DefaultPolicy/Resource] AwsSolutions-IAM5[Resource::*]: The IAM entity contains wildcard permissions and does not have a cdk-nag rule suppression with evidence for those permission.
 [Error at /StackName/rSecondUser/DefaultPolicy/Resource] AwsSolutions-IAM5[Action::s3:*]: The IAM entity contains wildcard permissions and does not have a cdk-nag rule suppression with evidence for those permission.
 [Error at /StackName/rSecondUser/DefaultPolicy/Resource] AwsSolutions-IAM5[Resource::*]: The IAM entity contains wildcard permissions and does not have a cdk-nag rule suppression with evidence for those permission.
 

By applying the following suppressions

 import { User } from 'aws-cdk-lib/aws-iam';
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { NagSuppressions } from 'cdk-nag';
 
 export class CdkTestStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
     const firstUser = new User(this, 'rFirstUser');
     firstUser.addToPolicy(
       new PolicyStatement({
         actions: ['s3:*'],
         resources: ['*'],
       })
     );
     const secondUser = new User(this, 'rSecondUser');
     secondUser.addToPolicy(
       new PolicyStatement({
         actions: ['s3:*'],
         resources: ['*'],
       })
     );
     const thirdUser = new User(this, 'rSecondUser');
     thirdUser.addToPolicy(
       new PolicyStatement({
         actions: ['sqs:CreateQueue'],
         resources: [`arn:aws:sqs:${this.region}:${this.account}:*`],
       })
     );
     NagSuppressions.addResourceSuppressions(
       firstUser,
       [
         {
           id: 'AwsSolutions-IAM5',
           reason:
             "Only suppress AwsSolutions-IAM5 's3:*' finding on First User.",
           appliesTo: ['Action::s3:*'],
         },
       ],
       true
     );
     NagSuppressions.addResourceSuppressions(
       secondUser,
       [
         {
           id: 'AwsSolutions-IAM5',
           reason: 'Suppress all AwsSolutions-IAM5 findings on Second User.',
         },
       ],
       true
     );
     NagSuppressions.addResourceSuppressions(
       thirdUser,
       [
         {
           id: 'AwsSolutions-IAM5',
           reason: 'Suppress AwsSolutions-IAM5 on the SQS resource.',
           appliesTo: [
             {
               regex: '/^Resource::arn:aws:sqs:(.*):\\*$/g',
             },
           ],
         },
       ],
       true
     );
   }
 }
 

You would see the following error on synth/deploy

 [Error at /StackName/rFirstUser/DefaultPolicy/Resource] AwsSolutions-IAM5[Resource::*]: The IAM entity contains wildcard permissions and does not have a cdk-nag rule suppression with evidence for those permission.
 

Suppressing aws-cdk-lib/pipelines Violations

The aws-cdk-lib/pipelines.CodePipeline construct and its child constructs are not guaranteed to be "Visited" by Aspects, as they are not added during the "Construction" phase of the cdk lifecycle. Because of this behavior, you may experience problems such as rule violations not appearing or the inability to suppress violations on these constructs.

You can remediate these rule violation and suppression problems by forcing the pipeline construct creation forward by calling .buildPipeline() on your CodePipeline object. Otherwise you may see errors such as:

 Error: Suppression path "/this/construct/path" did not match any resource. This can occur when a resource does not exist or if a suppression is applied before a resource is created.
 

See this issue for more information.

Example) Suppressing Violations in Pipelines

example-app.ts

 import { App, Aspects } from 'aws-cdk-lib';
 import { AwsSolutionsChecks } from 'cdk-nag';
 import { ExamplePipeline } from '../lib/example-pipeline';
 
 const app = new App();
 new ExamplePipeline(app, 'example-cdk-pipeline');
 Aspects.of(app).add(new AwsSolutionsChecks({ verbose: true }));
 app.synth();
 

example-pipeline.ts

 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Repository } from 'aws-cdk-lib/aws-codecommit';
 import {
   CodePipeline,
   CodePipelineSource,
   ShellStep,
 } from 'aws-cdk-lib/pipelines';
 import { NagSuppressions } from 'cdk-nag';
 import { Construct } from 'constructs';
 
 export class ExamplePipeline extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
 
     const exampleSynth = new ShellStep('ExampleSynth', {
       commands: ['yarn build --frozen-lockfile'],
       input: CodePipelineSource.codeCommit(
         new Repository(this, 'ExampleRepo', { repositoryName: 'ExampleRepo' }),
         'main'
       ),
     });
 
     const ExamplePipeline = new CodePipeline(this, 'ExamplePipeline', {
       synth: exampleSynth,
     });
 
     // Force the pipeline construct creation forward before applying suppressions.
     // @See https://github.com/aws/aws-cdk/issues/18440
     ExamplePipeline.buildPipeline();
 
     // The path suppression will error if you comment out "ExamplePipeline.buildPipeline();""
     NagSuppressions.addResourceSuppressionsByPath(
       this,
       '/example-cdk-pipeline/ExamplePipeline/Pipeline/ArtifactsBucket/Resource',
       [
         {
           id: 'AwsSolutions-S1',
           reason: 'Because I said so',
         },
       ]
     );
   }
 }
 

Rules and Property Overrides

In some cases L2 Constructs do not have a native option to remediate an issue and must be fixed via Raw Overrides. Since raw overrides take place after template synthesis these fixes are not caught by cdk-nag. In this case you should remediate the issue and suppress the issue like in the following example.

Example) Property Overrides

 import {
   Instance,
   InstanceType,
   InstanceClass,
   MachineImage,
   Vpc,
   CfnInstance,
 } from 'aws-cdk-lib/aws-ec2';
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { NagSuppressions } from 'cdk-nag';
 
 export class CdkTestStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
     const instance = new Instance(this, 'rInstance', {
       vpc: new Vpc(this, 'rVpc'),
       instanceType: new InstanceType(InstanceClass.T3),
       machineImage: MachineImage.latestAmazonLinux(),
     });
     const cfnIns = instance.node.defaultChild as CfnInstance;
     cfnIns.addPropertyOverride('DisableApiTermination', true);
     NagSuppressions.addResourceSuppressions(instance, [
       {
         id: 'AwsSolutions-EC29',
         reason: 'Remediated through property override.',
       },
     ]);
   }
 }
 

Conditionally Ignoring Suppressions

You can optionally create a condition that prevents certain rules from being suppressed. You can create conditions for any variety of reasons. Examples include a condition that always ignores a suppression, a condition that ignores a suppression based on the date, a condition that ignores a suppression based on the reason. You can read the developer docs for more information on creating your own conditions.

Example) Using the pre-built `SuppressionIgnoreErrors` class to ignore suppressions on any `Error` level rules.

 import { App, Aspects } from 'aws-cdk-lib';
 import { CdkTestStack } from '../lib/cdk-test-stack';
 import { AwsSolutionsChecks, SuppressionIgnoreErrors } from 'cdk-nag';
 
 const app = new App();
 new CdkTestStack(app, 'CdkNagDemo');
 // Ignore Suppressions on any errors
 Aspects.of(app).add(
   new AwsSolutionsChecks({
     suppressionIgnoreCondition: new SuppressionIgnoreErrors(),
   })
 );
 

Customizing Logging

NagLoggers give NagPack authors and users the ability to create their own custom reporting mechanisms. All pre-built NagPackscome with the AnnotationsLoggerand the NagReportLogger (with CSV reports) enabled by default.

See the NagLogger developer docs for more information.

Example) Adding the `ExtremelyHelpfulConsoleLogger` example from the NagLogger docs

 import { App, Aspects } from 'aws-cdk-lib';
 import { CdkTestStack } from '../lib/cdk-test-stack';
 import { ExtremelyHelpfulConsoleLogger } from './docs/NagLogger';
 import { AwsSolutionsChecks } from 'cdk-nag';
 
 const app = new App();
 new CdkTestStack(app, 'CdkNagDemo');
 Aspects.of(app).add(
   new AwsSolutionsChecks({
     additionalLoggers: [new ExtremelyHelpfulConsoleLogger()],
   })
 );
 

Using on CloudFormation templates

You can use cdk-nag on existing CloudFormation templates by using the cloudformation-include module.

Example 1) CloudFormation template with suppression

Sample CloudFormation template with suppression

 {
   "Resources": {
     "rBucket": {
       "Type": "AWS::S3::Bucket",
       "Properties": {
         "BucketName": "some-bucket-name"
       },
       "Metadata": {
         "cdk_nag": {
           "rules_to_suppress": [
             {
               "id": "AwsSolutions-S1",
               "reason": "at least 10 characters"
             }
           ]
         }
       }
     }
   }
 }
 

Sample App

 import { App, Aspects } from 'aws-cdk-lib';
 import { CdkTestStack } from '../lib/cdk-test-stack';
 import { AwsSolutionsChecks } from 'cdk-nag';
 
 const app = new App();
 new CdkTestStack(app, 'CdkNagDemo');
 Aspects.of(app).add(new AwsSolutionsChecks());
 

Sample Stack with imported template

 import { CfnInclude } from 'aws-cdk-lib/cloudformation-include';
 import { NagSuppressions } from 'cdk-nag';
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 
 export class CdkTestStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
     new CfnInclude(this, 'Template', {
       templateFile: 'my-template.json',
     });
     // Add any additional suppressions
     NagSuppressions.addResourceSuppressionsByPath(
       this,
       '/CdkNagDemo/Template/rBucket',
       [
         {
           id: 'AwsSolutions-S2',
           reason: 'at least 10 characters',
         },
       ]
     );
   }
 }
 

Example 2) CloudFormation template with granular suppressions

Sample CloudFormation template with suppression

 {
   "Resources": {
     "myPolicy": {
       "Type": "AWS::IAM::Policy",
       "Properties": {
         "PolicyDocument": {
           "Statement": [
             {
               "Action": [
                 "kms:Decrypt",
                 "kms:DescribeKey",
                 "kms:Encrypt",
                 "kms:ReEncrypt*",
                 "kms:GenerateDataKey*"
               ],
               "Effect": "Allow",
               "Resource": ["some-key-arn"]
             }
           ],
           "Version": "2012-10-17"
         }
       },
       "Metadata": {
         "cdk_nag": {
           "rules_to_suppress": [
             {
               "id": "AwsSolutions-IAM5",
               "reason": "Allow key data access",
               "applies_to": [
                 "Action::kms:ReEncrypt*",
                 "Action::kms:GenerateDataKey*"
               ]
             }
           ]
         }
       }
     }
   }
 }
 

Sample App

 import { App, Aspects } from 'aws-cdk-lib';
 import { CdkTestStack } from '../lib/cdk-test-stack';
 import { AwsSolutionsChecks } from 'cdk-nag';
 
 const app = new App();
 new CdkTestStack(app, 'CdkNagDemo');
 Aspects.of(app).add(new AwsSolutionsChecks());
 

Sample Stack with imported template

 import { CfnInclude } from 'aws-cdk-lib/cloudformation-include';
 import { NagSuppressions } from 'cdk-nag';
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 
 export class CdkTestStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
     new CfnInclude(this, 'Template', {
       templateFile: 'my-template.json',
     });
     // Add any additional suppressions
     NagSuppressions.addResourceSuppressionsByPath(
       this,
       '/CdkNagDemo/Template/myPolicy',
       [
         {
           id: 'AwsSolutions-IAM5',
           reason: 'Allow key data access',
           appliesTo: ['Action::kms:ReEncrypt*', 'Action::kms:GenerateDataKey*'],
         },
       ]
     );
   }
 }
 

Contributing

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

Interface Summary

Interface	Description
AnnotationLoggerProps	Props for the AnnotationLogger.
IApplyRule	Interface for JSII interoperability for passing parameters and the Rule Callback to @applyRule method.
IApplyRule.Jsii$Default	Internal default implementation for IApplyRule.
INagLogger	Interface for creating NagSuppression Ignores.
INagLogger.Jsii$Default	Internal default implementation for INagLogger.
INagSuppressionIgnore	Interface for creating NagSuppression Ignores.
INagSuppressionIgnore.Jsii$Default	Internal default implementation for INagSuppressionIgnore.
NagLoggerBaseData	Shared data for all INagLogger methods.
NagLoggerComplianceData	Data for onCompliance method of an INagLogger.
NagLoggerErrorData	Data for onError method of an INagLogger.
NagLoggerNonComplianceData	Data for onNonCompliance method of an INagLogger.
NagLoggerNotApplicableData	Data for onNotApplicable method of an INagLogger.
NagLoggerSuppressedData	Data for onSuppressed method of an INagLogger.
NagLoggerSuppressedErrorData	Data for onSuppressedError method of an INagLogger.
NagPackProps	Interface for creating a NagPack.
NagPackSuppression	Interface for creating a rule suppression.
NagReportLine
NagReportLoggerProps	Props for the NagReportLogger.
NagReportSchema
RegexAppliesTo	A regular expression to apply to matching findings.
SuppressionIgnoreInput	Information about the NagRule and the relevant NagSuppression for the INagSuppressionIgnore.

Class Summary

Class	Description
AnnotationLogger	A NagLogger that outputs to the CDK Annotations system.
AnnotationLogger.Builder	A fluent builder for AnnotationLogger.
AnnotationLoggerProps.Builder	A builder for AnnotationLoggerProps
AnnotationLoggerProps.Jsii$Proxy	An implementation for AnnotationLoggerProps
AwsSolutionsChecks	Check Best practices based on AWS Solutions Security Matrix.
AwsSolutionsChecks.Builder	A fluent builder for AwsSolutionsChecks.
HIPAASecurityChecks	Check for HIPAA Security compliance.
HIPAASecurityChecks.Builder	A fluent builder for HIPAASecurityChecks.
IApplyRule.Jsii$Proxy	A proxy class which represents a concrete javascript instance of this type.
INagLogger.Jsii$Proxy	A proxy class which represents a concrete javascript instance of this type.
INagSuppressionIgnore.Jsii$Proxy	A proxy class which represents a concrete javascript instance of this type.
NagLoggerBaseData.Builder	A builder for NagLoggerBaseData
NagLoggerBaseData.Jsii$Proxy	An implementation for NagLoggerBaseData
NagLoggerComplianceData.Builder	A builder for NagLoggerComplianceData
NagLoggerComplianceData.Jsii$Proxy	An implementation for NagLoggerComplianceData
NagLoggerErrorData.Builder	A builder for NagLoggerErrorData
NagLoggerErrorData.Jsii$Proxy	An implementation for NagLoggerErrorData
NagLoggerNonComplianceData.Builder	A builder for NagLoggerNonComplianceData
NagLoggerNonComplianceData.Jsii$Proxy	An implementation for NagLoggerNonComplianceData
NagLoggerNotApplicableData.Builder	A builder for NagLoggerNotApplicableData
NagLoggerNotApplicableData.Jsii$Proxy	An implementation for NagLoggerNotApplicableData
NagLoggerSuppressedData.Builder	A builder for NagLoggerSuppressedData
NagLoggerSuppressedData.Jsii$Proxy	An implementation for NagLoggerSuppressedData
NagLoggerSuppressedErrorData.Builder	A builder for NagLoggerSuppressedErrorData
NagLoggerSuppressedErrorData.Jsii$Proxy	An implementation for NagLoggerSuppressedErrorData
NagPack	Base class for all rule packs.
NagPackProps.Builder	A builder for NagPackProps
NagPackProps.Jsii$Proxy	An implementation for NagPackProps
NagPackSuppression.Builder	A builder for NagPackSuppression
NagPackSuppression.Jsii$Proxy	An implementation for NagPackSuppression
NagReportLine.Builder	A builder for NagReportLine
NagReportLine.Jsii$Proxy	An implementation for NagReportLine
NagReportLogger	A NagLogger that creates compliance reports.
NagReportLogger.Builder	A fluent builder for NagReportLogger.
NagReportLoggerProps.Builder	A builder for NagReportLoggerProps
NagReportLoggerProps.Jsii$Proxy	An implementation for NagReportLoggerProps
NagReportSchema.Builder	A builder for NagReportSchema
NagReportSchema.Jsii$Proxy	An implementation for NagReportSchema
NagRules	Helper class with methods for rule creation.
NagSuppressions	Helper class with methods to add cdk-nag suppressions to cdk resources.
NIST80053R4Checks	Check for NIST 800-53 rev 4 compliance.
NIST80053R4Checks.Builder	A fluent builder for NIST80053R4Checks.
NIST80053R5Checks	Check for NIST 800-53 rev 5 compliance.
NIST80053R5Checks.Builder	A fluent builder for NIST80053R5Checks.
PCIDSS321Checks	Check for PCI DSS 3.2.1 compliance.
PCIDSS321Checks.Builder	A fluent builder for PCIDSS321Checks.
RegexAppliesTo.Builder	A builder for RegexAppliesTo
RegexAppliesTo.Jsii$Proxy	An implementation for RegexAppliesTo
SuppressionIgnoreAlways	Always ignore the suppression.
SuppressionIgnoreAnd	Ignore the suppression if all of the given INagSuppressionIgnore return a non-empty message.
SuppressionIgnoreErrors	Ignore Suppressions for Rules with a NagMessageLevel.ERROR.
SuppressionIgnoreInput.Builder	A builder for SuppressionIgnoreInput
SuppressionIgnoreInput.Jsii$Proxy	An implementation for SuppressionIgnoreInput
SuppressionIgnoreNever	Don't ignore the suppression.
SuppressionIgnoreOr	Ignore the suppression if any of the given INagSuppressionIgnore return a non-empty message.

Enum Summary

Enum	Description
NagMessageLevel	The severity level of the rule.
NagReportFormat	Possible output formats of the NagReport.
NagRuleCompliance	The compliance level of a resource in relation to a rule.
NagRulePostValidationStates	Additional states a rule can be in post compliance validation.