Skip to content

Commit bc012a1

Browse files
author
Justin
committed
init
1 parent f20a377 commit bc012a1

File tree

15 files changed

+4290
-0
lines changed

15 files changed

+4290
-0
lines changed

‎aws_sra_examples/solutions/shield_advanced/shield_advanced/README.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
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+
![Architecture](./documentation/shield-org.png)
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 within the delegated administrator account and all member accounts.
48+
- The `Event Rule IAM Role` is assumed by EventBridge to forward Global events to the `Home Region` default Event Bus.
49+
50+
#### 1.3 Regional Event Rules<!-- omit in toc -->
51+
52+
- The `Organization Compliance Scheduled Event Rule` triggers the `AWS Lambda Function` to capture AWS Account status updates (e.g. suspended to active).
53+
- A parameter is provided to set the schedule frequency.
54+
- 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.
55+
56+
#### 1.4 Global Event Rules<!-- omit in toc -->
57+
58+
- If the `Home Region` is different from the `Global Region (e.g. us-east-1)`, then global event rules are created within the `Global Region` to forward events to the `Home Region` default Event Bus.
59+
- The `AWS Organizations Event Rule` forwards AWS Organization account update events.
60+
61+
#### 1.5 Dead Letter Queue (DLQ)<!-- omit in toc -->
62+
63+
- SQS dead letter queue used for retaining any failed Lambda events.
64+
65+
#### 1.6 AWS Lambda Function<!-- omit in toc -->
66+
67+
- The Lambda function includes logic to enable and configure shield.
68+
69+
#### 1.7 Lambda CloudWatch Log Group<!-- omit in toc -->
70+
71+
- 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.
72+
- By default the `AWS Lambda Function` will create the CloudWatch Log Group and logs are encrypted with a CloudWatch Logs service managed encryption key.
73+
- Parameters are provided for changing the default log group retention and encryption KMS key.
74+
75+
#### 1.8 Alarm SNS Topic<!-- omit in toc -->
76+
77+
- SNS Topic used to notify subscribers when messages hit the DLQ.
78+
79+
#### 1.9 Shield<!-- omit in toc -->
80+
81+
- The Shield Advanced Solution is configured globally for each account specified in the parameter Accounts to Update.
82+
- 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.
83+
84+
#### 1.10 Lambda Layer<!-- omit in toc -->
85+
86+
- The python boto3 SDK lambda layer to enable capability for lambda to enable all elements of the shield service.
87+
- This is downloaded during the deployment process and packaged into a layer that is used by the lambda function in this solution.
88+
- 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).
89+
- Note: Future revisions to this solution will remove this layer when boto3 is updated within the lambda environment.
90+
91+
---
92+
93+
### 2.0 Audit Account<!-- omit in toc -->
94+
95+
The example solutions use `Audit Account` instead of `Security Tooling Account` to align with the default account name used within the AWS Control Tower setup process for the Security Account. The Account ID for the `Audit Account` SSM parameter is
96+
populated from the `SecurityAccountId` parameter within the `AWSControlTowerBP-BASELINE-CONFIG` StackSet.
97+
98+
#### 2.1 AWS CloudFormation<!-- omit in toc -->
99+
100+
- See [1.1 AWS CloudFormation](#11-aws-cloudformation)
101+
102+
#### 2.2 Configuration IAM Role<!-- omit in toc -->
103+
104+
- IAM role assumed by the Lambda function within the `management account` to configure shield within each region provided.
105+
106+
#### 2.3 shield (Delegated admin)<!-- omit in toc -->
107+
108+
- shield is enabled in the delegated admin account within each provided region.
109+
- EC2, ECR, Lambda standard and Lambda code scanning is enabled.
110+
111+
---
112+
113+
### 3.0 All Existing and Future Organization Member Accounts<!-- omit in toc -->
114+
115+
#### 3.1 AWS CloudFormation<!-- omit in toc -->
116+
117+
- See [1.1 AWS CloudFormation](#11-aws-cloudformation)
118+
119+
#### 3.2 Configuration IAM Role<!-- omit in toc -->
120+
121+
- See [2.2 AWS CloudFormation](#22-configuration-iam-role)
122+
123+
#### 3.3 shield (Members)<!-- omit in toc -->
124+
125+
- Shield Advanced is enabled globally for each account specificied.
126+
- EC2, ECR, Lambda standard and Lambda code scanning is enabled.
127+
128+
---
129+
130+
## Implementation Instructions
131+
132+
### Prerequisites<!-- omit in toc -->
133+
134+
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.
135+
2. Verify that the [SRA Prerequisites Solution](../../common/common_prerequisites/) has been deployed.
136+
137+
### Solution Deployment<!-- omit in toc -->
138+
139+
Choose a Deployment Method:
140+
141+
- [AWS CloudFormation](#aws-cloudformation)
142+
- [Customizations for AWS Control Tower](../../../docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md)
143+
144+
#### AWS CloudFormation<!-- omit in toc -->
145+
146+
In the `management account (home region)`, launch an AWS CloudFormation **Stack** using one of the options below:
147+
148+
- **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
149+
by the [SRA Prerequisites Solution](../../common/common_prerequisites/).
150+
151+
```bash
152+
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
153+
```
154+
155+
#### Verify Solution Deployment<!-- omit in toc -->
156+
157+
1. Log into the each account where Shield Advanced is Configured and navigate to the WAF service console
158+
1. Navigate to `Overview` section of `AWS Shield` header
159+
2. Verify `Subscribe to Shield Advanced` status is `Complete`
160+
3. If configured verify `Add resources to protect` status is set to `Complete`
161+
4. If configured verify `Configure AWS SRT support` status is set to `Complete`
162+
5. If configured verify `IAM Role` for DRT Access is listed and `S3 buckets SRT is authorized to access` are listed
163+
6. If configured verify `Proactive engagement status` status is `Complete` and the Email, Phone Number, and Notes match the values from the parameters
164+
165+
#### Solution Update Instructions<!-- omit in toc -->
166+
167+
1. [Download and Stage the SRA Solutions](../../../docs/DOWNLOAD-AND-STAGE-SOLUTIONS.md). **Note:** Get the latest code and run the staging script.
168+
2. Update the existing CloudFormation Stack or CFCT configuration. **Note:** Make sure to update the `SRA Solution Version` parameter and any new added parameters.
169+
170+
#### Solution Delete Instructions<!-- omit in toc -->
171+
172+
1. In the `management account (home region)`, delete the AWS CloudFormation **Stack** (`sra-shield-advanced-main-ssm`.
173+
2. In the `management account (home region)`, delete stack instances from the the AWS CloudFormation **StackSet** (`sra-shield-advanced-main-ssm`.
174+
3. In the `management account (home region)`, delete AWS CloudFormation **StackSet** (`sra-shield-advanced-main-ssm` or `sra-shield-advanced-main`).
175+
4. In the `management account (home region)`, verify that the Lambda function processing is complete by confirming no more CloudWatch logs are generated.
176+
5. In the `management account (home region)`, delete the AWS CloudWatch **Log Group** (e.g. /aws/lambda/<solution_name>) for the Lambda function deployed.
177+
178+
#### Instructions to Manually Run the Lambda Function<!-- omit in toc -->
179+
180+
1. In the `management account (home region)`.
181+
2. Navigate to the AWS Lambda Functions page.
182+
3. Select the `checkbox` next to the Lambda Function and select `Test` from the `Actions` menu.
183+
4. Scroll down to view the `Test event`.
184+
5. Click the `Test` button to trigger the Lambda Function with the default values.
185+
6. Verify that the updates were successful within the expected account(s).
186+
187+
---
188+
189+
## References
190+
191+
- [Shield Advanced](https://aws.amazon.com/shield/features/#AWS_Shield_Advanced)
192+
- [Managing AWS SDKs in Lambda Functions](https://docs.aws.amazon.com/lambda/latest/operatorguide/sdks-functions.html)
193+
- [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html)
194+
- [Python Boto3 SDK changelog](https://github.com/boto/boto3/blob/develop/CHANGELOG.rst)
195+
- [AWS Regions where Lambda code scanning is currently available](https://docs.aws.amazon.com/shield/latest/user/shield_regions.html)

‎aws_sra_examples/solutions/shield_advanced/shield_advanced/customizations_for_aws_control_tower/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Customizations for AWS Control Tower<!-- 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+
---
6+
7+
[Customizations for AWS Control Tower Deployment Instructions](../../../../docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md)

‎aws_sra_examples/solutions/shield_advanced/shield_advanced/customizations_for_aws_control_tower/manifest-v2.yaml

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
#Default region for deploying Custom Control Tower: Code Pipeline, Step functions, Lambda, SSM parameters, and StackSets
3+
region: us-east-1
4+
version: 2021-03-15
5+
6+
# Control Tower Custom Resources (Service Control Policies or CloudFormation)
7+
resources:
8+
# -----------------------------------------------------------------------------
9+
# Organization shield
10+
# -----------------------------------------------------------------------------
11+
- name: sra-shield-advanced-main-ssm
12+
resource_file: templates/sra-shield-advanced-main-ssm.yaml
13+
parameters:
14+
- parameter_key: pComplianceFrequency
15+
parameter_value: 7
16+
- parameter_key: pControlTowerRegionsOnly
17+
parameter_value: 'true'
18+
- parameter_key: pCreateLambdaLogGroup
19+
parameter_value: 'false'
20+
- parameter_key: pEnabledRegions
21+
parameter_value: ''
22+
- parameter_key: pLambdaLogGroupKmsKey
23+
parameter_value: ''
24+
- parameter_key: pLambdaLogGroupRetention
25+
parameter_value: '14'
26+
- parameter_key: pLambdaLogLevel
27+
parameter_value: INFO
28+
- parameter_key: pSRAAlarmEmail
29+
parameter_value: ''
30+
- parameter_key: pSRASolutionVersion
31+
parameter_value: v1.0
32+
- parameter_key: pConfigureDRTTeamAccess
33+
parameter_value: 'true'
34+
- parameter_key: pResourcesToProtect
35+
parameter_value: ''
36+
- parameter_key: pShieldAccountsToProtect
37+
parameter_value: ALL
38+
- parameter_key: pShieldDRTRoleName
39+
parameter_value: DRT-Access-Role
40+
- parameter_key: pShieldAutoRenew
41+
parameter_value: ENABLED
42+
- parameter_key: pShieldDRTLogBuckets
43+
parameter_value: ''
44+
- parameter_key: pShieldWarning
45+
parameter_value: Reject
46+
- parameter_key: pStackSetAdminRole
47+
parameter_value: sra-stackset
48+
- parameter_key: pStackExecutionRole
49+
parameter_value: sra-execution
50+
- parameter_key: pProtectionGroup0AccountId
51+
parameter_value: ''
52+
- parameter_key: pProtectionGroup0Id
53+
parameter_value: ''
54+
- parameter_key: pProtectionGroup0Aggregation
55+
parameter_value: ''
56+
- parameter_key: pProtectionGroup0Pattern
57+
parameter_value: ''
58+
- parameter_key: pProtectionGroup0ResourceType
59+
parameter_value: ''
60+
- parameter_key: pProtectionGroup0Members
61+
parameter_value: ''
62+
- parameter_key: pProtectionGroup1AccountId
63+
parameter_value: ''
64+
- parameter_key: pProtectionGroup1Id
65+
parameter_value: ''
66+
- parameter_key: pProtectionGroup1Aggregation
67+
parameter_value: ''
68+
- parameter_key: pProtectionGroup1Pattern
69+
parameter_value: ''
70+
- parameter_key: pProtectionGroup1ResourceType
71+
parameter_value: ''
72+
- parameter_key: pProtectionGroup1Members
73+
parameter_value: ''
74+
- parameter_key: pProtectionGroup2AccountId
75+
parameter_value: ''
76+
- parameter_key: pProtectionGroup2Id
77+
parameter_value: ''
78+
- parameter_key: pProtectionGroup2Aggregation
79+
parameter_value: ''
80+
- parameter_key: pProtectionGroup2Pattern
81+
parameter_value: ''
82+
- parameter_key: pProtectionGroup2ResourceType
83+
parameter_value: ''
84+
- parameter_key: pProtectionGroup2Members
85+
parameter_value: ''
86+
- parameter_key: pProtectionGroup3AccountId
87+
parameter_value: ''
88+
- parameter_key: pProtectionGroup3Id
89+
parameter_value: ''
90+
- parameter_key: pProtectionGroup3Aggregation
91+
parameter_value: ''
92+
- parameter_key: pProtectionGroup3Pattern
93+
parameter_value: ''
94+
- parameter_key: pProtectionGroup3ResourceType
95+
parameter_value: ''
96+
- parameter_key: pProtectionGroup3Members
97+
parameter_value: ''
98+
- parameter_key: pProtectionGroup4AccountId
99+
parameter_value: ''
100+
- parameter_key: pProtectionGroup4Id
101+
parameter_value: ''
102+
- parameter_key: pProtectionGroup4Aggregation
103+
parameter_value: ''
104+
- parameter_key: pProtectionGroup4Pattern
105+
parameter_value: ''
106+
- parameter_key: pProtectionGroup4ResourceType
107+
parameter_value: ''
108+
- parameter_key: pProtectionGroup4Members
109+
parameter_value: ''
110+
- parameter_key: pShieldEnableProactiveEngagement
111+
parameter_value: 'false'
112+
- parameter_key: pShieldProactiveEngagementEmail
113+
parameter_value: ''
114+
- parameter_key: pShieldProactiveEngagementPhoneNumber
115+
parameter_value: ''
116+
- parameter_key: pShieldProactiveEngagementNotes
117+
parameter_value: ''
118+
deploy_method: stack_set
119+
deployment_targets:
120+
accounts:
121+
- REPLACE_ME_ORG_MANAGEMENT_ACCOUNT_NAME

0 commit comments

Comments
 (0)