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!
See RULES for more information on all the available packs.
Read the NagPack developer docs if you are interested in creating your own pack.
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 }));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) 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 3) 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 4) 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 policiesimport { 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 5) 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.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) Supressing 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',
},
]);
}
}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.',
},
]);
}
}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*'],
},
]
);
}
}See CONTRIBUTING for more information.
This project is licensed under the Apache-2.0 License.