AWS cdk documentation change
Summary
Updated documentation structure, fixed typographical quotes, removed redundant 'Topics' sections, and improved formatting of links/grammar
Security assessment
Changes are primarily structural/grammatical (e.g., apostrophe fixes, section reorganization). No new security controls, vulnerabilities, or mitigations were introduced. Existing security-related content about plugin risks and validation recommendations remains unchanged in substance.
Diff
diff --git a/cdk/v2/guide/policy-validation-synthesis.md b/cdk/v2/guide/policy-validation-synthesis.md index 80ca9a7a7..b59e9e3ed 100644 --- a//cdk/v2/guide/policy-validation-synthesis.md +++ b//cdk/v2/guide/policy-validation-synthesis.md @@ -5 +5 @@ -Policy validationFor application developersFor plugin authors +Policy validation at synthesis timeFor application developersFor plugin authors @@ -11,11 +10,0 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -###### Topics - - * Policy validation at synthesis time - - * For application developers - - * For plugin authors - - - - @@ -26 +15 @@ If you or your organization use any policy validation tool, such as [AWS CloudFo -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 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. @@ -34,9 +22,0 @@ This feature is considered experimental, and both the plugin API and the format -###### Topics - - * For application developers - - * For plugin authors - - - - @@ -63 +43 @@ 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. +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. @@ -67 +47 @@ Other than modifying the cloud assembly, plugins can do anything that your AWS C -Using the [CfnGuardValidator](https://github.com/cdklabs/cdk-validator-cfnguard) plugin allows you to use [AWS CloudFormation Guard](https://github.com/aws-cloudformation/cloudformation-guard) to perform policy validations. The `CfnGuardValidator` plugin comes with a select set of [AWS Control Tower proactive controls](https://docs.aws.amazon.com/controltower/latest/userguide/proactive-controls.html) built in. The current set of rules can be found in the [project documentation](https://github.com/cdklabs/cdk-validator-cfnguard/blob/main/README.md). As mentioned in Policy validation at synthesis time, we recommend that organizations set up a more authoritative method of validation using [AWS CloudFormation hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks.html). +Using the [`CfnGuardValidator`](https://github.com/cdklabs/cdk-validator-cfnguard) plugin allows you to use [AWS CloudFormation Guard](https://github.com/aws-cloudformation/cloudformation-guard) to perform policy validations. The `CfnGuardValidator` plugin comes with a select set of [AWS Control Tower proactive controls](https://docs.aws.amazon.com/controltower/latest/userguide/proactive-controls.html) built in. The current set of rules can be found in the [project documentation](https://github.com/cdklabs/cdk-validator-cfnguard/blob/main/README.md). As mentioned in Policy validation at synthesis time, we recommend that organizations set up a more authoritative method of validation using [AWS CloudFormation hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/hooks.html). @@ -131 +111 @@ If you choose the JSON format, the AWS CDK will print the policy validation repo -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 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. @@ -159 +139 @@ The framework will call `validate()`, passing an `IValidationContextBeta1` objec -Note that plugins aren't allowed to modify anything in the cloud assembly. Any attempt to do so will result in synthesis failure. +Note that plugins aren’t allowed to modify anything in the cloud assembly. Any attempt to do so will result in synthesis failure. @@ -169 +149 @@ An example scenario to illustrate a possible exemption mechanism: - * An organization has a rule that public Amazon S3 buckets aren't allowed, _except_ for under certain scenarios. + * An organization has a rule that public Amazon S3 buckets aren’t allowed, _except_ for under certain scenarios.