Skip to content

Commit 7687ee8

Browse files
justin-kontnyJustincyphronix
authored
Added Detective solution (#147)
* init detective * fixed linting issues * fixing some linting issues * added documentation https://github.com/IevIe, fixed linting issues * fixed linting issues * fix for R504 * reformatted files with black * added values in description, updated srl session name * update detective README --------- Co-authored-by: Justin <kontnyj@amazon.com> Co-authored-by: Liam Schneider <liamschn@amazon.com>
1 parent d6ea404 commit 7687ee8

File tree

17 files changed

+2624
-0
lines changed

17 files changed

+2624
-0
lines changed

‎aws_sra_examples/solutions/detective/detective_org/README.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Detective 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 Detective Organization solution will automate enabling Amazon Detective by delegating administration to an account (e.g. Audit or Security Tooling) and configuring Detective for all the existing and future AWS Organization accounts.
18+
19+
**Key solution features:**
20+
21+
- Delegates Detective administration to another account (i.e Audit account).
22+
- Assumes a role in the delegated administrator account to configure organizations management.
23+
- Adds all existing accounts including the `management account` as members.
24+
25+
---
26+
27+
## Deployed Resource Details
28+
29+
![Architecture](./documentation/sra-detective-org.png)
30+
31+
### 1.0 Organization Management Account<!-- omit in toc -->
32+
33+
#### 1.1 AWS CloudFormation<!-- omit in toc -->
34+
35+
- 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.
36+
- 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`.
37+
- For parameter details, review the [AWS CloudFormation templates](templates/).
38+
39+
#### 1.2 IAM Roles<!-- omit in toc -->
40+
41+
- The `Lambda IAM Role` is used by the Lambda function to enable the Detective Delegated Administrator Account within each region provided.
42+
- The `Configuration IAM Role` is assumed by the Lambda function to configure Detective within the delegated administrator account and all member accounts.
43+
44+
#### 1.3 Compliance Event Rule<!-- omit in toc -->
45+
46+
- The `Organization Compliance Scheduled Event Rule` triggers the `AWS Lambda Function` to capture AWS Account status updates (e.g. suspended to active).
47+
- A parameter is provided to set the schedule frequency.
48+
- 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.
49+
50+
#### 1.4 Dead Letter Queue (DLQ)<!-- omit in toc -->
51+
52+
- SQS dead letter queue used for retaining any failed Lambda events.
53+
54+
#### 1.5 Alarm SNS Topic<!-- omit in toc -->
55+
56+
- SNS Topic used to notify subscribers when messages hit the DLQ.
57+
58+
#### 1.6 AWS Lambda Function<!-- omit in toc -->
59+
60+
- The Lambda function includes logic to enable and configure Detective.
61+
62+
#### 1.7 Lambda Layer<!-- omit in toc -->
63+
64+
- The python boto3 SDK lambda layer to enable capability for lambda to activate all elements of the Detective service.
65+
- This is downloaded during the deployment process and packaged into a layer that is used by the lambda function in this solution.
66+
- The Detective API available in the current lambda environment (as of 06/06/2023) is boto3-1.20.32, however, enhanced functionality of the Detective API used in this solution requires at least 1.26.135 (see references below).
67+
- Note: Future revisions to this solution will remove this layer when boto3 is updated within the lambda environment.
68+
69+
#### 1.8 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.9 Detective<!-- omit in toc -->
76+
77+
- The Detective delegated administrator is registered within organizations in the `management account` using the Detective APIs within each provided region.
78+
79+
---
80+
81+
### 2.0 Audit Account<!-- omit in toc -->
82+
83+
The example solutions use `Audit Account` instead of `Security Tooling Account` to align with the default account name used within the AWS Control Tower
84+
setup process for the Security Account. The Account ID for the `Audit Account` SSM parameter is
85+
populated from the `SecurityAccountId` parameter within the `AWSControlTowerBP-BASELINE-CONFIG` StackSet.
86+
87+
#### 2.1 AWS CloudFormation<!-- omit in toc -->
88+
89+
- See [1.1 AWS CloudFormation](#11-aws-cloudformation)
90+
91+
#### 2.2 Configuration IAM Role<!-- omit in toc -->
92+
93+
- IAM role assumed by the Lambda function within the `management account` to configure Detective within each region provided.
94+
95+
#### 2.3 Detective (Delegated admin)<!-- omit in toc -->
96+
97+
- Detective is enabled in the delegated admin account within each provided region.
98+
- Detective core package, Amazon EKS audit logs and AWS security findings are enabled for the behavior graphs.
99+
- New organization accounts are automatically enabled as member accounts.
100+
101+
---
102+
103+
### 3.0 All Existing and Future Organization Member Accounts<!-- omit in toc -->
104+
105+
#### 3.1 AWS CloudFormation<!-- omit in toc -->
106+
107+
- See [1.1 AWS CloudFormation](#11-aws-cloudformation)
108+
109+
#### 3.2 Configuration IAM Role<!-- omit in toc -->
110+
111+
- IAM role assumed by the Lambda function within the `management account` to configure Detective within each account provided.
112+
113+
#### 3.3 Detective (Members)<!-- omit in toc -->
114+
115+
- Detective is enabled from the delegated administrator account.
116+
117+
---
118+
119+
## Implementation Instructions
120+
121+
### Prerequisites<!-- omit in toc -->
122+
123+
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.
124+
2. Verify that the [SRA Prerequisites Solution](../../common/common_prerequisites/) has been deployed.
125+
3. Verify that Amazon GuardDuty enabled. If you are not a GuardDuty customer, or have been a GuardDuty customer for less than 48 hours, you cannot enable Detective. You must either enable GuardDuty or wait for 48 hours (see references below).
126+
127+
### Solution Deployment<!-- omit in toc -->
128+
129+
Choose a Deployment Method:
130+
131+
- [AWS CloudFormation](#aws-cloudformation)
132+
- [Customizations for AWS Control Tower](../../../docs/CFCT-DEPLOYMENT-INSTRUCTIONS.md)
133+
134+
#### AWS CloudFormation<!-- omit in toc -->
135+
136+
In the `management account (home region)`, launch an AWS CloudFormation **Stack** using one of the options below:
137+
138+
- **Option 1:** (Recommended) Use the [sra-detective-org-main-ssm.yaml](templates/sra-detective-org-main-ssm.yaml) template. This is a more automated approach where some of the CloudFormation parameters are populated from SSM parameters created by
139+
the [SRA Prerequisites Solution](../../common/common_prerequisites/).
140+
141+
```bash
142+
aws cloudformation deploy --template-file $HOME/aws-sra-examples/aws_sra_examples/solutions/detective/detective_org/templates/sra-detective-org-main-ssm.yaml --stack-name sra-detective-org-main-ssm --capabilities CAPABILITY_NAMED_IAM --parameter-overrides pGuarddutyEnabledForMoreThan48Hours=<TRUE_OR_FALSE>
143+
```
144+
145+
- **Option 2:** Use the [sra-detective-org-main.yaml](templates/sra-detective-org-main.yaml) template. Input is required for the CloudFormation parameters where the default is not set.
146+
147+
```bash
148+
aws cloudformation deploy --template-file $HOME/aws-sra-examples/aws_sra_examples/solutions/detective/detective_org/templates/sra-detective-org-main.yaml --stack-name sra-detective-org-main --capabilities CAPABILITY_NAMED_IAM --parameter-overrides pAuditAccountId=<AUDIT_ACCOUNT_ID> pOrganizationId=<ORGANIZATION_ID> pRootOrganizationalUnitId=<ROOT_ORGANIZATIONAL_UNIT_ID> pSRAStagingS3BucketName=<SRA_STAGING_S3_BUCKET_NAME> pGuarddutyEnabledForMoreThan48Hours=<TRUE_OR_FALSE>
149+
```
150+
151+
##### Important<!-- omit in toc -->
152+
153+
Pay close attention to the `--parameter-overrides` argument. For launching of the AWS Cloudformation stack using one of the commands in the options above to be successful, Amazon GuardDuty must have been enabled for at least 48 hours, **and** the `pGuarddutyEnabledForMoreThan48Hours` parameter in the `--parameter-overrides` argument must be set to `true`. If it is set to `false` the stack launch will fail and provide an error.
154+
155+
#### Verify Solution Deployment<!-- omit in toc -->
156+
157+
1. Log into the `management account` and navigate to the Detective page
158+
1. Select Settings and then Account Management
159+
2. Verify that the delegated admin account is set for each region
160+
2. Log into the Audit account and navigate to the Detective page
161+
1. Select Settings and then Account Management
162+
2. Verify the auto-enable organization accounts is ON in each region
163+
3. Select Settings and then General
164+
4. Verify the Detective service, AWS security findings and EKS audit logs are enabled in each region
165+
3. Log into a member account and verify the Detective service is enabled
166+
167+
#### Solution Update Instructions<!-- omit in toc -->
168+
169+
1. [Download and Stage the SRA Solutions](../../../docs/DOWNLOAD-AND-STAGE-SOLUTIONS.md). **Note:** Get the latest code and run the staging script.
170+
2. Update the existing CloudFormation Stack or CFCT configuration. **Note:** Make sure to update the `SRA Solution Version` parameter and any new added parameters.
171+
172+
#### Solution Delete Instructions<!-- omit in toc -->
173+
174+
1. In the `management account (home region)`, delete the AWS CloudFormation **Stack** (`sra-detective-org-main-ssm` or `sra-detective-org-main`).
175+
2. In the `management account (home region)`, verify that the Lambda function processing is complete by confirming no more CloudWatch logs are generated.
176+
3. 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)`, navigate to the AWS Lambda Functions page.
181+
2. Select the `checkbox` next to the Lambda Function and select `Test` from the `Actions` menu.
182+
3. Scroll down to view the `Test event`.
183+
4. Click the `Test` button to trigger the Lambda Function with the default values.
184+
5. Verify that the updates were successful within the expected account(s).
185+
186+
---
187+
188+
## References
189+
190+
- [Managing multiple accounts in Amazon Detective with AWS Organizations](https://docs.aws.amazon.com/detective/latest/adminguide/accounts.html)
191+
- [Determining whether an account can be enabled](https://docs.aws.amazon.com/detective/latest/adminguide/accounts-orgs-members-enable.html#accounts-orgs-members-enable-eligibility)
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)

‎aws_sra_examples/solutions/detective/detective_org/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/detective/detective_org/customizations_for_aws_control_tower/manifest-v2.yaml

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
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 Detective
10+
# -----------------------------------------------------------------------------
11+
- name: sra-detective-org-main-ssm
12+
resource_file: templates/sra-detective-org-main-ssm.yaml
13+
parameters:
14+
- parameter_key: pControlTowerRegionsOnly
15+
parameter_value: 'true'
16+
- parameter_key: pCreateLambdaLogGroup
17+
parameter_value: 'false'
18+
- parameter_key: pDatasourcePackages
19+
parameter_value: EKS_AUDIT, ASFF_SECURITYHUB_FINDING
20+
- parameter_key: pEnabledRegions
21+
parameter_value: ''
22+
- parameter_key: pGuarddutyEnabledForMoreThan48Hours
23+
parameter_value: 'false'
24+
- parameter_key: pLambdaLogGroupKmsKey
25+
parameter_value: ''
26+
- parameter_key: pLambdaLogGroupRetention
27+
parameter_value: '14'
28+
- parameter_key: pLambdaLogLevel
29+
parameter_value: INFO
30+
- parameter_key: pSRAAlarmEmail
31+
parameter_value: ''
32+
- parameter_key: pSRASolutionVersion
33+
parameter_value: 'v1.0'
34+
deploy_method: stack_set
35+
deployment_targets:
36+
accounts:
37+
- REPLACE_ME_ORG_MANAGEMENT_ACCOUNT_NAME

‎aws_sra_examples/solutions/detective/detective_org/customizations_for_aws_control_tower/manifest.yaml

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
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: 2020-01-01
5+
6+
# Control Tower Custom Service Control Policies
7+
organization_policies: []
8+
9+
# Control Tower Custom CloudFormation Resources
10+
cloudformation_resources:
11+
# -----------------------------------------------------------------------------
12+
# Organization Detective
13+
# -----------------------------------------------------------------------------
14+
- name: sra-detective-org-main-ssm
15+
template_file: templates/sra-detective-org-main-ssm.yaml
16+
parameter_file: parameters/sra-detective-org-main-ssm.json
17+
deploy_method: stack_set
18+
deploy_to_account:
19+
- REPLACE_ME_ORG_MANAGEMENT_ACCOUNT_NAME
20+
21+
# - name: sra-detective-org-main
22+
# template_file: templates/sra-detective-org-main.yaml
23+
# parameter_file: parameters/sra-detective-org-main.json
24+
# deploy_method: stack_set
25+
# deploy_to_account:
26+
# - REPLACE_ME_ORG_MANAGEMENT_ACCOUNT_NAME

‎aws_sra_examples/solutions/detective/detective_org/customizations_for_aws_control_tower/parameters/sra-detective-org-main-ssm.json

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[
2+
{
3+
"ParameterKey": "pControlTowerRegionsOnly",
4+
"ParameterValue": "true"
5+
},
6+
{
7+
"ParameterKey": "pCreateLambdaLogGroup",
8+
"ParameterValue": "false"
9+
},
10+
{
11+
"ParameterKey": "pDatasourcePackages",
12+
"ParameterValue": "EKS_AUDIT, ASFF_SECURITYHUB_FINDING"
13+
},
14+
{
15+
"ParameterKey": "pEnabledRegions",
16+
"ParameterValue": ""
17+
},
18+
{
19+
"ParameterKey": "pGuarddutyEnabledForMoreThan48Hours",
20+
"ParameterValue": "false"
21+
},
22+
{
23+
"ParameterKey": "pLambdaLogGroupKmsKey",
24+
"ParameterValue": ""
25+
},
26+
{
27+
"ParameterKey": "pLambdaLogGroupRetention",
28+
"ParameterValue": "14"
29+
},
30+
{
31+
"ParameterKey": "pLambdaLogLevel",
32+
"ParameterValue": "INFO"
33+
},
34+
{
35+
"ParameterKey": "pSRAAlarmEmail",
36+
"ParameterValue": ""
37+
},
38+
{
39+
"ParameterKey": "pSRASolutionVersion",
40+
"ParameterValue": "v1.0"
41+
}
42+
43+
]

‎aws_sra_examples/solutions/detective/detective_org/customizations_for_aws_control_tower/parameters/sra-detective-org-main.json

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
[
2+
{
3+
"ParameterKey": "pAuditAccountId",
4+
"ParameterValue": ""
5+
},
6+
{
7+
"ParameterKey": "pControlTowerRegionsOnly",
8+
"ParameterValue": "true"
9+
},
10+
{
11+
"ParameterKey": "pCreateLambdaLogGroup",
12+
"ParameterValue": "false"
13+
},
14+
{
15+
"ParameterKey": "pDatasourcePackages",
16+
"ParameterValue": "EKS_AUDIT, ASFF_SECURITYHUB_FINDING"
17+
},
18+
{
19+
"ParameterKey": "pEnabledRegions",
20+
"ParameterValue": ""
21+
},
22+
{
23+
"ParameterKey": "pGuarddutyEnabledForMoreThan48Hours",
24+
"ParameterValue": "false"
25+
},
26+
{
27+
"ParameterKey": "pLambdaLogGroupKmsKey",
28+
"ParameterValue": ""
29+
},
30+
{
31+
"ParameterKey": "pLambdaLogGroupRetention",
32+
"ParameterValue": "14"
33+
},
34+
{
35+
"ParameterKey": "pLambdaLogLevel",
36+
"ParameterValue": "INFO"
37+
},
38+
{
39+
"ParameterKey": "pOrganizationId",
40+
"ParameterValue": ""
41+
},
42+
{
43+
"ParameterKey": "pRootOrganizationalUnitId",
44+
"ParameterValue": ""
45+
},
46+
{
47+
"ParameterKey": "pSRAAlarmEmail",
48+
"ParameterValue": ""
49+
},
50+
{
51+
"ParameterKey": "pSRAStagingS3BucketName",
52+
"ParameterValue": ""
53+
},
54+
{
55+
"ParameterKey": "pSRASolutionVersion",
56+
"ParameterValue": "v1.0"
57+
}
58+
]

‎aws_sra_examples/solutions/detective/detective_org/documentation/sra-detective-org.png

244 KB
Loading

‎aws_sra_examples/solutions/detective/detective_org/documentation/sra-detective-org.pptx

297 KB
Binary file not shown.

0 commit comments

Comments
 (0)