AWS controltower documentation change
Summary
Added EventBridge integration for drift notifications, updated references from SNS to generic 'drift notification', added guidance for creating EventBridge rules, and included version-specific behavior notes for LZ4.0+ customers
Security assessment
The changes introduce EventBridge as a new notification channel for governance drift detection, which improves monitoring capabilities but does not directly address a specific security vulnerability. The documentation adds guidance for security-related configuration monitoring but does not reference patching vulnerabilities or mitigating active threats.
Diff
diff --git a/controltower/latest/userguide/governance-drift.md b/controltower/latest/userguide/governance-drift.md index a4de580dd..32cb3c79d 100644 --- a//controltower/latest/userguide/governance-drift.md +++ b//controltower/latest/userguide/governance-drift.md @@ -5 +5 @@ -Moved member accountRemoved member accountUnplanned update to managed SCPSCP detached from managed OUDeleted Foundational OUSecurity Hub control driftControl policy driftTrusted access disabledInheritance drift on enabled baselinesInheritance drift on enabled controls +Moved member accountRemoved member accountUnplanned update to managed SCPSCP detached from managed OUDeleted Foundational OUSecurity Hub control driftControl policy driftTrusted access disabledInheritance drift on enabled baselinesInheritance drift on enabled controlsEventBridge creation @@ -23,0 +24,4 @@ The next sections provide detail about these types of drift that AWS Control Tow +###### Note + +AWS Control Tower will stop sending drift notifications to SNS topic for LZ4.0+ customers and will start sending drift notifications to EventBridge in the management account instead. To see sample events and guidance on how to receive drift notifications through EventBridge please see the section below on **EventBridge creation**. + @@ -65 +69 @@ AWS Control Tower reports _control drift_ regarding controls implemented with re -When baseline configurations on a member account are different than those applied to the parent OU, AWS Control Tower reports inheritance drift for enabled baselines (resource configurations) on those OUs and accounts. For more information about baselines, see [Types of baselines](https://docs.aws.amazon.com/controltower/latest/userguide/types-of-baselines.html). +When baseline configurations on a member account are different than those applied to the parent OU, AWS Control Tower reports inheritance drift for enabled baselines (resource configurations) on those OUs and accounts. For more information about baselines, see [Types of baselines](https://docs.aws.amazon.com//controltower/latest/userguide/types-of-baselines.html). @@ -88,0 +93,4 @@ When enabled control configurations on a member account are different than those +###### Note + +For customers on LZ 4.0+, AWS Control Tower will not send move account drift notifications for Account Factory accounts without AWSControlTowerBaseline. + @@ -91 +99 @@ This type of drift occurs on the account rather than the OU. This type of drift -The following is an example of the Amazon SNS notification when this type of drift is detected. +The following is an example of the drift notification when this type of drift is detected. @@ -137 +145 @@ The field name `MasterAccountID` has been changed to `ManagementAccountID` to co -This type of drift can occur when a member account is removed from a registered AWS Control Tower organizational unit. The following example shows the Amazon SNS notification when this type of drift is detected. +This type of drift can occur when a member account is removed from a registered AWS Control Tower organizational unit. The following example shows the drift notification when this type of drift is detected. @@ -167 +175 @@ In Service Catalog, the Account Factory provisioned product that represents the -This type of drift can occur when an SCP for a control is updated in the AWS Organizations console or programmatically using the AWS CLI or one of the AWS SDKs. The following is an example of the Amazon SNS notification when this type of drift is detected. +This type of drift can occur when an SCP for a control is updated in the AWS Organizations console or programmatically using the AWS CLI or one of the AWS SDKs. The following is an example of the drift notification when this type of drift is detected. @@ -196 +204 @@ When this type of drift occurs in an OU with more than 1000 accounts, resolve it -This type of drift can occur when an SCP for a control has been detached from an OU that's managed by AWS Control Tower. This occurrence is especially common when you're working from outside of the AWS Control Tower console. The following is an example of the Amazon SNS notification when this type of drift is detected. +This type of drift can occur when an SCP for a control has been detached from an OU that's managed by AWS Control Tower. This occurrence is especially common when you're working from outside of the AWS Control Tower console. The following is an example of the drift notification when this type of drift is detected. @@ -225 +233 @@ When this type of drift occurs in an OU with more than 1000 accounts, resolve it -This type of drift applies only to AWS Control Tower Foundational OUs, such as the Security OU. It can occur if a Foundational OU is deleted outside of the AWS Control Tower console. Foundational OUs cannot be moved without creating this type of drift, because moving an OU is the same as deleting it and then adding it someplace else. When you resolve the drift by updating your landing zone, AWS Control Tower replaces the Foundational OU in the original location. The following example shows an Amazon SNS notification you may receive when this type of drift is detected. +This type of drift applies only to AWS Control Tower Foundational OUs, such as the Security OU. It can occur if a Foundational OU is deleted outside of the AWS Control Tower console. Foundational OUs cannot be moved without creating this type of drift, because moving an OU is the same as deleting it and then adding it someplace else. When you resolve the drift by updating your landing zone, AWS Control Tower replaces the Foundational OU in the original location. The following example shows a drift notification you may receive when this type of drift is detected. @@ -248 +256 @@ This type of drift occurs when a control that's part of the **AWS Security Hub S -Security Hub control drift also can be detected if AWS Control Tower has not received a status update from Security Hub in more than 24 hours. If those findings are not received as expected, AWS Control Tower verifies that the control is in drift. The following example shows an Amazon SNS notification you may receive when this type of drift is detected. +Security Hub control drift also can be detected if AWS Control Tower has not received a status update from Security Hub in more than 24 hours. If those findings are not received as expected, AWS Control Tower verifies that the control is in drift. The following example shows a drift notification you may receive when this type of drift is detected. @@ -278 +286 @@ This type of drift is not reported for SCP-based controls. -The following example shows an Amazon SNS notification you may receive when this type of drift is detected. +The following example shows a drift notification you may receive when this type of drift is detected. @@ -311 +319 @@ When trusted access is disabled, AWS Control Tower no longer receives change eve -###### Example: Amazon SNS notification +###### Example: drift notification @@ -313 +321 @@ When trusted access is disabled, AWS Control Tower no longer receives change eve -The following is an example of the Amazon SNS notification that you receive when this type of drift occurs. +The following is an example of the drift notification that you receive when this type of drift occurs. @@ -334 +342 @@ This type of drift can occur to AWS Control Tower OUs and accounts. -AWS Control Tower notifies you when this type of drift occurs. For almost all cases of inheritance drift, you will receive an SNS notification for _Moved member account_ drift. That's because this type of drift typically occurs when an account has been moved, or an account fails enrollment. +AWS Control Tower notifies you when this type of drift occurs. For almost all cases of inheritance drift, you will receive a drift notification for _Moved member account_ drift. That's because this type of drift typically occurs when an account has been moved, or an account fails enrollment. @@ -342 +350 @@ In the AWS Control Tower console, you can view this inherited drift status in th -To view drift status programmatically, you can call the [`ListEnabledBaselines`](https://docs.aws.amazon.com/controltower/latest/APIReference/API_ListEnabledBaselines.html) API to view statuses for the enabled baselines on your OUs. To view statuses for individual accounts programmatically with the `ListEnabledBaselines` API, use the `includeChildren` flag. +To view drift status programmatically, you can call the [`ListEnabledBaselines`](https://docs.aws.amazon.com//controltower/latest/APIReference/API_ListEnabledBaselines.html) API to view statuses for the enabled baselines on your OUs. To view statuses for individual accounts programmatically with the `ListEnabledBaselines` API, use the `includeChildren` flag. @@ -344 +352 @@ To view drift status programmatically, you can call the [`ListEnabledBaselines`] -You can resolve this type of drift programmatically, by calling the [`ResetEnabledBaseline`](https://docs.aws.amazon.com/controltower/latest/APIReference/API_ResetEnabledBaseline.html) API. +You can resolve this type of drift programmatically, by calling the [`ResetEnabledBaseline`](https://docs.aws.amazon.com//controltower/latest/APIReference/API_ResetEnabledBaseline.html) API. @@ -352 +360 @@ This type of drift can occur to AWS Control Tower OUs and accounts. -AWS Control Tower notifies you when this type of drift occurs. For almost all cases of inheritance drift, you will receive an SNS notification for _Moved member account_ drift. That's because this type of drift typically occurs when an account has been moved, or an account fails enrollment. +AWS Control Tower notifies you when this type of drift occurs. For almost all cases of inheritance drift, you will receive a drift notification for _Moved member account_ drift. That's because this type of drift typically occurs when an account has been moved, or an account fails enrollment. @@ -360 +368,71 @@ In the AWS Control Tower console, you can view this inherited drift status in th -To view inherited drift status for enabled controls programmatically, you can call the [`ListEnabledControls`](https://docs.aws.amazon.com/controltower/latest/APIReference/API_ListEnabledControls.html) API to view statuses for the enabled controls on your OUs. To view statuses for individual accounts programmatically with the `ListEnabledControls` API, use the `includeChildren` flag. +To view inherited drift status for enabled controls programmatically, you can call the [`ListEnabledControls`](https://docs.aws.amazon.com//controltower/latest/APIReference/API_ListEnabledControls.html) API to view statuses for the enabled controls on your OUs. To view statuses for individual accounts programmatically with the `ListEnabledControls` API, use the `includeChildren` flag. + +You can resolve this type of inheritance drift programmatically, by calling the [`ResetEnabledControl`](https://docs.aws.amazon.com//controltower/latest/APIReference/API_ResetEnabledControl.html) API. + +## EventBridge creation + +###### Note + +EventBridge is enabled for LZ4.0+ customers only. + +Example EventBridge format for AWS Control Tower + + + { + "version": "0", + "id": "cd4d811e-ab12-322b-8255-872ce65b1bc8", + "detail-type": "Drift Detected", + "source": "aws.controltower", + "account": "111122223333", + "time": "2018-03-22T00:38:11Z", + "region": "us-east-1", + "resources": [], + "detail": { + "message" : "AWS Control Tower has detected that your member account '[email protected] (012345678909)' has been moved from organizational unit 'Sandbox (ou-0123-eEXAMPLE)' to 'Security (ou-3210-1EXAMPLE)'. For more information, including steps to resolve this issue, see 'https://docs.aws.amazon.com/console/controltower/move-account'", + "managementAccountId" : "012345678912", + "organizationId" : "o-123EXAMPLE", + "driftType" : "ACCOUNT_MOVED_BETWEEN_OUS", + "remediationStep" : "Re-register this organizational unit (OU), or if the OU has more than 1000 accounts, you must update the provisioned product in Account Factory.", + "accountId" : "012345678909", + "sourceId" : "012345678909", + "destinationId" : "ou-3210-1EXAMPLE" + } + } + + +Guidance to create EventBridge rule to receive drift notifications: + +###### To create an EventBridge rule for drift notifications + + 1. Open the **Amazon EventBridge Console** : + + 2. In the navigation pane, choose **Rules**. + + 3. Choose **Create rule**. + + 4. Enter a name and description for the rule. + + 5. For **Rule type** , choose **Rule with an event pattern**. + + 6. **Define the Event Source** : + + * For "Event source", select **AWS services** as the event source. + + * For "AWS service name", select **AWS Control Tower**. + + * For "Event type", select **Drift Detected** + + 7. **Select the Target** : + + * For **Target types** , choose **AWS service** , and for **Select a target** , choose a target such as an drift notification topic or Lambda function. The target is triggered when an event is received that matches the event pattern defined in the rule. + + * Depending on the target you selected, provide the necessary configuration details, such as the Lambda function name or the drift notification topic ARN. + + 8. **Review and Create the Rule** : + + * Review the details of your rule and make any necessary changes. + + * Once you're satisfied, click on **Create rule** to save the new EventBridge rule. + + + @@ -362 +440 @@ To view inherited drift status for enabled controls programmatically, you can ca -You can resolve this type of inheritance drift programmatically, by calling the [`ResetEnabledControl`](https://docs.aws.amazon.com/controltower/latest/APIReference/API_ResetEnabledControl.html) API. +After creating the rule, it will start monitoring for the specified AWS Control Tower events and trigger the selected target action when drift events occur.