Install & Compatibility
Where this runs
tested against v3.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 377.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 19.2s · import 0.000s · 378MB
400MB installed
● package 400MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AwsSolutionsChecks
✓ from cdk_nag import AwsSolutionsChecks
NagSuppressions
✓ from cdk_nag import NagSuppressions
NagPack
✓ from cdk_nag import NagPack
NIST80053R5Checks
✓ from cdk_nag import NIST80053R5Checks
HIPAASecurityChecks
✓ from cdk_nag import HIPAASecurityChecks
This quickstart demonstrates how to integrate `cdk-nag` into a Python CDK application. It creates a simple S3 bucket that would typically trigger AWS Solutions best practice warnings. It then shows how to apply the `AwsSolutionsChecks` to the entire application and how to add a suppression for a specific rule on a resource, including a mandatory reason for the suppression. Run `cdk synth` after adding this code to see the nag findings.
import os
from aws_cdk import App, Stack, Aspects, aws_s3 as s3
from constructs import Construct
from cdk_nag import AwsSolutionsChecks, NagSuppressions
class MyNaggedStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# An S3 bucket that will likely trigger some AwsSolutions nags
# for missing logging, encryption, and public access blocks.
my_bucket = s3.Bucket(self, "MyInsecureBucket")
# Suppress a specific finding on the bucket with a clear reason
# This suppression is for demonstration; always address findings first.
NagSuppressions.add_resource_suppressions(
my_bucket,
[
{
"id": "AwsSolutions-S1",
"reason": "This is a demonstration bucket; access logging is not critical for this specific example."
}
]
)
app = App()
# Apply AWS Solutions Checks to the entire app
Aspects.of(app).add(AwsSolutionsChecks(verbose=True))
MyNaggedStack(app, "CdkNagDemoStack")
app.synth()
Debug
Known issues
gotchaWhen using monorepos with package managers like PNPM, `cdk-nag` might fail to enforce rule checks silently if multiple versions of `aws-cdk-lib` are present. This occurs due to `instanceof` checks that evaluate to false across different instances of the `aws-cdk-lib` module.fixEnsure that only a single, consistent version of `aws-cdk-lib` is used across your entire monorepo. Workarounds like using `vite-node` for specific build steps have been reported.
affects: Potentially all `cdk-nag` versions relying on `instanceof` checks for `aws-cdk-lib` constructs (e.g., 2.22.21 and later).
gotchaConstructs within `aws-cdk-lib/pipelines.CodePipeline` and its children are not always guaranteed to be 'Visited' by `cdk-nag` Aspects during the CDK lifecycle. This can lead to missed rule violations or ineffective suppressions on pipeline-related resources.fixExplicitly call `.buildPipeline()` on your `CodePipeline` object to force the pipeline construct creation forward, ensuring that all child constructs are available for aspect visitation.
affects: All versions where `aws-cdk-lib/pipelines` aspects are not consistently visited.
gotchaSuppressing `cdk-nag` findings without a clear, valid reason can undermine security posture and compliance efforts. Each suppression should be a conscious decision, not a shortcut.fixAlways provide a detailed and meaningful `reason` when adding `NagSuppressions`. This documentation is crucial for future audits and understanding security decisions.
affects: All versions.
gotchaMany AWS resources, when created with default CDK configurations, do not meet common security best practices (e.g., S3 buckets without server-side encryption or access logging, SNS topics without SSL enforcement). These defaults will often trigger `cdk-nag` warnings or errors.fixProactively configure AWS resources to adhere to security best practices (e.g., enable encryption, enforce SSL, configure logging) rather than relying on defaults. Use `cdk-nag` output to guide these improvements.
affects: All versions, as this relates to default CDK resource behavior.
Errors
Common errors & fixes
[Error at /MyStack/MyResource/Resource] AwsSolutions-IAM5: The IAM entity contains wildcard permissions and does not have a cdk-nag rule suppression with evidence for those permission.
An AWS IAM policy defined within a CDK construct uses wildcard permissions (`*`) for actions or resources, which violates the AwsSolutions-IAM5 rule in cdk-nag, requiring least privilege.
fixRefine the IAM policy to grant only necessary, specific permissions for actions and resources. Alternatively, add a cdk-nag suppression to the resource or stack, providing a clear justification for the wildcard use.
ModuleNotFoundError: No module named 'cdk_nag'
The 'cdk-nag' Python package is not installed in the currently active Python environment, or the environment where it is installed is not active.
fixActivate your Python virtual environment (if using one) and install the 'cdk-nag' package using pip: `pip install cdk-nag`.
cdk-nag won't throw errors when using 2 versions of aws-cdk-lib in project because of instanceof check
In monorepo setups, particularly with package managers that can result in multiple instances of 'aws-cdk-lib' being loaded, cdk-nag's internal 'instanceof' checks for CDK constructs can fail, causing it to not enforce rules or report findings.
fixEnsure that only a single version of 'aws-cdk-lib' is present and used at runtime across your project, often achieved by configuring package manager deduplication or dependency resolution strategies (e.g., in `package.json` for npm/yarn or `vite.config.ts` for Vite-based projects).
Upgrade
Version history
3.0.2latest on PyPI · released Aug 4, 2026
Audit
Dependencies
aws-cdk-librequiredcdk-nag is an extension for AWS CDK applications and requires the AWS CDK library to function. Ensure it's installed and compatible with your cdk-nag version.
Python ~=3.9requiredThe library officially supports Python versions compatible with '~=3.9'.