cdk-nag


Namecdk-nag JSON
Version 2.28.75 PyPI version JSON
download
home_pagehttps://github.com/cdklabs/cdk-nag.git
SummaryCheck CDK v2 applications for best practices using a combination on available rule packs.
upload_time2024-03-28 00:13:47
maintainerNone
docs_urlNone
authorArun Donti<donti@amazon.com>
requires_python~=3.8
licenseApache-2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <!--
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
SPDX-License-Identifier: Apache-2.0
-->

# cdk-nag

[![PyPI version](https://img.shields.io/pypi/v/cdk-nag)](https://pypi.org/project/cdk-nag/)
[![npm version](https://img.shields.io/npm/v/cdk-nag)](https://www.npmjs.com/package/cdk-nag)
[![Maven version](https://img.shields.io/maven-central/v/io.github.cdklabs/cdknag)](https://search.maven.org/search?q=a:cdknag)
[![NuGet version](https://img.shields.io/nuget/v/Cdklabs.CdkNag)](https://www.nuget.org/packages/Cdklabs.CdkNag)
[![Go version](https://img.shields.io/github/go-mod/go-version/cdklabs/cdk-nag-go?color=blue&filename=cdknag%2Fgo.mod)](https://github.com/cdklabs/cdk-nag-go)

[![View on Construct Hub](https://constructs.dev/badge?package=cdk-nag)](https://constructs.dev/packages/cdk-nag)

Check CDK applications or [CloudFormation templates](#using-on-cloudformation-templates) for best practices using a combination of available rule packs. Inspired by [cfn_nag](https://github.com/stelligent/cfn_nag).

Check out [this blog post](https://aws.amazon.com/blogs/devops/manage-application-security-and-compliance-with-the-aws-cloud-development-kit-and-cdk-nag/) for a guided overview!

![demo](cdk_nag.gif)

## Available Rules and Packs

See [RULES](./RULES.md) for more information on all the available packs.

1. [AWS Solutions](./RULES.md#awssolutions)
2. [HIPAA Security](./RULES.md#hipaa-security)
3. [NIST 800-53 rev 4](./RULES.md#nist-800-53-rev-4)
4. [NIST 800-53 rev 5](./RULES.md#nist-800-53-rev-5)
5. [PCI DSS 3.2.1](./RULES.md#pci-dss-321)

[RULES](./RULES.md) also includes a collection of [additional rules](./RULES.md#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](./docs/NagPack.md) if you are interested in creating your own pack.

## Usage

For a full list of options See `NagPackProps` in the [API.md](./API.md#struct-nagpackprops)

<details>
<summary>Including in an application</summary>

```python
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 }));
```

</details>

## Suppressing a Rule

<details>
  <summary>Example 1) Default Construct</summary>

```python
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' },
    ]);
  }
}
```

</details><details>
  <summary>Example 2) On Multiple Constructs</summary>

```python
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' }]
    );
  }
}
```

</details><details>
  <summary>Example 3) Child Constructs</summary>

```python
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
    );
  }
}
```

</details><details>
  <summary>Example 4) Stack Level </summary>

```python
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' },
]);
```

</details><details>
  <summary>Example 5) Construct path</summary>

If you received the following error on synth/deploy

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

```python
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' }]
    );
  }
}
```

</details><details>
  <summary>Example 6) Granular Suppressions of findings</summary>

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

```bash
[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

```python
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

```bash
[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.
```

</details>

## Suppressing `aws-cdk-lib/pipelines` Violations

The [aws-cdk-lib/pipelines.CodePipeline](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.CodePipeline.html) 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](https://docs.aws.amazon.com/cdk/v2/guide/apps.html#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](https://github.com/aws/aws-cdk/issues/18440) for more information.

<details>
  <summary>Example) Suppressing Violations in Pipelines</summary>

`example-app.ts`

```python
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`

```python
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',
        },
      ]
    );
  }
}
```

</details>

## 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](https://docs.aws.amazon.com/cdk/latest/guide/cfn_layer.html#cfn_layer_raw). 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.

<details>
  <summary>Example) Property Overrides</summary>

```python
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.',
      },
    ]);
  }
}
```

</details>

## 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](./docs/IgnoreSuppressionConditions.md) for more information on creating your own conditions.

<details>
  <summary>Example) Using the pre-built `SuppressionIgnoreErrors` class to ignore suppressions on any `Error` level rules.</summary>

```python
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(),
  })
);
```

</details>

## Customizing Logging

`NagLogger`s give `NagPack` authors and users the ability to create their own custom reporting mechanisms. All pre-built `NagPacks`come with the `AnnotationsLogger`and the `NagReportLogger` (with CSV reports) enabled by default.

See the [NagLogger](./docs/NagLogger.md) developer docs for more information.

<details>
  <summary>Example) Adding the `ExtremelyHelpfulConsoleLogger` example from the NagLogger docs</summary>

```python
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()],
  })
);
```

</details>

## Using on CloudFormation templates

You can use cdk-nag on existing CloudFormation templates by using the [cloudformation-include](https://docs.aws.amazon.com/cdk/latest/guide/use_cfn_template.html#use_cfn_template_install) module.

<details>
  <summary>Example 1) CloudFormation template with suppression</summary>

Sample CloudFormation template with suppression

```json
{
  "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

```python
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

```python
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',
        },
      ]
    );
  }
}
```

</details><details>
  <summary>Example 2) CloudFormation template with granular suppressions</summary>

Sample CloudFormation template with suppression

```json
{
  "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

```python
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

```python
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*'],
        },
      ]
    );
  }
}
```

</details>

## Contributing

See [CONTRIBUTING](./CONTRIBUTING.md) for more information.

## License

This project is licensed under the Apache-2.0 License.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/cdklabs/cdk-nag.git",
    "name": "cdk-nag",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "~=3.8",
    "maintainer_email": null,
    "keywords": null,
    "author": "Arun Donti<donti@amazon.com>",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/b8/7b/074c22e25687c7c4c60955135dcf43381749aec869fd82a8fbb00cd23c06/cdk-nag-2.28.75.tar.gz",
    "platform": null,
    "description": "<!--\nCopyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\nSPDX-License-Identifier: Apache-2.0\n-->\n\n# cdk-nag\n\n[![PyPI version](https://img.shields.io/pypi/v/cdk-nag)](https://pypi.org/project/cdk-nag/)\n[![npm version](https://img.shields.io/npm/v/cdk-nag)](https://www.npmjs.com/package/cdk-nag)\n[![Maven version](https://img.shields.io/maven-central/v/io.github.cdklabs/cdknag)](https://search.maven.org/search?q=a:cdknag)\n[![NuGet version](https://img.shields.io/nuget/v/Cdklabs.CdkNag)](https://www.nuget.org/packages/Cdklabs.CdkNag)\n[![Go version](https://img.shields.io/github/go-mod/go-version/cdklabs/cdk-nag-go?color=blue&filename=cdknag%2Fgo.mod)](https://github.com/cdklabs/cdk-nag-go)\n\n[![View on Construct Hub](https://constructs.dev/badge?package=cdk-nag)](https://constructs.dev/packages/cdk-nag)\n\nCheck CDK applications or [CloudFormation templates](#using-on-cloudformation-templates) for best practices using a combination of available rule packs. Inspired by [cfn_nag](https://github.com/stelligent/cfn_nag).\n\nCheck out [this blog post](https://aws.amazon.com/blogs/devops/manage-application-security-and-compliance-with-the-aws-cloud-development-kit-and-cdk-nag/) for a guided overview!\n\n![demo](cdk_nag.gif)\n\n## Available Rules and Packs\n\nSee [RULES](./RULES.md) for more information on all the available packs.\n\n1. [AWS Solutions](./RULES.md#awssolutions)\n2. [HIPAA Security](./RULES.md#hipaa-security)\n3. [NIST 800-53 rev 4](./RULES.md#nist-800-53-rev-4)\n4. [NIST 800-53 rev 5](./RULES.md#nist-800-53-rev-5)\n5. [PCI DSS 3.2.1](./RULES.md#pci-dss-321)\n\n[RULES](./RULES.md) also includes a collection of [additional rules](./RULES.md#additional-rules) that are not currently included in any of the pre-built NagPacks, but are still available for inclusion in custom NagPacks.\n\nRead the [NagPack developer docs](./docs/NagPack.md) if you are interested in creating your own pack.\n\n## Usage\n\nFor a full list of options See `NagPackProps` in the [API.md](./API.md#struct-nagpackprops)\n\n<details>\n<summary>Including in an application</summary>\n\n```python\nimport { App, Aspects } from 'aws-cdk-lib';\nimport { CdkTestStack } from '../lib/cdk-test-stack';\nimport { AwsSolutionsChecks } from 'cdk-nag';\n\nconst app = new App();\nnew CdkTestStack(app, 'CdkNagDemo');\n// Simple rule informational messages\nAspects.of(app).add(new AwsSolutionsChecks());\n// Additional explanations on the purpose of triggered rules\n// Aspects.of(stack).add(new AwsSolutionsChecks({ verbose: true }));\n```\n\n</details>\n\n## Suppressing a Rule\n\n<details>\n  <summary>Example 1) Default Construct</summary>\n\n```python\nimport { SecurityGroup, Vpc, Peer, Port } from 'aws-cdk-lib/aws-ec2';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { NagSuppressions } from 'cdk-nag';\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    const test = new SecurityGroup(this, 'test', {\n      vpc: new Vpc(this, 'vpc'),\n    });\n    test.addIngressRule(Peer.anyIpv4(), Port.allTraffic());\n    NagSuppressions.addResourceSuppressions(test, [\n      { id: 'AwsSolutions-EC23', reason: 'lorem ipsum' },\n    ]);\n  }\n}\n```\n\n</details><details>\n  <summary>Example 2) On Multiple Constructs</summary>\n\n```python\nimport { SecurityGroup, Vpc, Peer, Port } from 'aws-cdk-lib/aws-ec2';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { NagSuppressions } from 'cdk-nag';\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    const vpc = new Vpc(this, 'vpc');\n    const test1 = new SecurityGroup(this, 'test', { vpc });\n    test1.addIngressRule(Peer.anyIpv4(), Port.allTraffic());\n    const test2 = new SecurityGroup(this, 'test', { vpc });\n    test2.addIngressRule(Peer.anyIpv4(), Port.allTraffic());\n    NagSuppressions.addResourceSuppressions(\n      [test1, test2],\n      [{ id: 'AwsSolutions-EC23', reason: 'lorem ipsum' }]\n    );\n  }\n}\n```\n\n</details><details>\n  <summary>Example 3) Child Constructs</summary>\n\n```python\nimport { User, PolicyStatement } from 'aws-cdk-lib/aws-iam';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { NagSuppressions } from 'cdk-nag';\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    const user = new User(this, 'rUser');\n    user.addToPolicy(\n      new PolicyStatement({\n        actions: ['s3:PutObject'],\n        resources: ['arn:aws:s3:::bucket_name/*'],\n      })\n    );\n    // Enable adding suppressions to child constructs\n    NagSuppressions.addResourceSuppressions(\n      user,\n      [\n        {\n          id: 'AwsSolutions-IAM5',\n          reason: 'lorem ipsum',\n          appliesTo: ['Resource::arn:aws:s3:::bucket_name/*'], // optional\n        },\n      ],\n      true\n    );\n  }\n}\n```\n\n</details><details>\n  <summary>Example 4) Stack Level </summary>\n\n```python\nimport { App, Aspects } from 'aws-cdk-lib';\nimport { CdkTestStack } from '../lib/cdk-test-stack';\nimport { AwsSolutionsChecks, NagSuppressions } from 'cdk-nag';\n\nconst app = new App();\nconst stack = new CdkTestStack(app, 'CdkNagDemo');\nAspects.of(app).add(new AwsSolutionsChecks());\nNagSuppressions.addStackSuppressions(stack, [\n  { id: 'AwsSolutions-EC23', reason: 'lorem ipsum' },\n]);\n```\n\n</details><details>\n  <summary>Example 5) Construct path</summary>\n\nIf you received the following error on synth/deploy\n\n```bash\n[Error at /StackName/Custom::CDKBucketDeployment8675309/ServiceRole/Resource] AwsSolutions-IAM4: The IAM user, role, or group uses AWS managed policies\n```\n\n```python\nimport { Bucket } from 'aws-cdk-lib/aws-s3';\nimport { BucketDeployment } from 'aws-cdk-lib/aws-s3-deployment';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { NagSuppressions } from 'cdk-nag';\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    new BucketDeployment(this, 'rDeployment', {\n      sources: [],\n      destinationBucket: Bucket.fromBucketName(this, 'rBucket', 'foo'),\n    });\n    NagSuppressions.addResourceSuppressionsByPath(\n      this,\n      '/StackName/Custom::CDKBucketDeployment8675309/ServiceRole/Resource',\n      [{ id: 'AwsSolutions-IAM4', reason: 'at least 10 characters' }]\n    );\n  }\n}\n```\n\n</details><details>\n  <summary>Example 6) Granular Suppressions of findings</summary>\n\nCertain rules support granular suppressions of `findings`. If you received the following errors on synth/deploy\n\n```bash\n[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.\n[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.\n[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.\n[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.\n```\n\nBy applying the following suppressions\n\n```python\nimport { User } from 'aws-cdk-lib/aws-iam';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { NagSuppressions } from 'cdk-nag';\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    const firstUser = new User(this, 'rFirstUser');\n    firstUser.addToPolicy(\n      new PolicyStatement({\n        actions: ['s3:*'],\n        resources: ['*'],\n      })\n    );\n    const secondUser = new User(this, 'rSecondUser');\n    secondUser.addToPolicy(\n      new PolicyStatement({\n        actions: ['s3:*'],\n        resources: ['*'],\n      })\n    );\n    const thirdUser = new User(this, 'rSecondUser');\n    thirdUser.addToPolicy(\n      new PolicyStatement({\n        actions: ['sqs:CreateQueue'],\n        resources: [`arn:aws:sqs:${this.region}:${this.account}:*`],\n      })\n    );\n    NagSuppressions.addResourceSuppressions(\n      firstUser,\n      [\n        {\n          id: 'AwsSolutions-IAM5',\n          reason:\n            \"Only suppress AwsSolutions-IAM5 's3:*' finding on First User.\",\n          appliesTo: ['Action::s3:*'],\n        },\n      ],\n      true\n    );\n    NagSuppressions.addResourceSuppressions(\n      secondUser,\n      [\n        {\n          id: 'AwsSolutions-IAM5',\n          reason: 'Suppress all AwsSolutions-IAM5 findings on Second User.',\n        },\n      ],\n      true\n    );\n    NagSuppressions.addResourceSuppressions(\n      thirdUser,\n      [\n        {\n          id: 'AwsSolutions-IAM5',\n          reason: 'Suppress AwsSolutions-IAM5 on the SQS resource.',\n          appliesTo: [\n            {\n              regex: '/^Resource::arn:aws:sqs:(.*):\\\\*$/g',\n            },\n          ],\n        },\n      ],\n      true\n    );\n  }\n}\n```\n\nYou would see the following error on synth/deploy\n\n```bash\n[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.\n```\n\n</details>\n\n## Suppressing `aws-cdk-lib/pipelines` Violations\n\nThe [aws-cdk-lib/pipelines.CodePipeline](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.CodePipeline.html) 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](https://docs.aws.amazon.com/cdk/v2/guide/apps.html#lifecycle). Because of this behavior, you may experience problems such as rule violations not appearing or the inability to suppress violations on these constructs.\n\nYou 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:\n\n```\nError: 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.\n```\n\nSee [this issue](https://github.com/aws/aws-cdk/issues/18440) for more information.\n\n<details>\n  <summary>Example) Suppressing Violations in Pipelines</summary>\n\n`example-app.ts`\n\n```python\nimport { App, Aspects } from 'aws-cdk-lib';\nimport { AwsSolutionsChecks } from 'cdk-nag';\nimport { ExamplePipeline } from '../lib/example-pipeline';\n\nconst app = new App();\nnew ExamplePipeline(app, 'example-cdk-pipeline');\nAspects.of(app).add(new AwsSolutionsChecks({ verbose: true }));\napp.synth();\n```\n\n`example-pipeline.ts`\n\n```python\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Repository } from 'aws-cdk-lib/aws-codecommit';\nimport {\n  CodePipeline,\n  CodePipelineSource,\n  ShellStep,\n} from 'aws-cdk-lib/pipelines';\nimport { NagSuppressions } from 'cdk-nag';\nimport { Construct } from 'constructs';\n\nexport class ExamplePipeline extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n\n    const exampleSynth = new ShellStep('ExampleSynth', {\n      commands: ['yarn build --frozen-lockfile'],\n      input: CodePipelineSource.codeCommit(\n        new Repository(this, 'ExampleRepo', { repositoryName: 'ExampleRepo' }),\n        'main'\n      ),\n    });\n\n    const ExamplePipeline = new CodePipeline(this, 'ExamplePipeline', {\n      synth: exampleSynth,\n    });\n\n    // Force the pipeline construct creation forward before applying suppressions.\n    // @See https://github.com/aws/aws-cdk/issues/18440\n    ExamplePipeline.buildPipeline();\n\n    // The path suppression will error if you comment out \"ExamplePipeline.buildPipeline();\"\"\n    NagSuppressions.addResourceSuppressionsByPath(\n      this,\n      '/example-cdk-pipeline/ExamplePipeline/Pipeline/ArtifactsBucket/Resource',\n      [\n        {\n          id: 'AwsSolutions-S1',\n          reason: 'Because I said so',\n        },\n      ]\n    );\n  }\n}\n```\n\n</details>\n\n## Rules and Property Overrides\n\nIn some cases L2 Constructs do not have a native option to remediate an issue and must be fixed via [Raw Overrides](https://docs.aws.amazon.com/cdk/latest/guide/cfn_layer.html#cfn_layer_raw). 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.\n\n<details>\n  <summary>Example) Property Overrides</summary>\n\n```python\nimport {\n  Instance,\n  InstanceType,\n  InstanceClass,\n  MachineImage,\n  Vpc,\n  CfnInstance,\n} from 'aws-cdk-lib/aws-ec2';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\nimport { NagSuppressions } from 'cdk-nag';\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    const instance = new Instance(this, 'rInstance', {\n      vpc: new Vpc(this, 'rVpc'),\n      instanceType: new InstanceType(InstanceClass.T3),\n      machineImage: MachineImage.latestAmazonLinux(),\n    });\n    const cfnIns = instance.node.defaultChild as CfnInstance;\n    cfnIns.addPropertyOverride('DisableApiTermination', true);\n    NagSuppressions.addResourceSuppressions(instance, [\n      {\n        id: 'AwsSolutions-EC29',\n        reason: 'Remediated through property override.',\n      },\n    ]);\n  }\n}\n```\n\n</details>\n\n## Conditionally Ignoring Suppressions\n\nYou 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](./docs/IgnoreSuppressionConditions.md) for more information on creating your own conditions.\n\n<details>\n  <summary>Example) Using the pre-built `SuppressionIgnoreErrors` class to ignore suppressions on any `Error` level rules.</summary>\n\n```python\nimport { App, Aspects } from 'aws-cdk-lib';\nimport { CdkTestStack } from '../lib/cdk-test-stack';\nimport { AwsSolutionsChecks, SuppressionIgnoreErrors } from 'cdk-nag';\n\nconst app = new App();\nnew CdkTestStack(app, 'CdkNagDemo');\n// Ignore Suppressions on any errors\nAspects.of(app).add(\n  new AwsSolutionsChecks({\n    suppressionIgnoreCondition: new SuppressionIgnoreErrors(),\n  })\n);\n```\n\n</details>\n\n## Customizing Logging\n\n`NagLogger`s give `NagPack` authors and users the ability to create their own custom reporting mechanisms. All pre-built `NagPacks`come with the `AnnotationsLogger`and the `NagReportLogger` (with CSV reports) enabled by default.\n\nSee the [NagLogger](./docs/NagLogger.md) developer docs for more information.\n\n<details>\n  <summary>Example) Adding the `ExtremelyHelpfulConsoleLogger` example from the NagLogger docs</summary>\n\n```python\nimport { App, Aspects } from 'aws-cdk-lib';\nimport { CdkTestStack } from '../lib/cdk-test-stack';\nimport { ExtremelyHelpfulConsoleLogger } from './docs/NagLogger';\nimport { AwsSolutionsChecks } from 'cdk-nag';\n\nconst app = new App();\nnew CdkTestStack(app, 'CdkNagDemo');\nAspects.of(app).add(\n  new AwsSolutionsChecks({\n    additionalLoggers: [new ExtremelyHelpfulConsoleLogger()],\n  })\n);\n```\n\n</details>\n\n## Using on CloudFormation templates\n\nYou can use cdk-nag on existing CloudFormation templates by using the [cloudformation-include](https://docs.aws.amazon.com/cdk/latest/guide/use_cfn_template.html#use_cfn_template_install) module.\n\n<details>\n  <summary>Example 1) CloudFormation template with suppression</summary>\n\nSample CloudFormation template with suppression\n\n```json\n{\n  \"Resources\": {\n    \"rBucket\": {\n      \"Type\": \"AWS::S3::Bucket\",\n      \"Properties\": {\n        \"BucketName\": \"some-bucket-name\"\n      },\n      \"Metadata\": {\n        \"cdk_nag\": {\n          \"rules_to_suppress\": [\n            {\n              \"id\": \"AwsSolutions-S1\",\n              \"reason\": \"at least 10 characters\"\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n```\n\nSample App\n\n```python\nimport { App, Aspects } from 'aws-cdk-lib';\nimport { CdkTestStack } from '../lib/cdk-test-stack';\nimport { AwsSolutionsChecks } from 'cdk-nag';\n\nconst app = new App();\nnew CdkTestStack(app, 'CdkNagDemo');\nAspects.of(app).add(new AwsSolutionsChecks());\n```\n\nSample Stack with imported template\n\n```python\nimport { CfnInclude } from 'aws-cdk-lib/cloudformation-include';\nimport { NagSuppressions } from 'cdk-nag';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    new CfnInclude(this, 'Template', {\n      templateFile: 'my-template.json',\n    });\n    // Add any additional suppressions\n    NagSuppressions.addResourceSuppressionsByPath(\n      this,\n      '/CdkNagDemo/Template/rBucket',\n      [\n        {\n          id: 'AwsSolutions-S2',\n          reason: 'at least 10 characters',\n        },\n      ]\n    );\n  }\n}\n```\n\n</details><details>\n  <summary>Example 2) CloudFormation template with granular suppressions</summary>\n\nSample CloudFormation template with suppression\n\n```json\n{\n  \"Resources\": {\n    \"myPolicy\": {\n      \"Type\": \"AWS::IAM::Policy\",\n      \"Properties\": {\n        \"PolicyDocument\": {\n          \"Statement\": [\n            {\n              \"Action\": [\n                \"kms:Decrypt\",\n                \"kms:DescribeKey\",\n                \"kms:Encrypt\",\n                \"kms:ReEncrypt*\",\n                \"kms:GenerateDataKey*\"\n              ],\n              \"Effect\": \"Allow\",\n              \"Resource\": [\"some-key-arn\"]\n            }\n          ],\n          \"Version\": \"2012-10-17\"\n        }\n      },\n      \"Metadata\": {\n        \"cdk_nag\": {\n          \"rules_to_suppress\": [\n            {\n              \"id\": \"AwsSolutions-IAM5\",\n              \"reason\": \"Allow key data access\",\n              \"applies_to\": [\n                \"Action::kms:ReEncrypt*\",\n                \"Action::kms:GenerateDataKey*\"\n              ]\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n```\n\nSample App\n\n```python\nimport { App, Aspects } from 'aws-cdk-lib';\nimport { CdkTestStack } from '../lib/cdk-test-stack';\nimport { AwsSolutionsChecks } from 'cdk-nag';\n\nconst app = new App();\nnew CdkTestStack(app, 'CdkNagDemo');\nAspects.of(app).add(new AwsSolutionsChecks());\n```\n\nSample Stack with imported template\n\n```python\nimport { CfnInclude } from 'aws-cdk-lib/cloudformation-include';\nimport { NagSuppressions } from 'cdk-nag';\nimport { Stack, StackProps } from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\n\nexport class CdkTestStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    new CfnInclude(this, 'Template', {\n      templateFile: 'my-template.json',\n    });\n    // Add any additional suppressions\n    NagSuppressions.addResourceSuppressionsByPath(\n      this,\n      '/CdkNagDemo/Template/myPolicy',\n      [\n        {\n          id: 'AwsSolutions-IAM5',\n          reason: 'Allow key data access',\n          appliesTo: ['Action::kms:ReEncrypt*', 'Action::kms:GenerateDataKey*'],\n        },\n      ]\n    );\n  }\n}\n```\n\n</details>\n\n## Contributing\n\nSee [CONTRIBUTING](./CONTRIBUTING.md) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "Check CDK v2 applications for best practices using a combination on available rule packs.",
    "version": "2.28.75",
    "project_urls": {
        "Homepage": "https://github.com/cdklabs/cdk-nag.git",
        "Source": "https://github.com/cdklabs/cdk-nag.git"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "a6f78bdab81e5b13aeab119935d2b5b832eb8088c30ddb2136ded887c9093ef6",
                "md5": "41e150ff4413aec7b95b1e04137971c2",
                "sha256": "24964ea3174581e4deaaae9ff1f9341b781f0187d52a2b09d4ba23a75bbd7c29"
            },
            "downloads": -1,
            "filename": "cdk_nag-2.28.75-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "41e150ff4413aec7b95b1e04137971c2",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "~=3.8",
            "size": 717571,
            "upload_time": "2024-03-28T00:13:35",
            "upload_time_iso_8601": "2024-03-28T00:13:35.442470Z",
            "url": "https://files.pythonhosted.org/packages/a6/f7/8bdab81e5b13aeab119935d2b5b832eb8088c30ddb2136ded887c9093ef6/cdk_nag-2.28.75-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "b87b074c22e25687c7c4c60955135dcf43381749aec869fd82a8fbb00cd23c06",
                "md5": "47ea481272457f65bf9af99e050c04b4",
                "sha256": "a69570d6afa0966c81cebe1a06d7d9be46f2aea39a532b0e35e809e5367650cf"
            },
            "downloads": -1,
            "filename": "cdk-nag-2.28.75.tar.gz",
            "has_sig": false,
            "md5_digest": "47ea481272457f65bf9af99e050c04b4",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "~=3.8",
            "size": 722715,
            "upload_time": "2024-03-28T00:13:47",
            "upload_time_iso_8601": "2024-03-28T00:13:47.802142Z",
            "url": "https://files.pythonhosted.org/packages/b8/7b/074c22e25687c7c4c60955135dcf43381749aec869fd82a8fbb00cd23c06/cdk-nag-2.28.75.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-28 00:13:47",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "cdklabs",
    "github_project": "cdk-nag",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "cdk-nag"
}
        
Elapsed time: 0.23807s