|
| 1 | +# Shield Organization<!-- omit in toc --> |
| 2 | + |
| 3 | +Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: CC-BY-SA-4.0 |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Table of Contents](#table-of-contents) |
| 8 | +- [Introduction](#introduction) |
| 9 | +- [Deployed Resource Details](#deployed-resource-details) |
| 10 | +- [Implementation Instructions](#implementation-instructions) |
| 11 | +- [References](#references) |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Introduction |
| 16 | + |
| 17 | +The Shield Advanced solution will automate enabling Amazon Shield Advanced by deploying and configuring for the chosen AWS accounts or all the existing and future AWS Organization accounts. |
| 18 | + |
| 19 | +**Key solution features:** |
| 20 | + |
| 21 | +- Deploys to all specified accounts accounts or within an AWS Organization |
| 22 | +- Configures up to 5 Protection Groups. |
| 23 | +- Dynamically figures out which S3 buckets are configured to which account. |
| 24 | +- Configures DDOS Response Team (DRT) access for accounts and buckets where applicable. |
| 25 | +- Configures contacts/emergency contacts |
| 26 | +- Enables Proactive Support |
| 27 | +- Assumes a role in each account to configure Shield Advanced. |
| 28 | +- Ability to disable shield within all accounts and regions via a parameter and CloudFormation update event. |
| 29 | + |
| 30 | +--- |
| 31 | + |
| 32 | +## Deployed Resource Details |
| 33 | + |
| 34 | + |
| 35 | + |
| 36 | +### 1.0 Organization Management Account<!-- omit in toc --> |
| 37 | + |
| 38 | +#### 1.1 AWS CloudFormation<!-- omit in toc --> |
| 39 | + |
| 40 | +- All resources are deployed via AWS CloudFormation as a `StackSet` and `Stack Instance` within the `management account` or a CloudFormation `Stack` within a specific account. |
| 41 | +- The [Customizations for AWS Control Tower](https://aws.amazon.com/solutions/implementations/customizations-for-aws-control-tower/) solution deploys all templates as a CloudFormation `StackSet`. |
| 42 | +- For parameter details, review the [AWS CloudFormation templates](templates/). |
| 43 | + |
| 44 | +#### 1.2 IAM Roles<!-- omit in toc --> |
| 45 | + |
| 46 | +- The `Lambda IAM Role` is used by the Lambda function to enable the shield Delegated Administrator Account within each region provided. |
| 47 | +- The `Configuration IAM Role` is assumed by the Lambda function to configure Shield Advanced. |
| 48 | + |
| 49 | +#### 1.3 Regional Event Rules<!-- omit in toc --> |
| 50 | + |
| 51 | +- The `Organization Compliance Scheduled Event Rule` triggers the `AWS Lambda Function` to capture AWS Account status updates (e.g. suspended to active). |
| 52 | + - A parameter is provided to set the schedule frequency. |
| 53 | + - See the [Instructions to Manually Run the Lambda Function](#instructions-to-manually-run-the-lambda-function) for triggering the `AWS Lambda Function` before the next scheduled run time. |
| 54 | + |
| 55 | +#### 1.4 Dead Letter Queue (DLQ)<!-- omit in toc --> |
| 56 | + |
| 57 | +- SQS dead letter queue used for retaining any failed Lambda events. |
| 58 | + |
| 59 | +#### 1.5 AWS Lambda Function<!-- omit in toc --> |
| 60 | + |
| 61 | +- The Lambda function includes logic to enable and configure shield. |
| 62 | + |
| 63 | +#### 1.6 Lambda CloudWatch Log Group<!-- omit in toc --> |
| 64 | + |
| 65 | +- All the `AWS Lambda Function` logs are sent to a CloudWatch Log Group `</aws/lambda/<LambdaFunctionName>` to help with debugging and traceability of the actions performed. |
| 66 | +- By default the `AWS Lambda Function` will create the CloudWatch Log Group and logs are encrypted with a CloudWatch Logs service managed encryption key. |
| 67 | +- Parameters are provided for changing the default log group retention and encryption KMS key. |
| 68 | + |
| 69 | +#### 1.7 Alarm SNS Topic<!-- omit in toc --> |
| 70 | + |
| 71 | +- SNS Topic used to notify subscribers when messages hit the DLQ. |
| 72 | + |
| 73 | +#### 1.8 Shield<!-- omit in toc --> |
| 74 | + |
| 75 | +- The Shield Advanced Solution is configured globally for each account specified in the parameter Accounts to Update. |
| 76 | +- Note to configure new accounts update the template parameter Accounts to Update with the account number or ALL and include resources or Protection Groups specific to that account. |
| 77 | + |
| 78 | +#### 1.9 Lambda Layer<!-- omit in toc --> |
| 79 | + |
| 80 | +- The python boto3 SDK lambda layer to enable capability for lambda to enable all elements of the shield service. |
| 81 | +- This is downloaded during the deployment process and packaged into a layer that is used by the lambda function in this solution. |
| 82 | +- The shield API available in the current lambda environment (as of 01/19/2023) is boto3-1.20.32, however, enhanced functionality of the shield API used in this solution requires at least 1.26.18 (see references below). |
| 83 | +- Note: Future revisions to this solution will remove this layer when boto3 is updated within the lambda environment. |
| 84 | + |
| 85 | +--- |
| 86 | + |
| 87 | +### 2.0 All Existing and Future Organization Accounts (Per Configuration in pShieldAccountsToProtect)<!-- omit in toc --> |
| 88 | + |
| 89 | +#### 2.1 AWS CloudFormation<!-- omit in toc --> |
| 90 | + |
| 91 | +- See [1.1 AWS CloudFormation](#11-aws-cloudformation) |
| 92 | + |
| 93 | +#### 2.2 Configuration IAM Role<!-- omit in toc --> |
| 94 | + |
| 95 | +- See [2.2 AWS CloudFormation](#22-configuration-iam-role) |
| 96 | + |
| 97 | +#### 2.3 Shield Advanced<!-- omit in toc --> |
| 98 | + |
| 99 | +- Shield Advanced is enabled globally for each account specificied. |
| 100 | + |
| 101 | +--- |
| 102 | + |
| 103 | +## Implementation Instructions |
| 104 | + |
| 105 | +### Prerequisites<!-- omit in toc --> |
| 106 | + |
| 107 | +1. [Download and Stage the SRA Solutions](../../../docs/DOWNLOAD-AND-STAGE-SOLUTIONS.md). **Note:** This only needs to be done once for all the solutions. |
| 108 | +2. Verify that the [SRA Prerequisites Solution](../../common/common_prerequisites/) has been deployed. |
| 109 | + |
| 110 | +### Solution Deployment<!-- omit in toc --> |
| 111 | + |
| 112 | +Choose a Deployment Method: |
| 113 | + |
| 114 | +- [AWS CloudFormation](#aws-cloudformation) |
| 115 | +- [Customizations for AWS Control Tower](../../../docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md) |
| 116 | + |
| 117 | +#### AWS CloudFormation<!-- omit in toc --> |
| 118 | + |
| 119 | +In the `management account (home region)`, launch an AWS CloudFormation **Stack** using one of the options below: |
| 120 | + |
| 121 | +- **Option 1:** (Recommended) Use the [sra-shield-advanced-main-ssm.yaml](templates/sra-shield-advanced-main-ssm.yaml) template. This is a more automated approach where some of the CloudFormation parameters are populated from SSM parameters created. |
| 122 | + Note: open [sra-shield-advanced-main-ssm.yaml](templates/sra-shield-advanced-main-ssm.yaml) template and update the following parameters (pShieldDRTLogBuckets, pResourcesToProtect, pShieldAccountsToProtect) based on your environment by the |
| 123 | + [SRA Prerequisites Solution](../../common/common_prerequisites/). |
| 124 | + |
| 125 | + ```bash |
| 126 | + aws cloudformation deploy --template-file $HOME/aws-sra-examples/aws_sra_examples/solutions/shield_advanced/shield_advanced/templates/sra-shield-advanced-main-ssm.yaml --stack-name sra-shield-advanced-main-ssm --capabilities CAPABILITY_NAMED_IAM |
| 127 | + ``` |
| 128 | + |
| 129 | +#### Verify Solution Deployment<!-- omit in toc --> |
| 130 | + |
| 131 | +1. Log into the each account where Shield Advanced is Configured and navigate to the WAF service console |
| 132 | + 1. Navigate to `Overview` section of `AWS Shield` header |
| 133 | + 2. Verify `Subscribe to Shield Advanced` status is `Complete` |
| 134 | + 3. If configured verify `Add resources to protect` status is set to `Complete` |
| 135 | + 4. If configured verify `Configure AWS SRT support` status is set to `Complete` |
| 136 | + 5. If configured verify `IAM Role` for DRT Access is listed and `S3 buckets SRT is authorized to access` are listed |
| 137 | + 6. If configured verify `Proactive engagement status` status is `Complete` and the Email, Phone Number, and Notes match the values from the parameters |
| 138 | + |
| 139 | +#### Solution Update Instructions<!-- omit in toc --> |
| 140 | + |
| 141 | +1. [Download and Stage the SRA Solutions](../../../docs/DOWNLOAD-AND-STAGE-SOLUTIONS.md). **Note:** Get the latest code and run the staging script. |
| 142 | +2. Update the existing CloudFormation Stack or CFCT configuration. **Note:** Make sure to update the `SRA Solution Version` parameter and any new added parameters. |
| 143 | + |
| 144 | +#### Solution Delete Instructions<!-- omit in toc --> |
| 145 | + |
| 146 | +1. In the `management account (home region)`, delete the AWS CloudFormation **Stack** (`sra-shield-advanced-main-ssm`. |
| 147 | +2. In the `management account (home region)`, delete stack instances from the the AWS CloudFormation **StackSet** (`sra-shield-advanced-main-ssm`. |
| 148 | +3. In the `management account (home region)`, delete AWS CloudFormation **StackSet** (`sra-shield-advanced-main-ssm` or `sra-shield-advanced-main`). |
| 149 | +4. In the `management account (home region)`, verify that the Lambda function processing is complete by confirming no more CloudWatch logs are generated. |
| 150 | +5. In the `management account (home region)`, delete the AWS CloudWatch **Log Group** (e.g. /aws/lambda/<solution_name>) for the Lambda function deployed. |
| 151 | + |
| 152 | +#### Instructions to Manually Run the Lambda Function<!-- omit in toc --> |
| 153 | + |
| 154 | +1. In the `management account (home region)`. |
| 155 | +2. Navigate to the AWS Lambda Functions page. |
| 156 | +3. Select the `checkbox` next to the Lambda Function and select `Test` from the `Actions` menu. |
| 157 | +4. Scroll down to view the `Test event`. |
| 158 | +5. Click the `Test` button to trigger the Lambda Function with the default values. |
| 159 | +6. Verify that the updates were successful within the expected account(s). |
| 160 | + |
| 161 | +--- |
| 162 | + |
| 163 | +## References |
| 164 | + |
| 165 | +- [Shield Advanced](https://aws.amazon.com/shield/features/#AWS_Shield_Advanced) |
| 166 | +- [Managing AWS SDKs in Lambda Functions](https://docs.aws.amazon.com/lambda/latest/operatorguide/sdks-functions.html) |
| 167 | +- [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) |
| 168 | +- [Python Boto3 SDK changelog](https://github.com/boto/boto3/blob/develop/CHANGELOG.rst) |
| 169 | +- [AWS Regions where Lambda code scanning is currently available](https://docs.aws.amazon.com/shield/latest/user/shield_regions.html) |
0 commit comments