Merge pull request #18 from AmazonElizabethZhong/master

Version 1.1.0 Release:

Author: AmazonElizabethZhong

EnableDetective.yaml

@@ -1,3 +1,11 @@
+#    __author__ = "Amazon Detective"
+#    __copyright__ = "Amazon 2020"
+#    __credits__ = "Amazon Detective"
+#    __license__ = "Apache"
+#    __version__ = "1.1.0"
+#    __maintainer__ = "Amazon Detective"
+#    __email__ = "detective-demo-requests@amazon.com"
+#    __status__ = "Production"
 AWSTemplateFormatVersion: 2010-09-09
 Description: Creates a new role to allow an administrator account to enable and manage Detective.
 
@@ -7,6 +15,10 @@ Parameters:
     Description: AWS Account Id of the administrator account (the account in which will recieve Detective findings from member accounts).
     MaxLength: 12
     MinLength: 12
+  RoleName:
+    Type: String
+    Default: "ManageDetective"
+    Description: RoleName to create IAM Role in the administrator account and each member account.
   CreateInstanceRole:
     Type: String
     Description: Select Yes to create an EC2 instance role that can be attached to an instnace in the Master account which will allow the instance to assume the exection role.  Select No if you plan to run the script locally or are creating the stack in a member account.
@@ -17,7 +29,7 @@ Resources:
   ExecutionRole:
     Type: AWS::IAM::Role
     Properties:
-      RoleName: ManageDetective
+      RoleName: !Ref RoleName
       AssumeRolePolicyDocument:
         Version: 2012-10-17
         Statement:
@@ -34,7 +46,10 @@ Resources:
     Type: AWS::IAM::Role
     Condition: CreateInstanceRole
     Properties:
-      RoleName: ManageDetectiveInstanceRole
+      RoleName: !Join
+                - ''
+                - - !Ref RoleName
+                  - 'InstanceRole'
       AssumeRolePolicyDocument:
         Version: "2012-10-17"
         Statement: 
@@ -47,7 +62,10 @@ Resources:
               - "sts:AssumeRole"
       Policies:
       -
-        PolicyName: ManageDetectivePolicy
+        PolicyName: !Join
+                    - ''
+                    - - !Ref RoleName
+                      - 'Policy'
         PolicyDocument: 
           Version: "2012-10-17"
           Statement: 

README.md

@@ -3,7 +3,7 @@
 Amazon Detective provides a set of open-source Python scripts in this repository. The scripts require Python 3.
 
 You can use these to perform the following tasks:
-* Enable Detective for an administrator account across Regions. When you enable Detective, you can assign tag values to the behavior graph.
+* Enable Detective for an administrator account across Regions. When you enable Detective, you can assign tag values to assign to a new behavior graph.
 * Add member accounts to an administrator account's behavior graphs across Regions.
 * Optionally send invitation emails to the member accounts. You can also configure the request to not send invitation emails.
 * Remove member accounts from an administrator account's behavior graphs across Regions.
@@ -13,12 +13,56 @@ For more information on how to use these scripts, see [Using the Amazon Detectiv
 
 ## Contributing to this project
 
+### Complete use case
+
+The following is an example use case of adding multiple accounts in a graph.
+
+1. Create a .csv file of the AWS account ids.
+    1. (Please check the format in section: *Creating a .csv list of accounts to add or remove*)
+2. Add the necessary permissions to each account.
+    1. (Please check the complete setup in section: *Required permissions for the scripts*)
+3. Add the root module into PYTHONPATH.
+    ```
+   #For example: export PYTHONPATH=$PYTHONPATH:/my_folder/amazon-detective-multiaccount-scripts/src
+    
+   export PYTHONPATH=$PYTHONPATH:<absolute root module path> 
+    ```
+4. Go to the root module, and run the python script and specify the .csv file. Make sure the role specified by --assume_role is the one created in Step 2. 
+    ```
+   #For example:
+   cd /my_folder/amazon-detective-multiaccount-scripts/src/amazon_detective_multiaccount_scripts
+   python3 enableDetective.py --admin_account 111122223333 --assume_role ManageDetective --input_file inputFile.csv --tags Department=Finance --enabled_regions us-west-1
+   ```
+6. Check results of the script in the terminal and/or AWS console.
+    1. For example, for the command above, the terminal should have the following output:
+       ![plot](./pic/image_1.png)
+       ![plot](./pic/image_2.png)
+
 ### Running tests
 
 ```
 # Install requirements
+
 pip3 install boto3 pytest
 
 # In the tests/ directory...
+
+# Add your root module into PYTHONPATH (if you haven't done this step) 
+# eg: export PYTHONPATH=$PYTHONPATH:/my_folder/amazon-detective-multiaccount-scripts/src
+
+export PYTHONPATH=$PYTHONPATH:<absolute root module path> 
+
+# Run the test
+
 pytest -s
 ```
+
+## FAQs
+1. If you experience the following error Message for opt-in regions while enabling detective in all regions:
+
+    `ERROR - error with region <region>: An error occurred (UnrecognizedClientException) when calling the ListGraphs operation:
+The security token included in the request is invalid`
+
+    Using the scripts in opt-in regions assumes you have your accounts/resources configured in that region, so please double-check your accounts' configuration.
+
+    For further information, here is documentation on opt-in regions work: https://docs.aws.amazon.com/general/latest/gr/rande-manage.html.

VERSION.md

@@ -0,0 +1,11 @@
+## Version 1.1.0:
+- Introduce mechanism to wait for the accounts to be invited in enableDetective.py
+- Optional parameters "--skip_prompt"
+- Improved unit test coverage
+- RoleName parameter added for enable detective cloudformation in EnableDetective.yaml
+- BUGFIX: 1. enableDetective.py does not work without --tags option
+- BUGFIX: 2. Fix datatype mismatch for delete_members function
+## Version 1.0.1:
+- BUGFIX: AttributeError: 'tuple' object has no attribute 'keys'
+## Version 1.0.0:
+- Initial project release

__init__.py

@@ -0,0 +1 @@
+# Implement your code here.