From 704ed583478044d2b5b7ab26e6f03fc643bd41d1 Mon Sep 17 00:00:00 2001 From: Benjamin Morris Date: Wed, 22 May 2024 11:41:58 -0700 Subject: [PATCH] cleanup and documentation for the proactive rules feature --- README.md | 23 ++++++++---- developer_notes.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++ pyproject.toml | 2 +- rdk/__init__.py | 2 +- rdk/rdk.py | 15 +++++++- 5 files changed, 122 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f2f4e53..1add22b 100644 --- a/README.md +++ b/README.md @@ -517,26 +517,36 @@ To use this generated lambda layer, add the flag `rdk -f regions.yaml deploy LP3_TestRule_P39_lib --generated-lambda-layer` If you created layer with a custom name (by running -`rdk init --custom-lambda-layer`, add a similar `custom-lambda-layer` +`rdk init --custom-lambda-layer`), add a similar `custom-lambda-layer` flag when running deploy. +### Proactive Rules + +As of version `1.0.0`, RDK now supports proactive rule creation. Proactive evaluation mode only applies to CloudFormation template deployment, and does not apply to already-deployed resources. Proactive rules are therefore only evaluated as "configuration changes", not periodic rules. + +You can create a proactive rule using `rdk create`'s flag `--evaluation-mode` and specifying an argument as outlined by `rdk create`'s help text. This will set the evaluation mode in the `parameters.json`. + +For more detail on proactive rules, see [this blog post](https://aws.amazon.com/blogs/mt/how-to-use-aws-config-proactive-rules-and-aws-cloudformation-hooks-to-prevent-creation-of-non-complaint-cloud-resources/). Note that the presence of a proactive rule does NOT automatically block misconfigured resources. You need to configure [CloudFormation Hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/what-is-cloudformation-hooks.html) in order to use the Config rule to assess (and potentially block) the CFT deployment. + +Note that proactive rules are **NOT** supported for Organization Rules, as of May 2024. This is a limitation of the Config service. Proactive evaluation mode is supported for single-account custom and managed rules. + ## Support & Feedback This project is maintained by AWS Solution Architects and Consultants. It is not part of an AWS service and support is provided best-effort by the maintainers. To post feedback, submit feature ideas, or report bugs, -please use the [Issues -section](https://github.com/awslabs/aws-config-rdk/issues) of this repo. +please use the [Issues section](https://github.com/awslabs/aws-config-rdk/issues) of this repo. ## Contributing -email us at if you have any questions. We +Email us at if you have any questions. We are happy to help and discuss. ## Contacts -- **Benjamin Morris** - [bmorrissirromb](https://github.com/bmorrissirromb) - _current maintainer_ -- **Julio Delgado Jr** - [tekdj7](https://github.com/tekdj7) - _current maintainer_ +- **Benjamin Morris** - [bmorrissirromb](https://github.com/bmorrissirromb) - _current lead maintainer_ +- **Carlo DePaolis** - [depaolism](https://github.com/depaolism) - _current maintainer_ +- **Nima Fotouhi** - [nimaft](https://github.com/nimaft) - _current maintainer_ ## Past Contributors @@ -550,6 +560,7 @@ are happy to help and discuss. - **Sandeep Batchu** - [batchus](https://github.com/batchus) - _maintainer_ - **Mark Beacom** - [mbeacom](https://github.com/mbeacom) - _maintainer_ - **Ricky Chau** - [rickychau2780](https://github.com/rickychau2780) - _maintainer_ +- **Julio Delgado Jr** - [tekdj7](https://github.com/tekdj7) - _maintainer_ ## License diff --git a/developer_notes.md b/developer_notes.md index 0bc01c6..0849020 100644 --- a/developer_notes.md +++ b/developer_notes.md @@ -48,3 +48,92 @@ To release a new version of RDK... 2. Make your changes 3. `poetry build` # builds a wheel package inside of the dist folder 4. `pip install --force-reinstall ` # optionally, use `--user` to install for just the current user. + +## Manual Testing Scenarios + +Note: before running these, make sure to set your AWS credentials and region appropriately. + +These are not a replacement for unit tests, but because RDK inherently relies on CloudFormation, some level of end-to-end testing is necessary. + +1. Basic periodic custom rule creation and deployment +```powershell +$rule="myAutomationTest" # This is gitignored +$runtime="python3.12" +$frequency="TwentyFour_Hours" +rdk create $rule --runtime $runtime --maximum-frequency $frequency +rdk deploy $rule +# It should deploy a CloudFormation stack successfully. +rdk undeploy $rule --force +Remove-Item $rule -recurse +``` +2. Basic configuration-change custom rule creation and deployment +```powershell +$rule="myAutomationTest" # This is gitignored +$runtime="python3.12" +$test_event_type = "AWS::EC2::Instance" +rdk create $rule --runtime $runtime --resource-types $test_event_type +rdk deploy $rule +# It should deploy a CloudFormation stack successfully. +rdk undeploy $rule --force +Remove-Item $rule -recurse +``` +3. Managed rule creation and deployment +```powershell +$rule="myAutomationTest" # This is gitignored +$managed_rule="ACCESS_KEYS_ROTATED" +$frequency="TwentyFour_Hours" +rdk create $rule --source-identifier $managed_rule --maximum-frequency $frequency +rdk deploy $rule +# It should deploy a CloudFormation stack successfully. +rdk undeploy $rule --force +Remove-Item $rule -recurse +``` + +4. Deploy a proactive rule +```powershell +$rule="myAutomationTest" # This is gitignored +$runtime="python3.12" +$test_event_type = "AWS::S3::Bucket" +$evaluation_mode="PROACTIVE" +rdk create $rule --runtime $runtime --evaluation-mode $evaluation_mode --resource-types $test_event_type +rdk deploy $rule +# It should deploy a CloudFormation stack successfully. +rdk undeploy $rule --force +Remove-Item $rule -recurse # clean up the directory for future testing +``` + +5. Deploy a proactive rule as a periodic rule (should fail) +```powershell +$rule="myAutomationTest" # This is gitignored +$runtime="python3.12" +$evaluation_mode="BOTH" +$frequency="TwentyFour_Hours" +rdk create $rule --runtime $runtime --evaluation-mode $evaluation_mode --maximum-frequency $frequency +# It should fail at create time +``` + +6. Deploy a proactive managed rule +```powershell +$rule="myAutomationTest" # This is gitignored +$managed_rule="S3_BUCKET_LOGGING_ENABLED" +$evaluation_mode="BOTH" +$test_event_type = "AWS::S3::Bucket" +rdk create $rule --source-identifier $managed_rule --resource-types $test_event_type --evaluation-mode $evaluation_mode +rdk deploy $rule +# It should deploy a CloudFormation stack successfully. +rdk undeploy $rule --force +Remove-Item $rule -recurse +``` + +7. Deploy a proactive managed Organization rule +```powershell +$rule="myAutomationTest" # This is gitignored +$managed_rule="S3_BUCKET_LOGGING_ENABLED" +$evaluation_mode="PROACTIVE" +$test_event_type = "AWS::S3::Bucket" +$test_management_account = "730335412016" +rdk create $rule --source-identifier $managed_rule --resource-types $test_event_type --evaluation-mode $evaluation_mode +rdk deploy-organization $rule --excluded-accounts $test_management_account +# It should fail to deploy due to an unsupported evaluation mode. +Remove-Item $rule -recurse +``` \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 865748a..ff8aa02 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,4 +1,4 @@ -# Copyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved. +# Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at # diff --git a/rdk/__init__.py b/rdk/__init__.py index b10b944..5d7d9c3 100644 --- a/rdk/__init__.py +++ b/rdk/__init__.py @@ -6,4 +6,4 @@ # # or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -MY_VERSION = "2" +MY_VERSION = "0.17.12" diff --git a/rdk/rdk.py b/rdk/rdk.py index 3ad06bc..444fba2 100644 --- a/rdk/rdk.py +++ b/rdk/rdk.py @@ -1221,7 +1221,7 @@ def create(self): if not self.args.source_identifier: if not self.args.runtime: - print("Runtime is required for 'create' command.") + print("Runtime is required for 'create' command (unless deploying a managed rule).") return 1 extension_mapping = { @@ -2209,6 +2209,13 @@ def deploy_organization(self): for rule_name in rule_names: rule_params, cfn_tags = self.__get_rule_parameters(rule_name) + if "EvaluationMode" in rule_params: + if rule_params["EvaluationMode"] in ["PROACTIVE", "BOTH"]: + print( + "Proactive evaluation mode is not supported for Organization rules. Please update your rule parameters." + ) + sys.exit(1) + # create CFN Parameters common for Managed and Custom source_events = "NONE" if "Remediation" in rule_params: @@ -3468,6 +3475,12 @@ def __parse_rule_args(self, is_required): print("Rule names must be 128 characters or fewer.") sys.exit(1) + if self.args.evaluation_mode in ["PROACTIVE", "BOTH"] and self.args.resource_types is None: + print( + "You are attempting to create a proactive rule without a configuration-change trigger. This is not supported. Please revise your request." + ) + exit(1) + resource_type_error = "" if self.args.resource_types: for resource_type in self.args.resource_types.split(","):