|
1 | 1 | # amazon-detective-multiaccount-scripts |
2 | 2 |
|
3 | | -## About these scripts |
| 3 | +Amazon Detective provides a set of open-source Python scripts in this repository. The scripts require Python 3. |
4 | 4 |
|
5 | | -These scripts automate the the following processes: |
| 5 | +You can use these to perform the following tasks: |
| 6 | +* Enable Detective for an administrator account across Regions. When you enable Detective, you can assign tag values to the behavior graph. |
| 7 | +* Add member accounts to an administrator account's behavior graphs across Regions. |
| 8 | +* Optionally send invitation emails to the member accounts. You can also configure the request to not send invitation emails. |
| 9 | +* Remove member accounts from an administrator account's behavior graphs across Regions. |
| 10 | +* Disable Detective for an administrator account across Regions. When an administrator account disables Detective, the administrator account's behavior graph in each Region is disabled. |
6 | 11 |
|
7 | | -* Enabling Detective for a master account across Regions |
8 | | -* Adding member accounts to the master account's behavior graph across Regions |
9 | | -* Removing member accounts from a master account's behavior graph across Regions |
10 | | -* Disabling Detective for a master account across Regions. Disabling Detective deletes the master account's behavior graph in each Region. |
11 | | - |
12 | | -The scripts act across a group of AWS accounts that are in your control. |
13 | | - |
14 | | -**enableDetective.py** does the following: |
15 | | - |
16 | | -1. Enables Detective in for a master account in each specified Region, if the master account does not already have Detective enabled in that Region. |
17 | | -2. Sends invitations from the master account to the specified member accounts for each behavior graph. |
18 | | -3. Automatically accepts the invitations for the member accounts. Because the script accepts the invitation on their behalf, member accounts can ignore these emails. |
19 | | - |
20 | | -The result is a master account that monitors security findings for all member accounts. |
21 | | - |
22 | | -Detective is regionally isolated. Findings for each member account are ingested into the master account's behavior graph for the corresponding Region. For example, the master account's behavior graph in the us-east-1 Region receives security findings from the us-east-1 Region from the associated member accounts. |
23 | | - |
24 | | - |
25 | | -**disableDetective.py** deletes the specified member accounts from the master account's behavior graphs across the specified Regions. |
26 | | - |
27 | | -It also provides an option to disable Detective for the master account across the specified Regions. |
28 | | - |
29 | | - |
30 | | -## Required permissions for the script |
31 | | - |
32 | | -The scripts require a pre-existing role in the master account and all of the member accounts that you add or remove. |
33 | | - |
34 | | -The role name must be the same in all accounts. |
35 | | - |
36 | | -The role trust relationship must allow your instance or local credentials to assume the role. |
37 | | - |
38 | | -The AmazonDetectiveFullAccess managed policy shown below contains the permissions that are required for the script to succeed: |
39 | | - |
40 | | -### Role policy |
41 | | - |
42 | | -```json |
43 | | - { |
44 | | - "Version": "2012-10-17", |
45 | | - "Statement": [ |
46 | | - { |
47 | | - "Sid": "VisualEditor0", |
48 | | - "Effect": "Allow", |
49 | | - "Action": [ |
50 | | - "detective:CreateMembers", |
51 | | - "detective:DeleteMembers", |
52 | | - "detective:AcceptInvitation", |
53 | | - "detective:ListGraphs", |
54 | | - "detective:ListMembers" |
55 | | - ], |
56 | | - "Resource": "*" |
57 | | - } |
58 | | - ] |
59 | | -} |
60 | | -``` |
61 | | - |
62 | | -### Role trust relationship |
63 | | - |
64 | | -```json |
65 | | -{ |
66 | | - "Version": "2012-10-17", |
67 | | - "Statement": [ |
68 | | - { |
69 | | - "Effect": "Allow", |
70 | | - "Principal": { |
71 | | - "AWS": "arn:aws:iam::<ACCOUNTID>:user/<USERNAME>" |
72 | | - }, |
73 | | - "Action": "sts:AssumeRole" |
74 | | - } |
75 | | - ] |
76 | | -} |
77 | | -``` |
78 | | - |
79 | | -If you do not have a common role that includes at least the above permissions, you must create a role with at least those permissions in each member account and in the master account. |
80 | | - |
81 | | -When you create the role, make sure that you do the following: |
82 | | - |
83 | | -* Use the same role name in every account |
84 | | -* Select the AmazonDetectiveFullAccess managed policy |
85 | | - |
86 | | -To automate this process, you can use the **EnableDetective.yaml** CloudFormation Template. Because the template creates only global resources, it can be created in any Region. |
87 | | - |
88 | | - |
89 | | -## Setting up the execution environment |
90 | | - |
91 | | -You can run the scripts from either an EC2 instance or from a local machine. |
92 | | - |
93 | | -### Option 1: Launch an EC2 instance |
94 | | - |
95 | | -1. Launch an EC2 instance in your master account <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html> |
96 | | -2. Attach to an instance an IAM role that has permissions to allow the instance to call AssumeRole within the master account. |
97 | | -If you used the EnableDetective.yaml template, then an instance role with a profile name of "EnableDetective" was created. |
98 | | -Otherwise see the documentation on creating an instance role here: <https://aws.amazon.com/blogs/security/easily-replace-or-attach-an-iam-role-to-an-existing-ec2-instance-by-using-the-ec2-console/>. |
99 | | -3. Install the required software |
100 | | - * APT: sudo apt-get -y install python3-pip python3 git |
101 | | - * RPM: sudo yum -y install python3-pip python3 git |
102 | | - * sudo pip install boto3 |
103 | | -4. Clone the Repository |
104 | | - * git clone <https://github.com/aws-samples/amazon-detective-multiaccount-scripts.git> |
105 | | - |
106 | | -### Option 2: Run the scripts locally |
107 | | - |
108 | | -1. Ensure you have set up on your local machine credentials for your master account that have permission to call AssumeRole. |
109 | | -2. Install the required software: |
110 | | - * Windows: |
111 | | - 1. Install Python <https://www.python.org/downloads/windows/> |
112 | | - 2. Open command prompt: |
113 | | - 1. pip install boto3 |
114 | | - 3. Download sourcecode from <https://github.com/aws-samples/amazon-detective-multiaccount-scripts> |
115 | | - * Mac: |
116 | | - 1. Install Python <https://www.python.org/downloads/mac-osx/> |
117 | | - 2. Open command prompt: |
118 | | - 1. pip install boto3 |
119 | | - 3. Download sourcecode from <https://github.com/aws-samples/amazon-detective-multiaccount-scripts> |
120 | | - * Linux: |
121 | | - 1. sudo apt-get -y install install python3-pip python3 git |
122 | | - 1. sudo pip install boto3 |
123 | | - 2. git clone <https://github.com/aws-samples/amazon-detective-multiaccount-scripts> |
124 | | - 2. cd amazon-detective-multiaccount-scripts |
125 | | - 1. sudo yum install git python |
126 | | - 3. sudo pip install boto3 |
127 | | - 1. git clone <https://github.com/aws-samples/amazon-detective-multiaccount-scripts> |
128 | | - |
129 | | -## Creating a .csv list of member accounts to add or remove |
130 | | - |
131 | | -To identify the member accounts to add to or remove from the behavior graphs, you provide a .csv file that contains the list of accounts. |
132 | | - |
133 | | -Each account is listed on a separate line. Each member account entry contains the AWS account ID and the account's root user email address. |
134 | | - |
135 | | -Example: |
136 | | - |
137 | | -``` |
138 | | -111122223333,srodriguez@example.com |
139 | | -444455556666,rroe@example.com |
140 | | -
|
141 | | -``` |
142 | | -A CSV file can also be generated from the Organizations Master or an account that is Delegated Administrator for GuardDuty/IAM Access Analyzer by running the below code: |
143 | | - |
144 | | -``` |
145 | | -import boto3 |
146 | | -import csv |
147 | | -import os |
148 | | -
|
149 | | -## Exports Organizations members as CSV to be used as input for Amazon Detective |
150 | | -
|
151 | | -client = boto3.client('organizations') |
152 | | -
|
153 | | -def create_accounts_csv(): |
154 | | - paginator = client.get_paginator('list_accounts') |
155 | | - page_iterator = paginator.paginate() |
156 | | - with open('accounts.csv', mode='w', newline='') as accounts_file: |
157 | | - writer = csv.writer(accounts_file, dialect='excel', delimiter='"', lineterminator='') |
158 | | - for r in page_iterator: |
159 | | - for key in r['Accounts']: |
160 | | - writer.writerows(key['Id']+',') |
161 | | - writer.writerows(key['Email']+'\n') |
162 | | -
|
163 | | -create_accounts_csv() |
164 | | -``` |
165 | | - |
166 | | -## Executing the scripts |
167 | | - |
168 | | -### Running enableDetective.py |
169 | | - |
170 | | -1. Copy the .csv file containing the account number and email addresses to the **amazon-detective-multi-account-scripts** directory on your EC2 instance or local machine. |
171 | | -If you are running the scripts from an EC2 instance, use one of the following methods: |
172 | | - * S3 `s3 cp s3://bucket/key_name enable.csv .` |
173 | | - * pscp.exe `pscp local_file_path username@hostname:.` |
174 | | - * scp `scp local_file_path username@hostname:.` |
175 | | -2. Change to the **amazon-detective-multiaccount-scripts** directory. |
176 | | -3. Run the enableDetective.py script. |
177 | | - |
178 | | - |
179 | | -```html |
180 | | -usage: enableDetective.py [-h] --master_account MASTER_ACCOUNT --assume_role |
181 | | - ASSUME_ROLE --enabled_regions REGION_LIST |
182 | | - input_file |
183 | | - |
184 | | -Adds member accounts to the master account's behavior graph in each Region. |
185 | | - |
186 | | -positional arguments: |
187 | | - input_file Path to the .csv file containing the list of account IDs |
188 | | - and email addresses of the member accounts to add to the master account's behavior graph in each Region |
189 | | - |
190 | | -arguments: |
191 | | - -h, --help Show a help message and exits |
192 | | - --master_account MASTER_ACCOUNT |
193 | | - AWS account ID for the master account |
194 | | - --assume_role ASSUME_ROLE |
195 | | - Role name to assume in each account |
196 | | - --enabled_regions REGION_LIST |
197 | | - Optional Comma-separated list of Regions in which to enable Detective for the master account and add the member |
198 | | - accounts to the behavior graph. If the master account already has a behavior graph in a Region, then |
199 | | - the member accounts are added to that behavior graph. If you do not provide a list of Regions, then |
200 | | - the script acts across all Regions that Detective supports. |
201 | | - --disable_email If this flag is included, then emails will not be sent to the member accounts. Member accounts must still accept |
202 | | - the invitation before they are added to the behavior graph. |
203 | | -``` |
204 | | - |
205 | | - |
206 | | - |
207 | | -### Running disableDetective.py |
208 | | - |
209 | | -1. Copy the .csv file containing the account number and email addresses to the **amazon-detective-multi-account-scripts** directory on your EC2 instance or local machine. |
210 | | -If you are running the scripts from an EC2 instance, use one of the following methods: |
211 | | - * S3 `s3 cp s3://bucket/key_name enable.csv .` |
212 | | - * pscp.exe `pscp local_file_path username@hostname:.` |
213 | | - * scp `scp local_file_path username@hostname:.` |
214 | | -2. Change to the **amazon-detective-multiaccount-scripts** directory. |
215 | | - |
216 | | -```html |
217 | | -usage: disabledetective.py [-h] --master_account MASTER_ACCOUNT --assume_role |
218 | | - ASSUME_ROLE --disabled_regions REGION_LIST [--delete_master] |
219 | | - input_file |
220 | | - |
221 | | -Removes member accounts from the master account's behavior graph in each Region. |
222 | | - |
223 | | -positional arguments: |
224 | | - input_file Name of the .csv file containing the list of account IDs |
225 | | - and email addresses |
226 | | - |
227 | | -arguments: |
228 | | - -h, --help Show a help message and exits |
229 | | - --master_account MASTER_ACCOUNT |
230 | | - Account ID for the master account |
231 | | - --assume_role ASSUME_ROLE |
232 | | - Role name to assume in each account |
233 | | - --disabled_regions REGION_LIST |
234 | | - Optional. Comma-separated list of Regions from which to remove the member accounts from the master account's |
235 | | - behavior graph. If you do not provide a list of Regions, then the script acts across all Regions that |
236 | | - Detective supports. |
237 | | - --delete_master If this flag is included, then instead of only deleting the member accounts from the master account's |
238 | | - behavior graphs, the script disables Detective for the master account in all of the specified Regions. |
239 | | - When Detective is disabled for a master account, the master account's behavior graph is disabled. |
240 | | -``` |
| 12 | +For more information on how to use these scripts, see [Using the Amazon Detective Python scripts](https://docs.aws.amazon.com/detective/latest/adminguide/detective-github-scripts.html) |
241 | 13 |
|
242 | 14 | ## Contributing to this project |
243 | 15 |
|
|
0 commit comments