AWS cdk documentation change
Summary
Graduated policy validation APIs from beta to stable, added new Validations class for managing plugins/warnings/errors, and deprecated Beta1 interfaces
Security assessment
The changes enhance policy validation capabilities which are security-related features (validating IAM policies/configurations), but there's no evidence of addressing a specific vulnerability. Added documentation for custom security warnings/errors and acknowledgments.
Diff
diff --git a/cdk/v2/guide/policy-validation-synthesis.md b/cdk/v2/guide/policy-validation-synthesis.md index a39af11db..7b145c24e 100644 --- a//cdk/v2/guide/policy-validation-synthesis.md +++ b//cdk/v2/guide/policy-validation-synthesis.md @@ -23 +23 @@ The goal of AWS CDK policy validation is to minimize the amount of set up needed -This feature is considered experimental, and both the plugin API and the format of the validation report are subject to change in the future. +The previous `Beta1` interfaces (such as `IPolicyValidationPluginBeta1`, `PolicyValidationPluginReportBeta1`, and the `policyValidationBeta1` property on `Stage`) have been graduated to stable, no-suffix equivalents (for example, `IPolicyValidationPlugin`, `PolicyValidationPluginReport`). The `Beta1` interfaces are deprecated but continue to work. The recommended way to register validation plugins is now through the `Validations` class rather than the `policyValidationBeta1` property. @@ -27 +27 @@ This feature is considered experimental, and both the plugin API and the format -To use one or more validation plugins in your application, use the `policyValidationBeta1` property of `Stage`: +### Adding validation plugins @@ -28,0 +29 @@ To use one or more validation plugins in your application, use the `policyValida +To use one or more validation plugins in your application, use the `Validations` class: @@ -29,0 +31,2 @@ To use one or more validation plugins in your application, use the `policyValida + + import { Validations } from 'aws-cdk-lib'; @@ -31,9 +34,9 @@ To use one or more validation plugins in your application, use the `policyValida - const app = new App({ - policyValidationBeta1: [ - new CfnGuardValidator() - ], - }); - // only apply to a particular stage - const prodStage = new Stage(app, 'ProdStage', { - policyValidationBeta1: [...], - }); + + const app = new App(); + + // Add a validation plugin to the entire app + Validations.of(app).addPlugins(new CfnGuardValidator()); + + // Or add to a particular stage + const prodStage = new Stage(app, 'ProdStage'); + Validations.of(prodStage).addPlugins(new CfnGuardValidator()); @@ -46,0 +50,26 @@ Other than modifying the cloud assembly, plugins can do anything that your AWS C +### Adding warnings and errors + +The `Validations` class also provides methods to add custom warnings and errors to your constructs: + + + import { Validations } from 'aws-cdk-lib'; + + const bucket = new s3.Bucket(this, 'MyBucket'); + + // Add a warning + Validations.of(bucket).addWarning('MyWarningId', 'This bucket does not have versioning enabled'); + + // Add an error (will cause synthesis to fail) + Validations.of(bucket).addError('MyErrorId', 'This bucket must have encryption enabled'); + +### Acknowledging warnings + +If you want to suppress a specific warning, use the `acknowledge` method: + + + import { Validations } from 'aws-cdk-lib'; + + Validations.of(myConstruct).acknowledge({ id: 'MyWarningId', reason: 'This is acceptable for our use case' }); + +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. + @@ -117 +146 @@ The AWS CDK core framework is responsible for registering and invoking plugins a -The communication protocol between the AWS CDK core module and your policy tool is defined by the `IPolicyValidationPluginBeta1` interface. To create a new plugin you must write a class that implements this interface. There are two things you need to implement: the plugin name (by overriding the `name` property), and the `validate()` method. +The communication protocol between the AWS CDK core module and your policy tool is defined by the `IPolicyValidationPlugin` interface. To create a new plugin you must write a class that implements this interface. There are two things you need to implement: the plugin name (by overriding the `name` property), and the `validate()` method. @@ -119 +148 @@ The communication protocol between the AWS CDK core module and your policy tool -The framework will call `validate()`, passing an `IValidationContextBeta1` object. The location of the templates to be validated is given by `templatePaths`. The plugin should return an instance of `ValidationPluginReportBeta1`. This object represents the report that the user wil receive at the end of the synthesis. +The framework will call `validate()`, passing an `IPolicyValidationContext` object. The location of the templates to be validated is given by `templatePaths`. The plugin should return an instance of `PolicyValidationPluginReport`. This object represents the report that the user wil receive at the end of the synthesis. @@ -122 +151 @@ The framework will call `validate()`, passing an `IValidationContextBeta1` objec - validate(context: IPolicyValidationContextBeta1): PolicyValidationReportBeta1 { + validate(context: IPolicyValidationContext): PolicyValidationPluginReport {