AWS cdk documentation change
Summary
Updated documentation to broaden scope from policy validation to general validation at synthesis time. Added sections on validation limitations, default validation plugins, security implications of plugins, structured reporting format, and construct author guidance.
Security assessment
The changes explicitly warn about plugin security risks ('Plugins have full access to your machine') and emphasize verifying plugin sources. This adds security documentation but doesn't address a specific vulnerability or incident.
Diff
diff --git a/cdk/v2/guide/policy-validation-synthesis.md b/cdk/v2/guide/policy-validation-synthesis.md index 7b145c24e..757e4df0a 100644 --- a//cdk/v2/guide/policy-validation-synthesis.md +++ b//cdk/v2/guide/policy-validation-synthesis.md @@ -7 +7 @@ -Policy validation at synthesis timeFor application developersFor plugin authors +Validation at synthesis timeWhat validation is and isn’tFor application developersFor construct authors: adding warnings and errors directlyFor plugin authors @@ -11 +11 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -# AWS CDK policy validation at synthesis time +# AWS CDK validation at synthesis time @@ -13 +13 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -## Policy validation at synthesis time +## Validation at synthesis time @@ -15,5 +15 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -If you or your organization use any policy validation tool, such as [AWS CloudFormation Guard](https://docs.aws.amazon.com/cfn-guard/latest/ug/what-is-guard.html) or [OPA](https://www.openpolicyagent.org/), to define constraints on your AWS CloudFormation template, you can integrate them with the AWS CDK at synthesis time. By using the appropriate policy validation plugin, you can make the AWS CDK application check the generated AWS CloudFormation template against your policies immediately after synthesis. If there are any violations, the synthesis will fail and a report will be printed to the console. - -The validation performed by the AWS CDK at synthesis time validate controls at one point in the deployment lifecycle, but they can’t affect actions that occur outside synthesis. Examples include actions taken directly in the console or via service APIs. They aren’t resistant to alteration of AWS CloudFormation templates after synthesis. Some other mechanism to validate the same rule set more authoritatively should be set up independently, like [AWS CloudFormation hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks.html) or [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html). Nevertheless, the ability of the AWS CDK to evaluate the rule set during development is still useful as it will improve detection speed and developer productivity. - -The goal of AWS CDK policy validation is to minimize the amount of set up needed during development, and make it as easy as possible. +Your AWS CDK application generates an infrastructure description at synthesis time in the form of CloudFormation templates. Those templates are validated immediately after synthesis. The AWS CDK comes with a built-in set of validation rules, which you can extend with other CDK-specific validation tools such as [CDK Nag](https://github.com/cdklabs/cdk-nag), or any policy validation tool your organization is already using such as [AWS CloudFormation Guard](https://docs.aws.amazon.com/cfn-guard/latest/ug/what-is-guard.html) or [OPA](https://www.openpolicyagent.org/). If there are any violations, the synthesis will fail and a report will be printed to the console. Using offline validation of your synthesized templates, you can discover and fix potential problems with your infrastructure early. You would use validation to find issues that would lead to failed deployments, common misconfigurations, or failure to comply with company standards. @@ -24,0 +21,4 @@ The previous `Beta1` interfaces (such as `IPolicyValidationPluginBeta1`, `Policy +## What validation is and isn’t + +The validation performed by the AWS CDK at synthesis time is a best-effort validation to improve developer experience; it is not a full standards compliance mechanism by itself. It validates templates generated normally by a CDK app, but it can’t affect actions that occur outside synthesis. For example, actions taken directly in the console or via service APIs. In addition, because CDK apps are written in a general-purpose programming language, determined developers are able to bypass the validation mechanism if they want. That is why CDK validation is a shift-left mechanism to validate early, and should be used in combination with another mechanism to validate the desired rule sets like [AWS CloudFormation hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks.html) or [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html). + @@ -29 +29 @@ The previous `Beta1` interfaces (such as `IPolicyValidationPluginBeta1`, `Policy -To use one or more validation plugins in your application, use the `Validations` class: +Validation is performed by validation plugins. A default plugin that uses a comprehensive rule set for AWS resources is automatically added to your application, based on [@aws/cloudformation-validate](https://github.com/aws-cloudformation/cloudformation-validate). If you want to add additional plugins to your application, use the `Validations` class: @@ -48 +48 @@ Immediately after synthesis, all plugins registered this way will be invoked to -Other than modifying the cloud assembly, plugins can do anything that your AWS CDK application can. They can read data from the filesystem, access the network etc. It’s your responsibility as the consumer of a plugin to verify that it’s secure to use. +Plugins have full access to your machine when they are running. It’s your responsibility as the consumer of a plugin to verify that it comes from a trusted source. @@ -50 +50 @@ Other than modifying the cloud assembly, plugins can do anything that your AWS C -### Adding warnings and errors +### Validation Report @@ -52 +52 @@ Other than modifying the cloud assembly, plugins can do anything that your AWS C -The `Validations` class also provides methods to add custom warnings and errors to your constructs: +When you synthesize the AWS CDK app the validator plugins will be called and the results will be printed. An example report is showing below. @@ -55 +55,5 @@ The `Validations` class also provides methods to add custom warnings and errors - import { Validations } from 'aws-cdk-lib'; + lib/my-custom-l3-construct.ts:10:5 + ERROR [CT.S3.PR.1]: Require an Amazon S3 bucket to have block public access settings configured (cdk-validator-cfnguard) + MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct + Suggested fix: [FIX]: The parameters 'BlockPublicAcls', 'BlockPublicPolicy', 'IgnorePublicAcls', 'RestrictPublicBuckets' must be set to true under the bucket-level 'PublicAccessBlockConfiguration'. + Acknowledge with 'cdk-validator-cfnguard::s3_bucket_level_public_access_prohibited_check' @@ -57 +61,5 @@ The `Validations` class also provides methods to add custom warnings and errors - const bucket = new s3.Bucket(this, 'MyBucket'); + lib/my-custom-l3-construct.ts:10:5 + ERROR [CT.S3.PR.10]: Require an Amazon S3 bucket to have server-side encryption configured using an AWS KMS key (cdk-validator-cfnguard) + MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct + Suggested fix: [FIX]: Set an encryption rule in 'BucketEncryption.ServerSideEncryptionConfiguration' with a 'ServerSideEncryptionByDefault.SSEAlgorithm' configuration of 'aws:kms' or 'aws:kms:dsse' + Acknowledge with 'cdk-validator-cfnguard::s3_bucket_default_encryption_kms_check' @@ -59,2 +67 @@ The `Validations` class also provides methods to add custom warnings and errors - // Add a warning - Validations.of(bucket).addWarning('MyWarningId', 'This bucket does not have versioning enabled'); + ... @@ -62,2 +69,10 @@ The `Validations` class also provides methods to add custom warnings and errors - // Add an error (will cause synthesis to fail) - Validations.of(bucket).addError('MyErrorId', 'This bucket must have encryption enabled'); +By default, the report will be printed in a human readable format. If you want a report in JSON format, enable it using the `@aws-cdk/core:validationReportJson` via the CLI or passing it directly to the application: + + + const app = new App({ + context: { '@aws-cdk/core:validationReportJson': true }, + }); + +Alternatively, you can set this context key-value pair using the `cdk.json` or `cdk.context.json` files in your project directory (see [Context values and the AWS CDK](./context.html)). + +If you choose the JSON format, the AWS CDK will print the policy validation report to a file called `policy-validation-report.json` in the cloud assembly directory. For the default, human-readable format, the report will be printed to the standard output. @@ -67 +82 @@ The `Validations` class also provides methods to add custom warnings and errors -If you want to suppress a specific warning, use the `acknowledge` method: +If you have evaluated a warning or error and deemed it to not apply for you, you can suppress it using the `acknowledge` method. Suppression is scope-based, and applies to all constructs under the given scope. @@ -72 +87,4 @@ If you want to suppress a specific warning, use the `acknowledge` method: - Validations.of(myConstruct).acknowledge({ id: 'MyWarningId', reason: 'This is acceptable for our use case' }); + Validations.of(myConstruct).acknowledge({ + id: 'PluginName::MyWarningId', + reason: 'This is acceptable for our use case', + }); @@ -74 +92 @@ If you want to suppress a specific warning, use the `acknowledge` method: -The `acknowledge` method accepts `Acknowledgment` objects with an `id` and a `reason`. The `id` uses a `::` delimiter to separate the validation source prefix from the rule name (for example, `annotation::MyWarning` or `cdknag::AwsSolutions-S1`). If you provide a bare ID without `::`, the `annotation::` prefix is added automatically. +The `id` uses a `::` delimiter to separate the validation source prefix from the rule name (for example, `Construct-Annotations::` or `AwsSolutions-S1::`). @@ -84 +102 @@ These AWS CDK bundled controls and managed AWS Control Tower proactive controls -### Validation Report +### AWS CDK Nag plugin @@ -86 +104 @@ These AWS CDK bundled controls and managed AWS Control Tower proactive controls -When you synthesize the AWS CDK app the validator plugins will be called and the results will be printed. An example report is showing below. +You can use [CDK Nag](https://github.com/cdklabs/cdk-nag) to check your infrastructure against a number of standards like HIPAA, PCI DSS, and so on. Version 3.x of cdk-nag integrates with the standardized Validations mechanism in CDK. @@ -87,0 +106 @@ When you synthesize the AWS CDK app the validator plugins will be called and the +## For construct authors: adding warnings and errors directly @@ -89,37 +108 @@ When you synthesize the AWS CDK app the validator plugins will be called and the - Validation Report (CfnGuardValidator) - ------------------------------------- - (Summary) - ╔═══════════╤════════════════════════╗ - ║ Status │ failure ║ - ╟───────────┼────────────────────────╢ - ║ Plugin │ CfnGuardValidator ║ - ╚═══════════╧════════════════════════╝ - (Violations) - Ensure S3 Buckets are encrypted with a KMS CMK (1 occurrences) - Severity: medium - Occurrences: - - - Construct Path: MyStack/MyCustomL3Construct/Bucket - - Stack Template Path: ./cdk.out/MyStack.template.json - - Creation Stack: - └── MyStack (MyStack) - │ Library: aws-cdk-lib.Stack - │ Library Version: 2.50.0 - │ Location: Object.<anonymous> (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:25:20) - └── MyCustomL3Construct (MyStack/MyCustomL3Construct) - │ Library: N/A - (Local Construct) - │ Library Version: N/A - │ Location: new MyStack (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:15:20) - └── Bucket (MyStack/MyCustomL3Construct/Bucket) - │ Library: aws-cdk-lib/aws-s3.Bucket - │ Library Version: 2.50.0 - │ Location: new MyCustomL3Construct (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:9:20) - - Resource Name: amzn-s3-demo-bucket - - Locations: - > BucketEncryption/ServerSideEncryptionConfiguration/0/ServerSideEncryptionByDefault/SSEAlgorithm - Recommendation: Missing value for key `SSEAlgorithm` - must specify `aws:kms` - How to fix: - > Add to construct properties for `cdk-app/MyStack/Bucket` - `encryption: BucketEncryption.KMS` - - Validation failed. See above reports for details +The `Validations` class also provides methods to add custom warnings and errors to your constructs directly. You can use this mechanism to report misconfigurations directly on your construct without having to implement a validation plugin. The validations and errors you add this way will be reported along with the violations found by validation plugins. @@ -127 +109,0 @@ When you synthesize the AWS CDK app the validator plugins will be called and the -By default, the report will be printed in a human readable format. If you want a report in JSON format, enable it using the `@aws-cdk/core:validationReportJson` via the CLI or passing it directly to the application: @@ -128,0 +111 @@ By default, the report will be printed in a human readable format. If you want a + import { Validations } from 'aws-cdk-lib'; @@ -130,3 +113 @@ By default, the report will be printed in a human readable format. If you want a - const app = new App({ - context: { '@aws-cdk/core:validationReportJson': true }, - }); + const bucket = new s3.Bucket(this, 'MyBucket'); @@ -134 +115,2 @@ By default, the report will be printed in a human readable format. If you want a -Alternatively, you can set this context key-value pair using the `cdk.json` or `cdk.context.json` files in your project directory (see [Context values and the AWS CDK](./context.html)). + // Add a warning + Validations.of(bucket).addWarning('MyWarningId', 'This bucket does not have versioning enabled'); @@ -136 +118,2 @@ Alternatively, you can set this context key-value pair using the `cdk.json` or ` -If you choose the JSON format, the AWS CDK will print the policy validation report to a file called `policy-validation-report.json` in the cloud assembly directory. For the default, human-readable format, the report will be printed to the standard output. + // Add an error (will cause synthesis to fail) + Validations.of(bucket).addError('MyErrorId', 'This bucket must have encryption enabled'); @@ -140,3 +123 @@ If you choose the JSON format, the AWS CDK will print the policy validation repo -### Plugins - -The AWS CDK core framework is responsible for registering and invoking plugins and then displaying the formatted validation report. The responsibility of the plugin is to act as the translation layer between the AWS CDK framework and the policy validation tool. A plugin can be created in any language supported by AWS CDK. If you are creating a plugin that might be consumed by multiple languages then it’s recommended that you create the plugin in `TypeScript` so that you can use JSII to publish the plugin in each AWS CDK language. +The AWS CDK core framework is responsible for registering and invoking plugins and then displaying the formatted validation report. The responsibility of the plugin is to act as the translation layer between the AWS CDK framework and an external policy validation tool that your plugin might for example shell out to. A plugin can be created in any language supported by AWS CDK. If you are creating a plugin that might be consumed by multiple languages then it’s recommended that you create the plugin in `TypeScript` so that you can use JSII to publish the plugin in each AWS CDK language. @@ -172 +153 @@ Note that plugins aren’t allowed to modify anything in the cloud assembly. Any -If your plugin depends on an external tool, keep in mind that some developers may not have that tool installed in their workstations yet. To minimize friction, we highly recommend that you provide some installation script along with your plugin package, to automate the whole process. Better yet, run that script as part of the installation of your package. With `npm`, for example, you can add it to the `postinstall` [script](https://docs.npmjs.com/cli/v9/using-npm/scripts) in the `package.json` file. +If your plugin depends on an external tool that you shell out to, keep in mind that some developers may not have that tool installed in their workstations yet. To minimize friction, provide some installation script along with your plugin package to automate the installation process.