Amazon Detective - Administration Guide · Security Hub allows you to pivot from a GuardDuty...

Amazon DetectiveAdministration Guide

Amazon Detective Administration Guide

Amazon Detective: Administration GuideCopyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is notAmazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages ordiscredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who mayor may not be affiliated with, connected to, or sponsored by Amazon.


Table of ContentsWhat is Detective? .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

How does Detective work? .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Who uses Detective? .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Detective terms and concepts .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Regions and quotas .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Detective Regions and endpoints ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Detective quotas .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Internet Explorer 11 not supported .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Setting up Detective .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Detective prerequisites and recommendations .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Supported AWS Command Line Interface version .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Account must have Amazon GuardDuty enabled .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Account data volume must be within the Detective quota .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Recommended alignment with GuardDuty and AWS Security Hub .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Required IAM policy for Detective .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Recommended update to the GuardDuty CloudWatch notification frequency .... . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Enabling Detective .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Enabling Detective (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Enabling Detective (Detective API, AWS CLI) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Enabling Detective across Regions (Python script on GitHub) .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Checking that data is being extracted .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

About the free trial for behavior graphs .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Source data used in a behavior graph .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Types of Detective source data .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12How Detective ingests and stores source data .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13How Detective enforces the data volume quota for behavior graphs .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

For master accounts: Managing the accounts in your behavior graph .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Viewing the list of accounts .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Listing accounts in the Detective behavior graph (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Listing the accounts in the Detective behavior graph (Detective API, AWS CLI) ... . . . . . . . . . . . . . . . . . . . . . . . 15

Inviting member accounts to a behavior graph .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Inviting individual accounts to a behavior graph (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Inviting a list of member accounts to a behavior graph (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Inviting member accounts to a behavior graph (Detective API, AWS CLI) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Adding a list of member accounts across Regions (Python script on GitHub) .... . . . . . . . . . . . . . . . . . . . . . . . . . 18

Enabling a member account that is Accepted (Not enabled) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Enabling a member account that is Accepted (Not enabled) (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Enabling a member account that is Accepted (Not enabled) (Detective API, AWS CLI) ... . . . . . . . . . . . . . . 19

Removing member accounts from a behavior graph .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Removing member accounts from a behavior graph (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Removing member accounts from a behavior graph (Detective API, AWS CLI) ... . . . . . . . . . . . . . . . . . . . . . . . . 20Removing a list of member accounts across Regions (Python script on GitHub) .... . . . . . . . . . . . . . . . . . . . . . 20

For member accounts: Managing behavior graph invitations and memberships .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22IAM policy for a member account .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Viewing behavior graph invitations .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Viewing behavior graph invitations (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Viewing behavior graph invitations (Detective API, AWS CLI) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Responding to a behavior graph invitation .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Responding to a behavior graph invitation (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Responding to a behavior graph invitation (Detective API, AWS CLI) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Removing your account from a behavior graph .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Removing your account from a behavior graph (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Removing your account from a behavior graph (Detective API, AWS CLI) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Tracking actions and usage in Detective .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

iii


Monitoring Detective usage and cost ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Volume of data ingested .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Projected 30-day cost ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Logging Detective API calls with CloudTrail .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Detective information in CloudTrail .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Understanding Detective log file entries ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Security ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Data protection .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Key management .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Identity and access management .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Audience .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Authenticating With Identities ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Managing Access Using Policies ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35How Amazon Detective works with IAM ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Identity-based policy examples .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Troubleshooting identity and access .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Logging and monitoring .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Compliance validation .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Resilience .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Infrastructure security ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Security best practices .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Best practices for master accounts .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Best practices for member accounts .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Disabling Detective .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Disabling Detective (Console) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Disabling Detective (Detective API, AWS CLI) ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Disabling Detective across Regions (Python script on GitHub) .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Using the Amazon Detective Python scripts ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Overview of the enableDetective.py script ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Overview of the disableDetective.py script ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Required permissions for the scripts ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Setting up the execution environment for the Python scripts ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Launching and configuring an EC2 instance .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Configuring a local machine to run the scripts ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Creating a .csv list of member accounts to add or remove .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Running enableDetective.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Running disableDetective.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Document history .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

iv

Amazon Detective Administration GuideHow does Detective work?

What is Amazon Detective?Amazon Detective makes it easy to analyze, investigate, and quickly identify the root cause of securityfindings or suspicious activities. Detective automatically collects log data from your AWS resources. Itthen uses machine learning, statistical analysis, and graph theory to help you visualize and conductfaster and more efficient security investigations.

The Detective prebuilt data aggregations, summaries, and context help you to quickly analyze anddetermine the nature and extent of possible security issues. Detective maintains up to a year of historicalevent data. This data is easily available through a set of visualizations that shows changes in the typeand volume of activity over a selected time window. For customers who have Amazon GuardDutyenabled, Detective also links those changes to GuardDuty findings.

How does Detective work?Detective automatically extracts time-based events such as login attempts, API calls, and network trafficfrom AWS CloudTrail and Amazon VPC flow logs. For customers who have GuardDuty enabled, it alsoingests findings detected by GuardDuty.

From those events, Detective uses machine learning and visualization to create a unified, interactive viewof your resource behaviors and the interactions between them over time. You can explore this behaviorgraph to examine disparate actions such as failed logon attempts or suspicious API calls. You can also seehow these actions affect resources such as AWS accounts and Amazon EC2 instances. You can adjust thebehavior graph's scope and timeline for a variety of tasks:

• Rapidly investigate any activity that falls outside the norm.• Identify patterns that may indicate a security issue.• Understand all of the resources affected by a finding.

Detective tailored visualizations provide a baseline for and summarize the account information. Thesefindings can help answer questions such as "Is this an unusual API call for this role?" Or "Is this spike intraffic from this instance expected?"

With Detective, you don't have to organize any data or develop, configure, or tune your own queriesand algorithms. There are no upfront costs and you pay only for the events analyzed, with no additionalsoftware to deploy or other feeds to subscribe to.

Who uses Detective?When an account enables Detective, it becomes the master account for a behavior graph. A behaviorgraph is a linked set of extracted and analyzed data from one or more AWS accounts. Master accountsinvite member accounts to contribute their data to the master account's behavior graph.

For information about how Detective uses source data from behavior graph accounts, see Source dataused in a behavior graph (p. 12).

For information on how master accounts manage behavior graphs, see For master accounts: Managingthe accounts in your behavior graph (p. 14). For information on how member accounts manage theirbehavior graph invitations and memberships, see For member accounts: Managing behavior graphinvitations and memberships (p. 22).

1

Amazon Detective Administration GuideWho uses Detective?

The master account uses the analytics and visualizations generated from the behavior graph toinvestigate AWS resources and GuardDuty findings. The Detective integration with GuardDuty and AWSSecurity Hub allows you to pivot from a GuardDuty finding in these services directly into the Detectiveconsole.

A Detective investigation focuses on the activity that is connected to the involved AWS resources. For anoverview of the investigation process in Detective, see How Amazon Detective is used for investigation inDetective User Guide.

2

https://docs.aws.amazon.com/detective/latest/userguide/detective-investigation-about.html


Amazon Detective terms andconcepts

The following terms and concepts are important for understanding Amazon Detective and how it works:

Behavior graph

A linked set of data generated from incoming source data that is associated with one or more AWSaccounts.

Each behavior graph uses the same structure of findings, entities, and relationships.Detective source data

Processed, structured versions of information from the following types of feeds:• AWS logs, such as AWS CloudTrail and Amazon VPC Flow Logs• GuardDuty findings

Detective uses the Detective source data to populate the behavior graph. Detective also stores copiesof the Detective source data to support its analytics.

Entity

An item extracted from the incoming data.

Each entity has a type, which identifies the type of object it represents. Examples of entity typesinclude IP addresses, Amazon EC2 instances, and AWS users.

Entities can be AWS resources that you manage, or external IP addresses that have interacted withyour resources.

For each entity, the source data is also used to populate entity properties. Property values can beextracted directly from source records or aggregated across multiple records.

Finding

A security issue detected by Amazon GuardDuty.Investigation

The process of performing triage on suspicious or interesting activity, determining the scope, gettingto its underlying source or cause, and then determining how to proceed.

Master account

The AWS account that owns a behavior graph and that uses the behavior graph for investigation.

The master account invites member accounts to contribute their data to the behavior graph. Masteraccounts can also view data usage for the behavior graph, and remove member accounts from thebehavior graph.

Member account

An AWS account that a master account invited to contribute data to a behavior graph.

Member accounts can respond to the behavior graph invitation and remove their account from thebehavior graph. They have no other access to the behavior graph.

3


Profile

For a finding or an entity, a single page that provides a collection of data visualizations plussupporting guidance.

For findings, profiles help analysts to determine whether the finding is of genuine concern or a falsepositive.

For entities, profiles provide supporting details for an investigation into a finding or for a generalhunt for suspicious activity.

Profile panel

A single visualization on a profile. Each profile panel is intended to help answer a specific question orquestions to assist an analyst in an investigation.

Profile panels can contain simple key-value pairs, tables, timelines, bar charts, or geolocation charts.Relationship

Activity that occurs between individual entities. Relationships are also extracted from the incomingsource data.

Similar to an entity, a relationship has a type, which identifies the types of entities involved andthe direction of the connection. An example of a relationship type is an IP address connecting to anAmazon EC2 instance.

Scope time

The time window that is used to scope the data displayed on finding and entity profiles.

The default scope time for a finding profile reflects the first and last times when the suspiciousactivity was observed.

The default scope time for an entity profile is the previous 24 hours.

4

Amazon Detective Administration GuideDetective Regions and endpoints

Amazon Detective Regions andquotas

When using Amazon Detective, be aware of these quotas.

Detective Regions and endpointsTo see the list of Regions where Detective is available, see Detective service endpoints.

Detective quotasDetective has the following quotas, which cannot be configured.

Resource Quota Comments

Number of member accounts 1,000 The number of member accounts that amaster account can add to a behavior graph.

Internet Explorer 11 not supportedYou cannot use Detective with Internet Explorer 11.

5

https://docs.aws.amazon.com/general/latest/gr/detective.html

Amazon Detective Administration GuideDetective prerequisites and recommendations

Setting up Amazon DetectiveWhen you enable Amazon Detective, Detective creates a Region-specific behavior graph that has youraccount as its master account. This is initially the only account in the behavior graph. The master accountcan then invite other AWS accounts to contribute their data to the behavior graph. See For masteraccounts: Managing the accounts in your behavior graph (p. 14).

Enabling Detective in a Region for the first time also begins a 30-day free trial for the behavior graph. Ifthe account disables Detective and then enables it again, no free trial is available. See About the free trialfor behavior graphs (p. 11).

After the free trial, each account in the behavior graph is billed for the data they contribute to it. Themaster account can track the usage and see the total projected cost for a typical 30-day period. See thesection called “Monitoring Detective usage and cost” (p. 27).

Contents• Amazon Detective prerequisites and recommendations (p. 6)• Enabling Amazon Detective (p. 8)

Amazon Detective prerequisites andrecommendations

Before you can enable Amazon Detective, you must have an AWS account. If you don't have an account,use this procedure to create one.

To sign up for AWS

1. Open https://portal.aws.amazon.com/billing/signup.2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a verification code on thephone keypad.

You also need to be aware of the following requirements and recommendations.

Contents• Supported AWS Command Line Interface version (p. 6)• Account must have Amazon GuardDuty enabled (p. 7)• Account data volume must be within the Detective quota (p. 7)• Recommended alignment with GuardDuty and AWS Security Hub (p. 7)• Required IAM policy for Detective (p. 7)• Recommended update to the GuardDuty CloudWatch notification frequency (p. 8)

Supported AWS Command Line Interface versionTo use the AWS CLI to perform Detective tasks, the minimum required version is 1.16.303.

6

https://portal.aws.amazon.com/billing/signup

Amazon Detective Administration GuideAccount must have Amazon GuardDuty enabled

Account must have Amazon GuardDuty enabledWhen you try to enable Detective, Detective checks whether GuardDuty has been enabled for youraccount for at least 48 hours.

If you are not a GuardDuty customer, or have been a GuardDuty customer for less than 48 hours, youcannot enable Detective. You must either enable GuardDuty or wait for 48 hours. This allows GuardDutyto assess the data volume that your account produces.

Account data volume must be within the DetectivequotaThe volume of data flowing into a behavior graph must be less than the maximum allowed by Detective.

When you try to enable Detective, if the data volume for your account is too large, you cannot enableDetective. The Detective console displays a notification to indicate that data volume is too large.

Recommended alignment with GuardDuty and AWSSecurity HubIf you are enrolled in GuardDuty and AWS Security Hub, we recommend that your account be a masteraccount for those services. If the master accounts are the same for all three services, then the followingintegration points work seamlessly.

• In GuardDuty or Security Hub, when viewing details for a GuardDuty finding, you can pivot from thefinding details to the Detective finding profile.

• In Detective, when investigating a GuardDuty finding, you can choose the option to archive thatfinding.

If you have different master accounts for GuardDuty and Security Hub, we recommend that you align themaster accounts based on the service you use more frequently.

• If you use GuardDuty more frequently, then enable Detective using the GuardDuty master account.• If you use Security Hub more frequently, then enable Detective using the Security Hub master account.

If you cannot use the same master accounts across all of the services, then after you enable Detective,you can optionally create a cross-account role. This role grants the Detective master account access toother accounts.

For information on how IAM supports this type of role, see Providing access to an IAM user in anotherAWS account that you own in the IAM User Guide.

Required IAM policy for DetectiveBefore you can enable Detective, if you are not an administrator, then you must attach the followingpermissions policy to your IAM principal. The principal can be an existing user or role that you are alreadyusing, or you can create a new user or role to use for Detective.

This policy allows you to perform all master account actions in Detective.

{ "Version": "2012-10-17",

7

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_aws-accounts.html


Amazon Detective Administration GuideRecommended update to the GuardDuty

CloudWatch notification frequency

"Statement": [ { "Effect": "Allow", "Action": [ "detective:Get*", "detective:CreateGraph", "detective:CreateMembers", "detective:DeleteGraph", "detective:DeleteMembers", "detective:ListGraphs", "detective:ListMembers", "detective:SearchGraph", "detective:StartMonitoringMember" ], "Resource": "*" } ]}

Recommended update to the GuardDuty CloudWatchnotification frequencyIn GuardDuty, detectors are configured with an Amazon CloudWatch notification frequency for reportingsubsequent occurrences of a finding. This includes sending notifications to Detective.

By default, the frequency is six hours. This means that even if a finding recurs many times, the newoccurrences are not reflected in Detective until up to six hours later.

To reduce the amount of time it takes for Detective to receive these updates, we recommend that theGuardDuty master account changes the setting on their detectors to 15 minutes. Note that changing theconfiguration has no effect on the cost of using GuardDuty.

For information on setting the notification frequency, see Monitoring GuardDuty Findings with AmazonCloudWatch Events in the Amazon GuardDuty User Guide.

Enabling Amazon DetectiveYou can enable Detective from the Detective console, the Detective API, or the AWS Command LineInterface.

You can only enable Detective once in each Region. If you are already a master account for a behaviorgraph in a Region, then you cannot enable Detective again in that Region.

Before you try to enable Detective, make sure that your account has been enrolled in Amazon GuardDutyfor at least 48 hours. If you do not meet this requirement, you cannot enable Detective.

If you do meet the GuardDuty requirement, then when you make the request to enable Detective,Detective checks whether your data volume is within the Detective quota. If your data volume exceedsthe quota, then you cannot enable Detective.

Contents• Enabling Detective (Console) (p. 9)• Enabling Detective (Detective API, AWS CLI) (p. 9)• Enabling Detective across Regions (Python script on GitHub) (p. 9)• Checking that data is being extracted (p. 10)

8

https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_findings_cloudwatch.html

https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_findings_cloudwatch.html

Amazon Detective Administration GuideEnabling Detective (Console)

Enabling Detective (Console)You can enable Amazon Detective from the AWS Management Console.

To enable Detective (console)

1. Sign in to the AWS Management Console, then open the Detective console at https://console.aws.amazon.com/detective/.

2. Choose Get started.

3. On the Enable Amazon Detective page, review the provided information.

Align master accounts (recommended) explains the recommendation to align the masteraccounts between Detective and Amazon GuardDuty and AWS Security Hub. See the section called“Recommended alignment with GuardDuty and AWS Security Hub” (p. 7).

Attach IAM policy (required) contains the IAM policy that is required to enable Detective andmanage a behavior graph. The policy should already be attached to your principal.

4. If it is not yet attached, choose Copy IAM policy to copy the policy so that you can attach it.

Confirm that the required IAM policy is in place. Then choose Enable Amazon Detective.

5. After you enable Detective, you can invite member accounts to your behavior graph.

To navigate to the Account management page, choose Add members now. For informationon inviting member accounts, see the section called “Inviting member accounts to a behaviorgraph” (p. 16).

Enabling Detective (Detective API, AWS CLI)You can enable Amazon Detective from the Detective API or the AWS Command Line Interface.

To enable Detective (Detective API, AWS CLI)

• Detective API: Use the CreateGraph operation.

• AWS CLI: At the command line, run the create-graph command.

aws detective create-graph

Enabling Detective across Regions (Python script onGitHub)Detective provides an open-source script in GitHub that does the following:

• Enables Detective for a master account in a specified list of Regions

• Adds a provided list of member accounts to add to each of the resulting behavior graphs

• Sends invitation emails to the member accounts

• Automatically accepts the invitations for the member accounts

For information on how to configure and use the GitHub scripts, see Using the Amazon Detective Pythonscripts (p. 49).

9

https://console.aws.amazon.com/detective/


https://docs.aws.amazon.com/detective/latest/APIReference/API_CreateGraph.html

Amazon Detective Administration GuideChecking that data is being extracted

Checking that data is being extractedAfter you enable Detective, it begins to ingest and extract data from your AWS account into yourbehavior graph.

For the initial extraction, data usually becomes available in the behavior graph within 24 hours.

One way to check that Detective is extracting data is to look for example values on the Detective Searchpage.

To check for example values on the Search page

1. Open the Detective console.2. In the navigation pane, choose Search.3. From the Select type menu, choose a type of item.

Examples from your data contains a sample set of identifiers of the selected type that are in yourbehavior graph data.

If you can see example values, then you know that data is being ingested and extracted into yourbehavior graph.

10



About the free trial for behaviorgraphs

When you enable Detective, and become the Detective master account for a behavior graph, a 30-dayfree trial starts for the behavior graph. Your account and your member accounts are not billed for anydata processed during that period.

Detective only allows one free trial for each combination of master account and Region. For example, ifan account deactivates Detective and then enables it again in the same Region, there is no free trial forthe second time Detective is enabled.

The free trial provides multiple benefits:

• You can explore Detective features and functionality to verify its value before you start to pay for it.• You can monitor the amount of data and the estimated cost before Detective begins to bill for it. See

the section called “Monitoring Detective usage and cost” (p. 27).

For the first two weeks after you enable Detective, Detective is in a training mode. During the trainingperiod, Detective uses your data to establish baselines of your organization's typical behavior. For moreinformation about the training period for behavior graph data, see Training period for new behaviorgraphs in the Detective User Guide.

During the free trial, Detective recommends that you add as many member accounts as you can to thebehavior graph. This provides Detective with a larger pool of data, which allows it to generate a moreaccurate picture of the normal activity for your organization.

While the free trial is in effect, the Settings pages display a notification that indicates the free trial is ineffect, and provides the date when the free trial ends.

When the trial period ends, Detective begins to bill the master and member accounts for the data theycontribute to the behavior graph.

11

https://docs.aws.amazon.com/detective/latest/userguide/detective-data-training-period.html

https://docs.aws.amazon.com/detective/latest/userguide/detective-data-training-period.html

Amazon Detective Administration GuideTypes of Detective source data

Source data used in a behavior graphTo populate a behavior graph, Amazon Detective uses source data from the behavior graph masteraccount and member accounts.

For details about the behavior graph data structure, see Overview of the behavior graph data structure inDetective User Guide.

Contents

• Types of Detective source data (p. 12)

• How Detective ingests and stores source data (p. 13)

• How Detective enforces the data volume quota for behavior graphs (p. 13)

Types of Detective source dataDetective ingests data from these types of AWS logs:

• AWS CloudTrail logs

• Amazon Virtual Private Cloud (Amazon VPC) flow logs

• For accounts that are enrolled in GuardDuty, Detective also ingests GuardDuty findings.

Detective consumes CloudTrail and VPC flow log events using independent and duplicative streams ofCloudTrail and VPC flow logs. These processes do not affect or use your existing CloudTrail and VPC flowlog configurations. They also do not affect the performance of or increase your costs for these services.

12

https://docs.aws.amazon.com/detective/latest/userguide/graph-data-structure-overview.html

Amazon Detective Administration GuideHow Detective ingests and stores source data

How Detective ingests and stores source dataWhen Detective is enabled, Detective begins ingesting source data from the behavior graph masteraccount. As member accounts are added to the behavior graph, Detective also begins using the datafrom those member accounts.

Detective source data consists of structured and processed versions of the original feeds. To supportDetective analytics, Detective stores copies of the Detective source data.

The Detective ingest process feeds data into Amazon Simple Storage Service (Amazon S3) buckets in theDetective source data store. As new source data arrives, other Detective components pick up the dataand start the extraction and analytics processes. For more information, see How Detective uses sourcedata to populate a behavior graph in Detective User Guide.

How Detective enforces the data volume quota forbehavior graphs

Detective has a strict quota on the volume of data it allows in each behavior graph. The data volume isthe amount of data per day that flows into the Detective behavior graph.

Detective enforces this quota when a master account enables Detective, and when a member accountaccepts an invitation to contribute to a behavior graph.

• If the data volume for a master account exceeds the quota, then the master account cannot enableDetective.

• If the added data volume from a member account would cause the behavior graph to exceed thequota, the member account cannot be enabled.

The data volume for a behavior graph also can grow naturally over time. Detective checks the behaviorgraph data volume each day to make sure that it does not exceed the quota.

If the behavior graph data volume is approaching the quota, Detective displays a warning message onthe console. To avoid exceeding the quota, you can remove member accounts.

If the behavior graph data volume exceeds the quota, then Detective disables the behavior graph. Whenthe behavior graph is disabled, no new data is ingested into it. You can still view the existing behaviorgraph data. The console displays a message to indicate that the behavior graph is disabled.

If your behavior graph is disabled, you must work with AWS Support to get it re-enabled. If possible,before you contact AWS Support, try to remove member accounts to get the data volume below thequota. This makes it easier to re-enable the behavior graph.

13

https://docs.aws.amazon.com/detective/latest/userguide/behavior-graph-population-about.html

https://docs.aws.amazon.com/detective/latest/userguide/behavior-graph-population-about.html

Amazon Detective Administration GuideViewing the list of accounts

For master accounts: Managing theaccounts in your behavior graph

A master account can invite 1,000 other accounts to be member accounts in the behavior graph. Seethe section called “Inviting member accounts to a behavior graph” (p. 16). When a member accountaccepts the invitation and is enabled, Amazon Detective begins to ingest and extract the memberaccount's data into that behavior graph.

The master account can also remove member accounts from their behavior graph. See the section called“Removing member accounts from a behavior graph” (p. 19).

An account can be a member account of multiple behavior graphs in the same Region. An account canonly be the master account of one behavior graph per Region. An account can be a master account indifferent Regions.

Detective charges each account for the data that it contributes to each behavior graph. For informationon tracking the volume of data for each account in the behavior graph, see the section called“Monitoring Detective usage and cost” (p. 27).

Contents• Viewing the list of accounts in a behavior graph (p. 14)• Inviting member accounts to a behavior graph (p. 16)• Enabling a member account that is Accepted (Not enabled) (p. 18)• Removing member accounts from a behavior graph (p. 19)

Viewing the list of accounts in a behavior graphThe master account can use the Detective console or API to view a list of behavior graph accounts.

The results do not include member accounts that declined the invitation or that were removed from thebehavior graph. It only includes accounts with the following statuses.

Verification in progress

Detective is verifying the account email address before it sends the invitation.Verification failed

The email address verification failed. The invitation was not sent.Invited

The invitation was sent, but the member account has not yet responded.Accepted (Enabled)

The member account accepted the invitation and is contributing data to the behavior graph.Accepted (Not enabled)

The member account accepted the invitation, but cannot be enabled. This status occurs for one ofthe following reasons.• The member account has not been an Amazon GuardDuty customer for at least 48 hours.

14

Amazon Detective Administration GuideListing accounts in the Detective behavior graph (Console)

• The member account data would cause the behavior graph data volume to exceed the Detectivequota.

Listing accounts in the Detective behavior graph(Console)You can use the AWS Management Console to see and filter a list of accounts in your behavior graph.

To display the list of accounts in the behavior graph (console)


2. In the Detective navigation pane, choose Account management.

My member accounts lists your account and the member accounts that you invited to contributedata to the behavior graph. For each account, the list displays the following information:

• The AWS account identifier.• For member accounts only, the account root user email address.• The account status.• The data volume for the account. This is the percentage of data volume for the account relative

to the maximum allowed data volume for a behavior graph. Detective cannot retrieve the datavolume for member accounts that have not accepted the behavior graph invitation.

• The date when the account status was last updated.

To add a filter to the list of accounts in the behavior graph (console)

1. Choose the filter box.2. Choose the column that you want to use to filter the list.3. For the specified column, choose the value to use for the filter.4. To remove a filter, choose the x icon at the top right.5. To update the list with the most recent status information, choose the refresh icon at the top right.

Listing the accounts in the Detective behavior graph(Detective API, AWS CLI)You can use an API call or the AWS Command Line Interface to view a list of all invited and monitoredmember accounts in your behavior graph.

To retrieve a list of all of the invited and monitored member accounts (Detective API, AWSCLI)

• Detective API: Use the ListMembers operation. To identify the intended behavior graph, specify thebehavior graph ARN.

• AWS CLI: At the command line, run the list-members command.

aws detective list-members --graph-arn <graph ARN>

Example:

15



https://docs.aws.amazon.com/detective/latest/APIReference/API_ListMembers.html

Amazon Detective Administration GuideInviting member accounts to a behavior graph

aws detective list-members --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

To retrieve details about specific member accounts in your behavior graph (Detective API,AWS CLI)

• Detective API: Use the GetMembers operation. Specify the behavior graph ARN and the list of accountidentifiers for the member accounts.

• AWS CLI: At the command line, run the get-members command.

aws detective get-members --account-ids <member account IDs> --graph-arn <behavior graph ARN>

Example:

aws detective get-members --account-ids 444455556666 123456789012 --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

Inviting member accounts to a behavior graphThe master account can invite up to 1000 member accounts to contribute to a behavior graph.

At a high level, the process for inviting members to contribute to a behavior graph is as follows.

1. For each member account to add, the master account provides the AWS account identifier and theroot user email address.

2. Detective validates that the email address is the root user email address for the account.3. If the account information is valid, Detective sends the invitation to the member account.4. The member account accepts or declines the invitation.5. If the member account accepts the invitation, then Detective checks whether the member account has

been an Amazon GuardDuty customer for at least 48 hours.

If it has, then Detective checks whether the member account data would cause the data rate for thebehavior graph to exceed the quota.

6. If the member account passes both of those checks, then the member account status is Accepted(Enabled). Detective begins to ingest data from the member account into the behavior graph.

If it fails either of those checks, then the member account status is Accepted (Not enabled). Themember account does not contribute data to the behavior graph.

Inviting individual accounts to a behavior graph(Console)You can manually specify which member accounts to invite to contribute their data to a behavior graph.

To manually select the member accounts to invite (console)

1. Open the Detective console.2. In the Detective navigation pane, choose Account management.

16

https://docs.aws.amazon.com/detective/latest/APIReference/API_GetMembers


Amazon Detective Administration GuideInviting a list of member accounts

to a behavior graph (Console)

3. Under My member accounts, choose Invite individual accounts.4. Under Add accounts, add a member account to the invitation list.

a. Choose Add account.b. For AWS Account ID, enter the AWS account ID.c. For Email address, enter the root user email address for the account.

5. To remove an account from the list, choose Remove for that account.6. Under Personalize invitation email, add customized content to include in the invitation email.

For example, you can use this area to provide contact information. Or use it to remind the memberaccount that they need to attach the required IAM policy to their user or role before they can acceptthe invitation.

7. Member account IAM policy contains the text of the required IAM policy for member accounts. Theemail invitation includes this policy text. To copy the policy text, choose Copy.

8. Choose Invite.

Inviting a list of member accounts to a behaviorgraph (Console)From the Detective console, you can provide a .csv file containing a list of member accounts to invite toyour behavior graph.

The first line in the file is the header row. Each account is then listed on a separate line. Each memberaccount entry contains the AWS account ID and the account's root user email address.

Example:

Account ID,Email address111122223333,[email protected],[email protected]

When Detective processes the file, it ignores accounts that were already invited, unless the accountstatus is Verification failed. That status indicates that the email address provided for the account did notmatch the account's root user email address. In that case, Detective deletes the original invitation andtries again to verify the email address and send the invitation.

This option also provides a template that you can use to create the list of accounts.

To invite member accounts from a .csv list (console)

1. Open the Detective console.2. In the Detective navigation pane, choose Account management.3. Under My member accounts, choose Invite accounts from .csv.4. Under Add accounts, to download a template file to work from, choose Download .csv template.5. To select the file containing the list of accounts, choose Choose .csv file.6. Under Review member accounts, verify the list of member accounts that Detective found in the file.7. Under Personalize invitation email, add customized content to include in the invitation email.

For example, you can provide contact information, or remind the member account about therequired IAM policy.

8. Member account IAM policy contains the text of the required IAM policy for member accounts. Theemail invitation includes this policy text. To copy the policy text, choose Copy.

9. Choose Invite.

17


Amazon Detective Administration GuideInviting member accounts to a behavior

graph (Detective API, AWS CLI)

Inviting member accounts to a behavior graph(Detective API, AWS CLI)You can use the Detective API or the AWS Command Line Interface to invite member accounts tocontribute their data to a behavior graph.

To invite member accounts to a behavior graph (Detective API, AWS CLI)

• Detective API: Use the CreateMembers operation. You must provide the graph ARN. For eachaccount, specify the account identifier and the root user email address. You can optionally providecustom text to add to the invitation email.

• AWS CLI: At the command line, run the create-members command.

aws detective create-members --accounts AccountId=<AWS account ID>,EmailAddress=<root user email address> --graph-arn <behavior graph ARN> --message "<Custom message text>"

Example:

aws detective create-members --accounts AccountId=444455556666,[email protected] AccountId=123456789012,[email protected] --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234 --message "This is Paul Santos. I need to add your account to the data we use for security investigation in Amazon Detective. If you have any questions, contact me at [email protected]."

Adding a list of member accounts across Regions(Python script on GitHub)Detective provides an open-source script in GitHub that allows you to do the following:

• Add a specified list of member accounts to a master account's behavior graphs across a specified list ofRegions.

• If the master account does not have a behavior graph in a Region, then the script also enablesDetective and creates the behavior graph in that Region.

• Sends invitation emails to the member accounts.• Automatically accept the invitations for the member accounts.


Enabling a member account that is Accepted (Notenabled)

After a member account accepts an invitation, Amazon Detective checks whether it can enable themember account. If Detective cannot enable the member account, then it sets the member accountstatus to Accepted (Not enabled). This can happen for one of the following reasons.

• The member account has not been an Amazon GuardDuty customer for at least 48 hours.

18

https://docs.aws.amazon.com/detective/latest/APIReference/API_CreateMembers.html

Amazon Detective Administration GuideEnabling a member account that isAccepted (Not enabled) (Console)

• The member account data would cause the behavior graph data rate to exceed the quota.

Member accounts that are Accepted (Not enabled) do not contribute data to the behavior graph.

You can try to enable Accepted (Not enabled) member accounts. For example, if a member account wasnot a GuardDuty customer, you can try again 48 hours after the member account enables GuardDuty.

Enabling a member account that is Accepted (Notenabled) (Console)On the member account list, the Manage menu includes an option to enable selected member accountsthat are Accepted (Not enabled).

To enable a member account that is Accepted (Not enabled)

1. Open the Detective console.2. In the Detective navigation pane, choose Account management.3. Under My member accounts, select the check box for each member account to enable.

You can only enable member accounts that have a status of Accepted (Not enabled).4. Choose Manage accounts, then choose Enable.

Detective determines whether the member account can be enabled. If the member account can beenabled, the status changes to Accepted (Enabled).

Enabling a member account that is Accepted (Notenabled) (Detective API, AWS CLI)You can use an API call or the AWS Command Line Interface to enable a single member account that isAccepted (Not enabled).

To enable a member account that is Accepted (Not enabled)

• Detective API: Use the StartMonitoringMember API operation. You must provide the behavior graphARN. To identify the member account, use the AWS account identifier.

• AWS CLI: At the command line, run the start-monitoring-member command:

start-monitoring-member --graph-arn <behavior graph ARN> --account-id <AWS account ID>

For example:

start-monitoring-member --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234 --account-id 444455556666

Removing member accounts from a behaviorgraph

The master account can remove member accounts from a behavior graph at any time. When a memberaccount is removed from a behavior graph, the following occurs.

19


https://docs.aws.amazon.com/detective/latest/APIReference/API-StartMonitoringMember.html

Amazon Detective Administration GuideRemoving member accounts

from a behavior graph (Console)

• The member account is removed from My member accounts.• Amazon Detective stops ingesting data from the removed account.

Detective does not remove any existing data from the behavior graph, which aggregates data acrossmember accounts.

Removing member accounts from a behavior graph(Console)From your master account, you can use the AWS Management Console to remove member accounts froma behavior graph.

To remove member accounts (console)

1. Open the Detective console.2. In the Detective navigation pane, choose Account management.3. Under My member accounts, select the check box for each member account to delete.

You cannot delete your own account from the list.4. Choose Manage accounts. Then choose Remove account.5. When prompted to confirm, enter remove.6. Choose Remove member accounts.

Removing member accounts from a behavior graph(Detective API, AWS CLI)From your master account, you can use the Detective API or the AWS Command Line Interface to removemember accounts from a behavior graph.

To use remove member accounts from your behavior graph (Detective API, AWS CLI)

• Detective API: Use the DeleteMembers operation. Specify the graph ARN and the list of accountidentifiers for the member accounts to remove.

• AWS CLI: At the command line, run the delete-members command.

aws detective delete-members --account-ids <account ID list> --graph-arn <behavior graph ARN>

Example:

aws detective delete-members --account-ids 444455556666 123456789012 --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

Removing a list of member accounts across Regions(Python script on GitHub)Detective provides an open-source script in GitHub. You can use this script to remove a specified list ofmember accounts from the master account's behavior graphs across a specified list of Regions.

20


https://docs.aws.amazon.com/detective/latest/APIReference/API_DeleteMembers.html

Amazon Detective Administration GuideRemoving a list of member accounts

across Regions (Python script on GitHub)


21

Amazon Detective Administration GuideIAM policy for a member account

For member accounts: Managingbehavior graph invitations andmemberships

A member account receives an invitation from the master account for a behavior graph. The invitationindicates that the master account wants to use the member account's data in the behavior graph. Amember account can be invited to contribute to multiple behavior graphs. For more information, see thesection called “Viewing behavior graph invitations” (p. 23).

Amazon Detective charges each member account for the ingested data for each behavior graph that itcontributes to.

Before Detective can ingest and extract the member account's data, the member account must acceptthe invitation. If the member account declines the invitation, then the behavior graph does not use themember account's data. See the section called “Responding to a behavior graph invitation” (p. 24).

A member account can remove their account from a behavior graph at any time. When they remove theiraccount, Detective stops ingesting and extracting the account data into that behavior graph. See thesection called “Removing your account from a behavior graph” (p. 25).

Contents• Required IAM policy for a member account (p. 22)• Viewing your list of behavior graph invitations (p. 23)• Responding to a behavior graph invitation (p. 24)• Removing your account from a behavior graph (p. 25)

Required IAM policy for a member accountBefore a member account can view and manage invitations, the required IAM policy must be attached totheir principal. The principal can be an existing user or role, or you can create a new user or role to usefor Detective.

Ideally, the master account has their IAM administrator attach the required policy.

The member account IAM policy grants access to member account actions in Amazon Detective. Theemail invitation to contribute to a behavior graph includes the text of that IAM policy.

To use this policy, replace <behavior graph ARN> with the graph ARN.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "detective:AcceptInvitation", "detective:DisassociateMembership",

22

Amazon Detective Administration GuideViewing behavior graph invitations

"detective:RejectInvitation" ], "Resource": "<behavior graph ARN>" }, { "Effect":"Allow", "Action":["detective:ListInvitations"], "Resource":"*" } ]}

Viewing your list of behavior graph invitationsFrom the Amazon Detective console, Detective API, or AWS Command Line Interface, a member accountcan see their behavior graph invitations.

Viewing behavior graph invitations (Console)You can view behavior graph invitations from the AWS Management Console.

To view behavior graph invitations (console)


2. In the Detective navigation pane, choose Account management.

On the Account management page, My master accounts contains your open and accepted behaviorgraph invitations in the current Region.

The list does not contain invitations that you declined, memberships that you resigned, or membershipsthat the master account removed.

Each invitation shows the master account number, the date that the invitation was issued, and thecurrent status of the invitation.

• For invitations that you have not responded to, the status is Invited.• For invitations that you accepted, the status is either Accepted (Enabled) or Accepted (Not enabled).

If the status is Accepted (Enabled), then your account contributes data to the behavior graph.

If the status is Accepted (Not enabled), then your account does not contribute data to the behaviorgraph because of an issue with your account. This could occur for one of the following reasons.• When you accepted the invitation, your account was not an Amazon GuardDuty customer for at least

48 hours.• The addition of your account would cause the volume of data for the behavior graph to exceed the

Detective quota.

Viewing behavior graph invitations (Detective API,AWS CLI)You can list behavior graph invitations from the Detective API or the AWS Command Line Interface.

23



Amazon Detective Administration GuideResponding to a behavior graph invitation

To retrieve a list of open and accepted invitations to behavior graphs (Detective API, AWSCLI)

• Detective API: Use the ListInvitations operation.• AWS CLI: At the command line, run the list-invitations command.

aws detective list-invitations

Responding to a behavior graph invitationWhen you accept an invitation, Detective verifies that your account can be enabled for the behaviorgraph.

If it can be enabled, then Detective begins ingesting and extracting data from logs and findings into thebehavior graph as of that point in time. Your account is charged for the data.

If it cannot be enabled, then the invitation status is Accepted (Not enabled). Your account does notcontribute data to the behavior graph. Unless you remove your account from the behavior graph, themaster account can attempt to enable it at any time.

If you decline the invitation, then it is removed from your list of invitations, and Detective does not useyour account data in the behavior graph.

Responding to a behavior graph invitation (Console)You can use the AWS Management Console to respond to the email invitation, which includes a link tothe Detective console. You can only respond to an invitation that has a status of Invited.

To respond to a behavior graph invitation (console)

1. Open the Detective console.2. In the Detective navigation pane, choose Account management.3. Under My master accounts, to accept the invitation and begin contributing data to the behavior

graph, choose Accept invitation.

To decline the invitation and remove it from the list, choose Decline.

Responding to a behavior graph invitation (DetectiveAPI, AWS CLI)You can respond to behavior graph invitations from the Detective API or the AWS Command LineInterface.

To accept a behavior graph invitation (Detective API, AWS CLI)

• Detective API: Use the AcceptInvitation operation. You must specify the graph ARN.• AWS CLI: At the command line, run the accept-invitation command.

aws detective accept-invitation --graph-arn <behavior graph ARN>

Example:

24

https://docs.aws.amazon.com/detective/latest/APIReference/API_ListInvitations.html


https://docs.aws.amazon.com/detective/latest/APIReference/API_AcceptInvitation.html

Amazon Detective Administration GuideRemoving your account from a behavior graph

aws detective accept-invitation --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

To decline a behavior graph invitation (Detective API, AWS CLI)

• Detective API: Use the RejectInvitation operation. You must specify the graph ARN.• AWS CLI: At the command line, run the reject-invitation command.

aws detective reject-invitation --graph-arn <behavior graph ARN>

Example:

aws detective reject-invitation --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

Removing your account from a behavior graphAfter you accept an invitation, you can remove your account from a behavior graph at any time. Whenyou remove your account from a behavior graph, Amazon Detective stops ingesting data from youraccount into the behavior graph. Existing data remains in the behavior graph.

Removing your account from a behavior graph(Console)You can use the AWS Management Console to remove your account from a behavior graph.

To remove your account from a behavior graph (console)

1. Open the Detective console.2. In the Detective navigation pane, choose Account management.3. Under My master account, for the behavior graph you want to resign from, choose Resign.

Removing your account from a behavior graph(Detective API, AWS CLI)You can use the Detective API or the AWS Command Line Interface to remove your account from abehavior graph.

To remove your account from a behavior graph (Detective API, AWS CLI)

• Detective API: Use the DisassociateMembership operation. You must specify the graph ARN.• AWS CLI: At the command line, run the disassociate-membership command.

aws detective disassociate-membership --graph-arn <behavior graph ARN>

Example:

25

https://docs.aws.amazon.com/detective/latest/APIReference/API_RejectInvitation.html


https://docs.aws.amazon.com/detective/latest/APIReference/API_DisassociateMembership.html

Amazon Detective Administration GuideRemoving your account from a

behavior graph (Detective API, AWS CLI)

aws detective disassociate-membership --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

26

Amazon Detective Administration GuideMonitoring Detective usage and cost

Tracking actions and usage inAmazon Detective

To help you to track your Detective activity, the Usage page shows the amount of data ingested intoyour behavior graph. Detective also supports AWS CloudTrail logging.

Contents• Monitoring Amazon Detective usage and cost (p. 27)• Logging Amazon Detective API calls with AWS CloudTrail (p. 28)

Monitoring Amazon Detective usage and costAmazon Detective bills each account for the data used in each behavior graph that they belong to.Detective charges a tiered flat rate per GB for all data regardless of the source.

For master accounts, the Usage page of the Detective console shows the volume of data ingested intotheir behavior graph over the previous 30 days. Master accounts can also see a projected cost for atypical 30-day period.

During the free trial, the Usage page displays a notification that includes the number of days remaining.

To view Detective usage information


2. In the Detective navigation pane, under Settings, choose Usage.

Volume of data ingestedIngested volume by account lists the active accounts in the behavior graph. It does not list memberaccounts that were removed.

For each account, the ingested volume list provides the following information.

• The AWS account identifier and root user email address.• The date when the account began to contribute data to the behavior graph.

For the master account, this is the date when they enabled Detective.

For member accounts, this is the date when they accepted the behavior graph invitation.• The volume of ingested data from the account over the previous 30 days. The total includes all source

types.

Projected 30-day costProjected 30-day cost shows a projected cost for 30 days of data across the current accounts. Theprojected cost is based on the daily average volume for each account.

27



Amazon Detective Administration GuideLogging Detective API calls with CloudTrail

ImportantThis amount is a projected cost only. It projects the total cost of the behavior graph data for atypical 30-day time period. It is based on the usage from the previous 30 days. The projectedcost does not include member accounts that were removed from the behavior graph.

To calculate the projected cost, Detective does the following.

1. For each account, Detective calculates the average volume per day. It adds the data volume across allof the active days and then divides by the number of days that the account has been active.

If the account joined the behavior graph more than 30 days ago, then the number of days is 30. Ifthe account joined the graph fewer than 30 days ago, then it is the number of days since the accountjoined.

For example, if an account accepted the invitation 12 days ago, then Detective adds the volumeingested for those 12 days and then divides it by 12.

2. For each account, Detective multiplies its daily average by 30. This is the projected 30-day usage forthat account.

3. For each account, Detective uses its pricing model to calculate the projected 30-day cost for theprojected 30-day usage.

4. Detective combines the projected 30-day cost from all of the accounts.

Logging Amazon Detective API calls with AWSCloudTrail

Detective is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user,role, or an AWS service in Detective. CloudTrail captures all API calls for Detective as events. The callscaptured include calls from the Detective console and code calls to the Detective API operations.

• If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket,including events for Detective.

• If you don't configure a trail, you can still view the most recent events in the CloudTrail console inEvent history.

Using the information collected by CloudTrail, you can determine the following:

• The request that was made to Detective

• The IP address from which the request was made

• Who made the request

• When it was made

• Additional details about the request

To learn more about CloudTrail, see the AWS CloudTrail User Guide.

Detective information in CloudTrailCloudTrail is enabled on your AWS account when you create the account. When activity occurs inDetective, that activity is recorded in a CloudTrail event, along with other AWS service events, in Eventhistory. You can view, search, and download recent events in your AWS account. For more information,see Viewing Events with CloudTrail Event History.

28

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html

Amazon Detective Administration GuideUnderstanding Detective log file entries

For an ongoing record of events in your AWS account, including events for Detective, create a trail. A trailenables CloudTrail to deliver log files to an Amazon S3 bucket.

By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logsevents from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket thatyou specify. You also can configure other AWS services to further analyze and act upon the event datacollected in CloudTrail logs.

For more information, see the following:

• Overview for Creating a Trail• CloudTrail Supported Services and Integrations• Configuring Amazon SNS Notifications for CloudTrail• Receiving CloudTrail Log Files from Multiple Regions and Receiving CloudTrail Log Files from Multiple

Accounts

CloudTrail logs all Detective operations, which are documented in the Detective API Reference.

For example, calls to the CreateMembers, AcceptInvitation, and DeleteMembers operationsgenerate entries in the CloudTrail log files.

Every event or log entry contains information about who generated the request. The identityinformation helps you determine the following:

• Whether the request was made with root or AWS Identity and Access Management (IAM) usercredentials

• Whether the request was made with temporary security credentials for a role or a federated user• Whether the request was made by another AWS service

For more information, see the CloudTrail userIdentity Element.

Understanding Detective log file entriesA trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that youspecify. CloudTrail log files contain one or more log entries.

An event represents a single request from any source. Events include information about the requestedaction, the date and time of the action, request parameters, and so on. CloudTrail log files aren't anordered stack trace of the public API calls, so the entries don't appear in any specific order.

The following example shows a CloudTrail log entry that demonstrates the AcceptInvitation action.

{ "EventId": "f2545ee3-170f-4340-8af4-a983c669ce37", "Username": "JaneRoe", "EventTime": 1571956406.0, "CloudTrailEvent": "{\"eventVersion\":\"1.05\",\"userIdentity\":{\"type\":\"AssumedRole\",\"principalId\":\"AROAJZARKEP6WKJ5JHSUS:JaneRoe\",\"arn\":\"arn:aws:sts::111122223333:assumed-role/1A4R5SKSPGG9V/JaneRoe\",\"accountId\":\"111122223333\",\"accessKeyId\":\"AKIAIOSFODNN7EXAMPLE\",\"sessionContext\":{\"attributes\":{\"mfaAuthenticated\":\"false\",\"creationDate\":\"2019-10-24T21:54:56Z\"},\"sessionIssuer\":{\"type\":\"Role\",\"principalId\":\"AROAJZARKEP6WKJ5JHSUS\",\"arn\":\"arn:aws:iam::111122223333:role/1A4R5SKSPGG9V\",\"accountId\":\"111122223333\",\"userName\":\"JaneRoe\"}}},\"eventTime\":\"2019-10-24T22:33:26Z\",\"eventSource\":\"detective.amazonaws.com\",\"eventName\":\"AcceptInvitation\",\"awsRegion\":\"us-east-2\",\"sourceIPAddress\":\"192.0.2.123\",\"userAgent\":\"aws /3 aws-sdk-java/1.11.648

29

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html

https://docs.aws.amazon.com/detective/latest/APIReference/

https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html

Amazon Detective Administration GuideUnderstanding Detective log file entries

Linux/4.14.133-97.112.amzn2.x86_64 OpenJDK_64-Bit_Server_VM/25.201-b09 java/1.8.0_201 vendor/Oracle_Corporation exec-env/AWS_Lambda_java8\",\"errorCode\":\"ValidationException\",\"requestParameters\":{\"masterAccount\":\"111111111111\"},\"responseElements\":{\"message\":\"Invalid request body\"},\"requestID\":\"8437ff99-5ec4-4b1a-8353-173be984301f\",\"eventID\":\"f2545ee3-170f-4340-8af4-a983c669ce37\",\"readOnly\":false,\"eventType\":\"AwsApiCall\",\"recipientAccountId\":\"111122223333\"}", "EventName": "AcceptInvitation", "EventSource": "detective.amazonaws.com", "Resources": [] },

30

Amazon Detective Administration GuideData protection

Security in Amazon DetectiveCloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center andnetwork architecture that is built to meet the requirements of the most security-sensitive organizations.

Security is a shared responsibility between AWS and you. The shared responsibility model describes thisas security of the cloud and security in the cloud:

• Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services inthe AWS Cloud. AWS also provides you with services that you can use securely.

Third-party auditors regularly test and verify the effectiveness of our security as part of the AWScompliance programs.

To learn about the compliance programs that apply to Amazon Detective, see AWS Services in Scopeby Compliance Program.

• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are alsoresponsible for other factors including the sensitivity of your data, your company’s requirements, andapplicable laws and regulations.

This documentation helps you understand how to apply the shared responsibility model when usingDetective. The following topics show you how to configure Detective to meet your security andcompliance objectives. You also learn how to use other AWS services that help you to monitor and secureyour Detective resources.

Contents• Data protection in Amazon Detective (p. 31)• Identity and access management for Amazon Detective (p. 32)• Logging and monitoring in Amazon Detective (p. 44)• Compliance validation for Amazon Detective (p. 44)• Resilience in Amazon Detective (p. 45)• Infrastructure security in Amazon Detective (p. 45)• Security best practices for Amazon Detective (p. 45)

Data protection in Amazon DetectiveAmazon Detective conforms to the AWS shared responsibility model, which includes regulations andguidelines for data protection. AWS is responsible for protecting the global infrastructure that runs allthe AWS services. AWS maintains control over data hosted on this infrastructure, including the securityconfiguration controls for handling customer content and personal data. AWS customers and APNpartners, acting either as data controllers or data processors, are responsible for any personal data thatthey put in the AWS Cloud.

For data protection purposes, we recommend that you protect AWS account credentials and set upindividual user accounts with AWS Identity and Access Management (IAM), so that each user is given onlythe permissions necessary to fulfill their job duties. We also recommend that you secure your data in thefollowing ways:

• Use multi-factor authentication (MFA) with each account.• Use SSL/TLS to communicate with AWS resources.

31

http://aws.amazon.com/compliance/shared-responsibility-model/

http://aws.amazon.com/compliance/programs/


http://aws.amazon.com/compliance/services-in-scope/


http://aws.amazon.com/compliance/shared-responsibility-model/

Amazon Detective Administration GuideKey management

• Set up API and user activity logging with AWS CloudTrail.• Use AWS encryption solutions, along with all default security controls within AWS services.• Use advanced managed security services such as Amazon Macie, which assists in discovering and

securing personal data that is stored in Amazon S3.

We strongly recommend that you never put sensitive identifying information, such as your customers'account numbers, into free-form fields such as a Name field. This includes when you work with Detectiveor other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter intoDetective or other services might get picked up for inclusion in diagnostic logs. When you provide a URLto an external server, don't include credentials information in the URL to validate your request to thatserver.

For more information about data protection, see the AWS Shared Responsibility Model and GDPR blogpost on the AWS Security Blog.

Contents• Key management for Amazon Detective (p. 32)

Key management for Amazon DetectiveBecause Detective does not store any personally identifiable customer data, it uses AWS owned customermaster keys (CMKs).

This type of CMK can be used across multiple accounts. See the description of AWS owned CMKs in theAWS Key Management Service Developer Guide.

This type of CMK rotates automatically every three years (1095 days). See the description of key rotationin the AWS Key Management Service Developer Guide.

Identity and access management for AmazonDetective

AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securelycontrol access to AWS resources. IAM administrators control who can be authenticated (signed in) andauthorized (have permissions) to use Detective resources. IAM is an AWS service that you can use with noadditional charge.

Contents• Audience (p. 32)• Authenticating With Identities (p. 33)• Managing Access Using Policies (p. 35)• How Amazon Detective works with IAM (p. 36)• Amazon Detective identity-based policy examples (p. 39)• Troubleshooting Amazon Detective identity and access (p. 43)

AudienceHow you use AWS Identity and Access Management (IAM) differs, depending on the work you do inDetective.

32

http://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/

https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk

https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk

https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html

https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html

Amazon Detective Administration GuideAuthenticating With Identities

Service user – If you use the Detective service to do your job, then your administrator provides you withthe credentials and permissions that you need. As you use more Detective features to do your work, youmight need additional permissions. Understanding how access is managed can help you request the rightpermissions from your administrator. If you cannot access a feature in Detective, see TroubleshootingAmazon Detective identity and access (p. 43).

Service administrator – If you're in charge of Detective resources at your company, you probably havefull access to Detective. It's your job to determine which Detective features and resources your employeesshould access. You must then submit requests to your IAM administrator to change the permissions ofyour service users. Review the information on this page to understand the basic concepts of IAM. Tolearn more about how your company can use IAM with Detective, see How Amazon Detective works withIAM (p. 36).

IAM administrator – If you're an IAM administrator, you might want to learn details about how you canwrite policies to manage access to Detective. To view example Detective identity-based policies that youcan use in IAM, see Amazon Detective identity-based policy examples (p. 39).

Authenticating With IdentitiesAuthentication is how you sign in to AWS using your identity credentials. For more information aboutsigning in using the AWS Management Console, see The IAM Console and Sign-in Page in the IAM UserGuide.

You must be authenticated (signed in to AWS) as the AWS account root user, an IAM user, or by assumingan IAM role. You can also use your company's single sign-on authentication, or even sign in using Googleor Facebook. In these cases, your administrator previously set up identity federation using IAM roles.When you access AWS using credentials from another company, you are assuming a role indirectly.

To sign in directly to the AWS Management Console, use your password with your root user email or yourIAM user name. You can access AWS programmatically using your root user or IAM user access keys. AWSprovides SDK and command line tools to cryptographically sign your request using your credentials. Ifyou don’t use AWS tools, you must sign the request yourself. Do this using Signature Version 4, a protocolfor authenticating inbound API requests. For more information about authenticating requests, seeSignature Version 4 Signing Process in the AWS General Reference.

Regardless of the authentication method that you use, you might also be required to provide additionalsecurity information. For example, AWS recommends that you use multi-factor authentication (MFA) toincrease the security of your account. To learn more, see Using Multi-Factor Authentication (MFA) in AWSin the IAM User Guide.

AWS Account Root UserWhen you first create an AWS account, you begin with a single sign-in identity that has complete accessto all AWS services and resources in the account. This identity is called the AWS account root user andis accessed by signing in with the email address and password that you used to create the account. Westrongly recommend that you do not use the root user for your everyday tasks, even the administrativeones. Instead, adhere to the best practice of using the root user only to create your first IAM user. Thensecurely lock away the root user credentials and use them to perform only a few account and servicemanagement tasks.

IAM Users and GroupsAn IAM user is an identity within your AWS account that has specific permissions for a single person orapplication. An IAM user can have long-term credentials such as a user name and password or a set ofaccess keys. To learn how to generate access keys, see Managing Access Keys for IAM Users in the IAMUser Guide. When you generate access keys for an IAM user, make sure you view and securely save the key

33

https://docs.aws.amazon.com/IAM/latest/UserGuide/console.html

https://console.aws.amazon.com/

https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

Amazon Detective Administration GuideAuthenticating With Identities

pair. You cannot recover the secret access key in the future. Instead, you must generate a new access keypair.

An IAM group is an identity that specifies a collection of IAM users. You can't sign in as a group. Youcan use groups to specify permissions for multiple users at a time. Groups make permissions easier tomanage for large sets of users. For example, you could have a group named IAMAdmins and give thatgroup permissions to administer IAM resources.

Users are different from roles. A user is uniquely associated with one person or application, but a roleis intended to be assumable by anyone who needs it. Users have permanent long-term credentials, butroles provide temporary credentials. To learn more, see When to Create an IAM User (Instead of a Role) inthe IAM User Guide.

IAM Roles

An IAM role is an identity within your AWS account that has specific permissions. It is similar to an IAMuser, but is not associated with a specific person. You can temporarily assume an IAM role in the AWSManagement Console by switching roles. You can assume a role by calling an AWS CLI or AWS APIoperation or by using a custom URL. For more information about methods for using roles, see Using IAMRoles in the IAM User Guide.

IAM roles with temporary credentials are useful in the following situations:

• Temporary IAM user permissions – An IAM user can assume an IAM role to temporarily take ondifferent permissions for a specific task.

• Federated user access – Instead of creating an IAM user, you can use existing identities from AWSDirectory Service, your enterprise user directory, or a web identity provider. These are known asfederated users. AWS assigns a role to a federated user when access is requested through an identityprovider. For more information about federated users, see Federated Users and Roles in the IAM UserGuide.

• Cross-account access – You can use an IAM role to allow someone (a trusted principal) in a differentaccount to access resources in your account. Roles are the primary way to grant cross-account access.However, with some AWS services, you can attach a policy directly to a resource (instead of using a roleas a proxy). To learn the difference between roles and resource-based policies for cross-account access,see How IAM Roles Differ from Resource-based Policies in the IAM User Guide.

• AWS service access – A service role is an IAM role that a service assumes to perform actions in youraccount on your behalf. When you set up some AWS service environments, you must define a rolefor the service to assume. This service role must include all the permissions that are required for theservice to access the AWS resources that it needs. Service roles vary from service to service, but manyallow you to choose your permissions as long as you meet the documented requirements for thatservice. Service roles provide access only within your account and cannot be used to grant accessto services in other accounts. You can create, modify, and delete a service role from within IAM. Forexample, you can create a role that allows Amazon Redshift to access an Amazon S3 bucket on yourbehalf and then load data from that bucket into an Amazon Redshift cluster. For more information, seeCreating a Role to Delegate Permissions to an AWS Service in the IAM User Guide.

• Applications running on Amazon EC2 – You can use an IAM role to manage temporary credentialsfor applications that are running on an EC2 instance and making AWS CLI or AWS API requests.This is preferable to storing access keys within the EC2 instance. To assign an AWS role to an EC2instance and make it available to all of its applications, you create an instance profile that is attachedto the instance. An instance profile contains the role and enables programs that are running on theEC2 instance to get temporary credentials. For more information, see Using an IAM Role to GrantPermissions to Applications Running on Amazon EC2 Instances in the IAM User Guide.

To learn whether to use IAM roles, see When to Create an IAM Role (Instead of a User) in the IAM UserGuide.

34

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html#id_which-to-choose

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_access-management.html#intro-access-roles

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_compare-resource-policies.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html#id_which-to-choose_role

Amazon Detective Administration GuideManaging Access Using Policies

Managing Access Using PoliciesYou control access in AWS by creating policies and attaching them to IAM identities or AWS resources. Apolicy is an object in AWS that, when associated with an identity or resource, defines their permissions.AWS evaluates these policies when an entity (root user, IAM user, or IAM role) makes a request.Permissions in the policies determine whether the request is allowed or denied. Most policies are storedin AWS as JSON documents. For more information about the structure and contents of JSON policydocuments, see Overview of JSON Policies in the IAM User Guide.

An IAM administrator can use policies to specify who has access to AWS resources, and what actionsthey can perform on those resources. Every IAM entity (user or role) starts with no permissions. In otherwords, by default, users can do nothing, not even change their own password. To give a user permissionto do something, an administrator must attach a permissions policy to a user. Or the administrator canadd the user to a group that has the intended permissions. When an administrator gives permissions to agroup, all users in that group are granted those permissions.

IAM policies define permissions for an action regardless of the method that you use to perform theoperation. For example, suppose that you have a policy that allows the iam:GetRole action. A user withthat policy can get role information from the AWS Management Console, the AWS CLI, or the AWS API.

Identity-Based PoliciesIdentity-based policies are JSON permissions policy documents that you can attach to an identity, suchas an IAM user, role, or group. These policies control what actions that identity can perform, on whichresources, and under what conditions. To learn how to create an identity-based policy, see Creating IAMPolicies in the IAM User Guide.

Identity-based policies can be further categorized as inline policies or managed policies. Inline policiesare embedded directly into a single user, group, or role. Managed policies are standalone policies thatyou can attach to multiple users, groups, and roles in your AWS account. Managed policies include AWSmanaged policies and customer managed policies. To learn how to choose between a managed policy oran inline policy, see Choosing Between Managed Policies and Inline Policies in the IAM User Guide.

Resource-Based PoliciesResource-based policies are JSON policy documents that you attach to a resource such as an Amazon S3bucket. Service administrators can use these policies to define what actions a specified principal (accountmember, user, or role) can perform on that resource and under what conditions. Resource-based policiesare inline policies. There are no managed resource-based policies.

Access Control Lists (ACLs)Access control lists (ACLs) are a type of policy that controls which principals (account members, users, orroles) have permissions to access a resource. ACLs are similar to resource-based policies, although theydo not use the JSON policy document format. Amazon S3, AWS WAF, and Amazon VPC are examplesof services that support ACLs. To learn more about ACLs, see Access Control List (ACL) Overview in theAmazon Simple Storage Service Developer Guide.

Other Policy TypesAWS supports additional, less-common policy types. These policy types can set the maximumpermissions granted to you by the more common policy types.

• Permissions boundaries – A permissions boundary is an advanced feature in which you set themaximum permissions that an identity-based policy can grant to an IAM entity (IAM user or role).

35

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#choosing-managed-or-inline

https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html

Amazon Detective Administration GuideHow Amazon Detective works with IAM

You can set a permissions boundary for an entity. The resulting permissions are the intersection ofentity's identity-based policies and its permissions boundaries. Resource-based policies that specifythe user or role in the Principal field are not limited by the permissions boundary. An explicit denyin any of these policies overrides the allow. For more information about permissions boundaries, seePermissions Boundaries for IAM Entities in the IAM User Guide.

• Service control policies (SCPs) – SCPs are JSON policies that specify the maximum permissions foran organization or organizational unit (OU) in AWS Organizations. AWS Organizations is a service forgrouping and centrally managing multiple AWS accounts that your business owns. If you enable allfeatures in an organization, then you can apply service control policies (SCPs) to any or all of youraccounts. The SCP limits permissions for entities in member accounts, including each AWS accountroot user. For more information about Organizations and SCPs, see How SCPs Work in the AWSOrganizations User Guide.

• Session policies – Session policies are advanced policies that you pass as a parameter when youprogrammatically create a temporary session for a role or federated user. The resulting session'spermissions are the intersection of the user or role's identity-based policies and the session policies.Permissions can also come from a resource-based policy. An explicit deny in any of these policiesoverrides the allow. For more information, see Session Policies in the IAM User Guide.

Multiple Policy Types

When multiple types of policies apply to a request, the resulting permissions are more complicated tounderstand. To learn how AWS determines whether to allow a request when multiple policy types areinvolved, see Policy Evaluation Logic in the IAM User Guide.

How Amazon Detective works with IAMDetective uses IAM identity-based policies to grant permissions for the following types of users andactions:

• Master accounts – The master account is the owner of a behavior graph, which uses data from theiraccount. Master accounts can invite member accounts to also contribute their data to the behaviorgraph. They also use the behavior graph for triage and investigation of findings and resourcesassociated with those accounts.

You can set up different policies to allow different users from the master account to performdifferent types of tasks. For example, a user from a master account might only have permissions tomanage member accounts. Another user might only have permissions to use the behavior graph forinvestigation.

• Member accounts – A member account is an account that is invited to contribute data to a behaviorgraph. A member account responds to an invitation. After accepting an invitation, a member accountcan remove their account from the behavior graph.

To get a high-level view of how Detective and other AWS services work with IAM, see AWS Services ThatWork with IAM in the IAM User Guide.

Detective identity-based policies

With IAM identity-based policies, you can specify allowed or denied actions and resources, as well as theconditions under which actions are allowed or denied. Detective supports specific actions, resources, andcondition keys.

To learn about all of the elements that you use in a JSON policy, see IAM JSON Policy ElementsReference in the IAM User Guide.

36

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html

https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_about-scps.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html


Actions

The Action element of an IAM identity-based policy describes the specific action or actions that will beallowed or denied by the policy. Policy actions usually have the same name as the associated AWS APIoperation. The action is used in a policy to grant permissions to perform the associated operation.

Policy statements must include either an Action element or a NotAction element. The Actionelement lists the actions allowed by the policy. The NotAction element lists the actions that are notallowed.

The actions defined for Detective reflect tasks that you can perform using Detective. Policy actions inDetective have the following prefix: detective:.

For example, to grant permission to use the CreateMembers API operation to invite member accountsto a behavior graph, you include the detective:CreateMembers action in their policy.

To specify multiple actions in a single statement, separate them with commas. For example, for amember account, the policy includes the set of actions related to managing an invitation:

"Action": [ "detective:ListInvitations", "detective:AcceptInvitation", "detective:RejectInvitation", "detective:DisassociateMembership]

You can also use wildcards (*) to specify multiple actions. For example, to manage the data used in theirbehavior graph, master accounts in Detective must be able to perform the following tasks:

• View their list of member accounts (ListMembers).• Get information about selected member accounts (GetMembers).• Invite member accounts to their behavior graph (CreateMembers).• Remove members from their behavior graph (DeleteMembers).

Instead of listing these actions separately, you can grant access to all actions that end with the wordMembers. The policy for that could include the following action:

"Action": "detective:*Members"

To see a list of Detective actions, see Actions Defined by Amazon Detective in the IAM User Guide.

Resources

The Resource element specifies the object or objects to which the action applies. Statements mustinclude either a Resource or a NotResource element. You specify a resource using an ARN or using thewildcard (*) to indicate that the statement applies to all resources.

For more information about the format of ARNs, see Amazon Resource Names (ARNs) and AWS ServiceNamespaces.

For Detective, the only resource type is the behavior graph. The behavior graph resource in Detective hasthe following ARN:

arn:aws:detective:${Region}:${AccountId}:graph:${GraphId}

37

https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazondetective.html#amazondetective-actions-as-permissions

https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html

https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html


For example, a behavior graph has the following values:

• The Region for the behavior graph is us-east-1.

• The account ID for the master account ID is 111122223333.

• The graph ID of the behavior graph is 027c7c4610ea4aacaf0b883093cab899.

To identify this behavior graph in a Resource statement, you would use the following ARN:

"Resource": "arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899"

To specify multiple resources in a Resource statement, use commas to separate them.

"Resource": [ "resource1", "resource2"]

For example, the same AWS account may be invited to be a member account in more than one behaviorgraph. In the policy for that member account, the Resource statement would list the behavior graphsthey were invited to.

"Resource": [ "arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899", "arn:aws:detective:us-east-1:444455556666:graph:056d2a9521xi2bbluw1d164680eby416"]

Some Detective actions, such as creating a behavior graph, listing behavior graphs, and listing behaviorgraph invitations, are not performed on a specific behavior graph. For those actions, the Resourcestatement must use the wildcard (*).

"Resource": "*"

For master account actions, Detective always verifies that the user making the request belongs to themaster account for the affected behavior graph. For member account actions, Detective always verifiesthat the user making the request belongs to the member account. Even if an IAM policy grants access toa behavior graph, if the user does not belong to the correct account, the user cannot perform the action.

For all actions that are performed on a specific behavior graph, the IAM policy should include the graphARN. The graph ARN can be added later. For example, when an account first enables Detective, the initialIAM policy provides access to all Detective actions, using the wildcard for the graph ARN. This allows theuser to immediately start to manage member accounts for and conduct investigations in their behaviorgraph. After the behavior graph is created, you can update the policy to add the graph ARN.

Condition keys

The Condition element (or Condition block) lets you specify conditions in which a statement is ineffect. The Condition element is optional. You can build conditional expressions that use conditionoperators, such as equals or less than, to match the condition in the policy with values in the request.

If you specify multiple Condition elements in a statement, or multiple keys in a single Conditionelement, AWS evaluates them using a logical AND operation. If you specify multiple values for a singlecondition key, AWS evaluates the condition using a logical OR operation. All of the conditions must bemet before the statement's permissions are granted.

38

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html

Amazon Detective Administration GuideIdentity-based policy examples

You can also use placeholder variables when you specify conditions. For example, you can grant an IAMuser permission to access a resource only if it is tagged with their IAM user name. For more information,see IAM Policy Elements: Variables and Tags in the IAM User Guide.

Detective does not define its own set of condition keys. It does support using global condition keys. Tosee all AWS global condition keys, see AWS Global Condition Context Keys in the IAM User Guide.

To learn which actions and resources allow you to use a condition key, see Actions Defined by AmazonDetective.

Examples

To view examples of Detective identity-based policies, see Amazon Detective identity-based policyexamples (p. 39).

Detective resource-based policies (Not supported)Detective does not support resource-based policies.

Authorization based on Detective tags (Not supported)Detective does not support tagging resources or controlling access based on tags.

Detective IAM RolesAn IAM role is an entity within your AWS account that has specific permissions.

Using temporary credentials with Detective

You can use temporary credentials to sign in with federation, assume an IAM role, or to assume a cross-account role. You obtain temporary security credentials by calling AWS STS API operations such asAssumeRole or GetFederationToken.

Detective supports using temporary credentials.

Service-linked roles (Not supported)

Service-linked roles allow AWS services to access resources in other services to complete an action onyour behalf. Service-linked roles appear in your IAM account and are owned by the service. An IAMadministrator can view but not edit the permissions for service-linked roles.

Detective does not support service-linked roles.

Service roles (Not supported)

This feature allows a service to assume a service role on your behalf. This role allows the service toaccess resources in other services to complete an action on your behalf. Service roles appear in yourIAM account and are owned by the account. This means that an IAM administrator can change thepermissions for this role. However, doing so might break the functionality of the service.

Detective does not support service roles.

Amazon Detective identity-based policy examplesBy default, IAM users and roles don't have permission to create or modify Detective resources. They alsocan't perform tasks using the AWS Management Console, AWS CLI, or AWS API.

39

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html



https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html

https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html

https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role


An IAM administrator must create IAM policies that grant users and roles permission to perform specificAPI operations on the specified resources they need. The administrator then attaches those policies tothe IAM users or groups that require those permissions.

To learn how to create an IAM identity-based policy using these example JSON policy documents, seeCreating Policies on the JSON Tab in the IAM User Guide.

Topics• Policy best practices (p. 40)

• Using the Detective console (p. 40)

• Allowing users to view their own permissions (p. 41)

• Master account: Managing the member accounts in a behavior graph (p. 41)

• Master account: Using a behavior graph for investigation (p. 42)

• Member account: Managing behavior graph invitations and memberships (p. 42)

Policy best practicesIdentity-based policies are very powerful. They determine whether someone can create, access, or deleteDetective resources in your account. These actions can incur costs for your AWS account. When youcreate or edit identity-based policies, follow these guidelines and recommendations:

• Get Started Using AWS Managed Policies – To start using Detective quickly, use AWS managedpolicies to give your employees the permissions they need. These policies are already available inyour account and are maintained and updated by AWS. For more information, see Get Started UsingPermissions With AWS Managed Policies in the IAM User Guide.

• Grant Least Privilege – When you create custom policies, grant only the permissions requiredto perform a task. Start with a minimum set of permissions and grant additional permissions asnecessary. Doing so is more secure than starting with permissions that are too lenient and then tryingto tighten them later. For more information, see Grant Least Privilege in the IAM User Guide.

• Enable MFA for Sensitive Operations – For extra security, require IAM users to use multi-factorauthentication (MFA) to access sensitive resources or API operations. For more information, see UsingMulti-Factor Authentication (MFA) in AWS in the IAM User Guide.

• Use Policy Conditions for Extra Security – To the extent that it's practical, define the conditions underwhich your identity-based policies allow access to a resource. For example, you can write conditions tospecify a range of allowable IP addresses that a request must come from. You can also write conditionsto allow requests only within a specified date or time range, or to require the use of SSL or MFA. Formore information, see IAM JSON Policy Elements: Condition in the IAM User Guide.

Using the Detective consoleTo use the Amazon Detective console, the user or role must have access to the relevant actions, whichmatch corresponding actions in the API.

To enable Detective and become a master account for a behavior graph, the user or role must be grantedpermission for the CreateGraph action.

To use the Detective console to perform any master account actions, the user or role must be grantedpermission for the ListGraphs action. This grants permission to retrieve the behavior graphs theiraccount is a master for. They also must be granted permission to perform specific master accountactions.

The most basic master account actions are to view a list of member accounts in a behavior graph, and touse the behavior graph for investigation.

40

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-json-editor

https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-use-aws-defined-policies

https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-use-aws-defined-policies

https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege



https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html


• To view the list of member accounts in a behavior graph, the principal must be granted permission forthe ListMembers action.

• To conduct investigation in a behavior graph, the principal must be granted permission for theSearchGraph action.

To use the Detective console to perform any member account actions, the user or role must be grantedpermission for the ListInvitations action. This grants permission to view behavior graph invitations.They can then be granted permission for specific member account actions.

Allowing users to view their own permissionsThis example shows how you might create a policy that allows IAM users to view the inline and managedpolicies that are attached to their user identity. This policy includes permissions to complete this actionon the console or programmatically using the AWS CLI or AWS API.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "ViewOwnUserInfo", "Effect": "Allow", "Action": [ "iam:GetUserPolicy", "iam:ListGroupsForUser", "iam:ListAttachedUserPolicies", "iam:ListUserPolicies", "iam:GetUser" ], "Resource": ["arn:aws:iam::*:user/${aws:username}"] }, { "Sid": "NavigateInConsole", "Effect": "Allow", "Action": [ "iam:GetGroupPolicy", "iam:GetPolicyVersion", "iam:GetPolicy", "iam:ListAttachedGroupPolicies", "iam:ListGroupPolicies", "iam:ListPolicyVersions", "iam:ListPolicies", "iam:ListUsers" ], "Resource": "*" } ]}

Master account: Managing the member accounts in a behaviorgraphThis example policy is intended for master account users who are only responsible for managingthe member accounts used in the behavior graph. The policy also allows the user to view the usageinformation and deactivate Detective. The policy does not grant permission to use the behavior graphfor investigation.

{"Version":"2012-10-17", "Statement":[ {

41


"Effect":"Allow", "Action":["detective:ListMembers","detective:CreateMembers","detective:DeleteMembers","detective:DeleteGraph","detective:Get*","detective:StartMonitoringMember"], "Resource":"arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899" }, { "Effect":"Allow", "Action":["detective:CreateGraph","detective:ListGraphs"], "Resource":"*" } ]}

Master account: Using a behavior graph for investigationThis example policy is intended for master account users who use the behavior graph for investigationonly. They cannot view or edit the list of member accounts in the behavior graph.

{"Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":["detective:SearchGraph"], "Resource":"arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899" }, { "Effect":"Allow", "Action":["detective:ListGraphs"], "Resource":"*" } ]}

Member account: Managing behavior graph invitations andmembershipsThis example policy is intended for users belonging to a member account. In the example, the memberaccount belongs to two behavior graphs. The policy grants permission to respond to invitations andremove the member account from the behavior graph.

{"Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":["detective:AcceptInvitation","detective:RejectInvitation","detective:DisassociateMembership"], "Resource":[ "arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899", "arn:aws:detective:us-east-1:444455556666:graph:056d2a9521xi2bbluw1d164680eby416" ] }, { "Effect":"Allow", "Action":["detective:ListInvitations"], "Resource":"*" } ]}

42

Amazon Detective Administration GuideTroubleshooting identity and access

Troubleshooting Amazon Detective identity andaccessUse the following information to help you diagnose and fix common issues that you might encounterwhen working with Detective and IAM.

I am not authorized to perform an action in DetectiveIf the AWS Management Console tells you that you're not authorized to perform an action, then youmust contact your administrator for assistance. Your administrator is the person that provided you withyour user name and password.

The following example error occurs when the mateojackson IAM user tries to use the consoleto accept an invitation to become a member account for a behavior graph, but does not havedetective:AcceptInvitation permissions.

User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: detective:AcceptInvitation on resource: arn:aws:detective:us-east-1:444455556666:graph:567856785678

In this case, Mateo asks his administrator to update his policies to allow him to access thearn:aws:detective:us-east-1:444455556666:graph:567856785678 resource using thedetective:AcceptInvitation action.

I am not authorized to perform iam:PassRoleIf you receive an error that you're not authorized to perform the iam:PassRole action, then you mustcontact your administrator for assistance. Your administrator is the person that provided you with youruser name and password. Ask that person to update your policies to allow you to pass a role to Detective.

Some AWS services allow you to pass an existing role to that service, instead of creating a new servicerole or service-linked role. To do this, you must have permissions to pass the role to the service.

The following example error occurs when an IAM user named marymajor tries to use the console toperform an action in Detective. However, the action requires the service to have permissions granted by aservice role. Mary does not have permissions to pass the role to the service.

User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole

In this case, Mary asks her administrator to update her policies to allow her to perform theiam:PassRole action.

I want to view my access keysAfter you create your IAM user access keys, you can view your access key ID at any time. However, youcan't view your secret access key again. If you lose your secret key, you must create a new access key pair.

Access keys consist of two parts: an access key ID (for example, AKIAIOSFODNN7EXAMPLE) and a secretaccess key (for example, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). Like a user name andpassword, you must use both the access key ID and secret access key together to authenticate yourrequests. Manage your access keys as securely as you do your user name and password.

ImportantDo not provide your access keys to a third party, even to help find your canonical user ID. Bydoing this, you might give someone permanent access to your account.

43

https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html#FindingCanonicalId

Amazon Detective Administration GuideLogging and monitoring

When you create an access key pair, you are prompted to save the access key ID and secret access key ina secure location. The secret access key is available only at the time you create it. If you lose your secretaccess key, you must add new access keys to your IAM user. You can have a maximum of two access keys.If you already have two, you must delete one key pair before creating a new one. To view instructions,see Managing Access Keys in the IAM User Guide.

I'm an administrator and want to allow others to accessDetectiveTo allow others to access Detective, you must create an IAM entity (user or role) for the person orapplication that needs access. They will use the credentials for that entity to access AWS. You must thenattach a policy to the entity that grants them the correct permissions in Detective.

To get started right away, see Creating Your First IAM Delegated User and Group in the IAM User Guide.

I want to allow people outside of my AWS account to access myDetective resourcesYou can create a role that users in other accounts or people outside of your organization can use toaccess your resources. You can specify who is trusted to assume the role. For services that supportresource-based policies or access control lists (ACLs), you can use those policies to grant people access toyour resources.

To learn more, consult the following:

• To learn whether Detective supports these features, see How Amazon Detective works withIAM (p. 36).

• To learn how to provide access to your resources across AWS accounts that you own, see ProvidingAccess to an IAM User in Another AWS Account That You Own in the IAM User Guide.

• To learn how to provide access to your resources to third-party AWS accounts, see Providing Access toAWS Accounts Owned by Third Parties in the IAM User Guide.

• To learn how to provide access through identity federation, see Providing Access to ExternallyAuthenticated Users (Identity Federation) in the IAM User Guide.

• To learn the difference between using roles and resource-based policies for cross-account access, seeHow IAM Roles Differ from Resource-based Policies in the IAM User Guide.

Logging and monitoring in Amazon DetectiveAmazon Detective is integrated AWS CloudTrail. CloudTrail captures all API calls for Detective as events.

For details on using CloudTrail logging for Detective, see the section called “Logging Detective API callswith CloudTrail” (p. 28).

Compliance validation for Amazon DetectiveDetective is not in scope of any AWS compliance programs.

For a list of AWS services in scope of specific compliance programs, see AWS Services in Scope byCompliance Program. For general information, see AWS Compliance Programs.

You can download third-party audit reports using AWS Artifact. For more information, see DownloadingReports in AWS Artifact.

44

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey

https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-delegated-user.html



https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_compare-resource-policies.html




https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html

https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html

Amazon Detective Administration GuideResilience

AWS provides the following resources to help with compliance:

• Security and Compliance Quick Start Guides – These deployment guides discuss architecturalconsiderations and provide steps for deploying security- and compliance-focused baselineenvironments on AWS.

• Evaluating resources with rules in the AWS Config Developer Guide – The AWS Config service assesseshow well your resource configurations comply with internal practices, industry guidelines, andregulations.

• AWS Security Hub – This AWS service provides a comprehensive view of your security state within AWSthat helps you check your compliance with security industry standards and best practices.

Resilience in Amazon DetectiveThe AWS global infrastructure is built around AWS Regions and Availability Zones. AWS Regions providemultiple physically separated and isolated Availability Zones, which are connected with low-latency,high-throughput, and highly redundant networking. With Availability Zones, you can design and operateapplications and databases that automatically fail over between zones without interruption. AvailabilityZones are more highly available, fault tolerant, and scalable than traditional single or multiple datacenter infrastructures.

For more information about AWS Regions and Availability Zones, see AWS Global Infrastructure.

In addition to the AWS global infrastructure, Detective makes use of the resiliency built into AmazonDynamoDB and Amazon Simple Storage Service (Amazon S3).

The Detective architecture is also resilient to the failure of a single Availability Zone. This resilience isbuilt into Detective, and does not require any configuration.

Infrastructure security in Amazon DetectiveAs a managed service, Amazon Detective is protected by the AWS global network security proceduresthat are described in the Amazon Web Services: Overview of Security Processes whitepaper.

You use AWS published API calls to access Detective through the network. Clients must supportTransport Layer Security (TLS) 1.0 or later. We recommend TLS 1.2 or later. Clients must also supportcipher suites with perfect forward secrecy (PFS) such as Ephemeral Diffie-Hellman (DHE) or Elliptic CurveEphemeral Diffie-Hellman (ECDHE). Most modern systems such as Java 7 and later support these modes.

Additionally, requests must be signed by using an access key ID and a secret access key that is associatedwith an IAM principal. For more information on access keys, see Managing access keys in the IAM UserGuide.

If you prefer, you can use the AWS Security Token Service (AWS STS) to generate temporary securitycredentials to sign requests.

Security best practices for Amazon DetectiveDetective provides a number of security features to consider as you develop and implement yourown security policies. The following best practices are general guidelines and don’t represent acomplete security solution. Because these best practices might not be appropriate or sufficient for yourenvironment, treat them as helpful considerations rather than prescriptions.

For Detective, the security best practices are associated with managing the accounts in a behavior graph.

45

http://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance

https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html

https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html

http://aws.amazon.com/about-aws/global-infrastructure/

https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html

Amazon Detective Administration GuideBest practices for master accounts

Best practices for master accountsWhen inviting member accounts to your behavior graph, only invite accounts that you oversee.

Limit access to the behavior graph. When a user has access to a behavior graph, they can see all of thefindings for the member accounts. Such findings might expose sensitive security information.

Best practices for member accountsWhen you receive an invitation to a behavior graph, make sure to validate the source of the invitation.

Check the AWS account identifier of the master account that sent the invitation. Verify that you knowwho the account belongs to, and that the inviting account has a legitimate reason to monitor yoursecurity data.

46

Amazon Detective Administration GuideDisabling Detective (Console)

Disabling Amazon DetectiveThe master account for a behavior graph can disable Amazon Detective from the Detective console, theDetective API, or AWS Command Line Interface. When you disable Detective, the behavior graph and itsassociated Detective data are deleted.

Once a behavior graph is deleted, it cannot be restored.

Contents• Disabling Detective (Console) (p. 47)• Disabling Detective (Detective API, AWS CLI) (p. 47)• Disabling Detective across Regions (Python script on GitHub) (p. 47)

Disabling Detective (Console)You can disable Amazon Detective from the AWS Management Console.

To disable Detective (console)

1. Open the Detective console.2. In the Detective navigation pane, under Settings, choose General.3. On the General page, under Disable Detective, choose Disable Detective.4. When prompted to confirm, type disable.5. Choose Disable Detective.

Disabling Detective (Detective API, AWS CLI)You can disable Amazon Detective from the Detective API or the AWS Command Line Interface.

To disable Detective (Detective API, AWS CLI)

• Detective API: Use the DeleteGraph operation. You must provide the graph ARN.• AWS CLI: At the command line, run the delete-graph command.

aws detective delete-graph --graph-arn <graph ARN>

Example:

aws detective delete-graph --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

Disabling Detective across Regions (Python scripton GitHub)

Detective provides an open-source script in GitHub that allows you to disable Detective for a masteraccount across a specified list of Regions.

47


https://docs.aws.amazon.com/detective/latest/APIReference/API_DeleteGraph.html

Amazon Detective Administration GuideDisabling Detective across

Regions (Python script on GitHub)


48

Amazon Detective Administration GuideOverview of the enableDetective.py script

Using the Amazon Detective Pythonscripts

Amazon Detective provides a set of open-source Python scripts in the GitHub repository amazon-detective-multiaccount-scripts. The scripts require Python 3.

You can use these to perform the following tasks:

• Enable Detective for a master account across Regions.

• Add member accounts to a master account's behavior graphs across Regions.

• Remove member accounts from a master account's behavior graphs across Regions.

• Disable Detective for a master account across Regions. When a master account disables Detective, themaster account's behavior graph in each Region is disabled.

Overview of the enableDetective.py scriptThe enableDetective.py script does the following:

1. Enables Detective in for a master account in each specified Region, if the master account does notalready have Detective enabled in that Region.

2. Sends invitations from the master account to the specified member accounts for each behavior graph.

The invitation email messages use the default message content and cannot be customized.

3. Automatically accepts the invitations for the member accounts.

Because the script automatically accepts the invitations, member accounts can ignore these messages.

We recommend reaching out directly to the member accounts to notify them that the invitations areaccepted automatically.

Overview of the disableDetective.py scriptThe disableDetective.py script deletes the specified member accounts from the master account'sbehavior graphs across the specified Regions.

It also provides an option to disable Detective for the master account across the specified Regions.

Required permissions for the scriptsThe scripts require a preexisting AWS role in the master account and in all of the member accounts thatyou add or remove.

49

https://github.com/aws-samples/amazon-detective-multiaccount-scripts


Amazon Detective Administration GuideSetting up the execution

environment for the Python scripts

The role name must be the same in all of the accounts.

The role trust relationship must allow your instance or local credentials to assume the role.

The AmazonDetectiveFullAccess managed policy shown below contains the permissions that arerequired for the script to succeed.

Role policy

{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "detective:CreateMembers", "detective:DeleteMembers", "detective:AcceptInvitation" ], "Resource": "*" } ]}

Role trust relationship

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::<ACCOUNTID>:user/<USERNAME>" }, "Action": "sts:AssumeRole" } ]}

If you do not have a common role that includes at least the above permissions, you must create a rolewith at least those permissions in each member account and in the master account.

When you create the role, make sure that you do the following:

• Use the same role name in every account.

• Select the AmazonDetectiveFullAccess managed policy.

To automate this process, you can use the EnableDetective.yaml AWS CloudFormation template.Because the template creates only global resources, it can be run in any Region.

Setting up the execution environment for thePython scripts

You can run the scripts from either an EC2 instance or from a local machine.

50

Amazon Detective Administration GuideLaunching and configuring an EC2 instance

Launching and configuring an EC2 instanceOne option for running the scripts is to run them from an EC2 instance.

To launch and configure an EC2 instance

1. Launch an EC2 instance in your master account. For details on how to launch an EC2 instance, seeGetting Started with Amazon EC2 Linux Instances in the Amazon EC2 User Guide for Linux Instances.

2. Attach to the instance an IAM role that has permissions to allow the instance to call AssumeRolewithin the master account.

If you used the EnableDetective.yaml AWS CloudFormation template, then an instance role witha profile named EnableDetective was created.

Otherwise, for information on creating an instance role, see the blog post Easily Replace or Attachan IAM Role to an Existing EC2 Instance by Using the EC2 Console.

3. Install the required software:

• APT: sudo apt-get -y install python3-pip python3 git• RPM: sudo yum -y install python3-pip python3 git• Boto (minimum version 1.15): sudo pip install boto3

4. Clone the repository to the EC2 instance.

git clone https://github.com/aws-samples/amazon-detective-multiaccount-scripts.git

Configuring a local machine to run the scriptsYou can also run the scripts from your local machine.

To configure a local machine to run the scripts

1. Make sure that you have set up on your local machine credentials for your master account that havepermission to call AssumeRole.

2. Install the required software:

• Python 3

• Boto (minimum version 1.15)

• GitHub scripts

Platform Setup Instructions

Windows 1. Install Python 3 (https://www.python.org/downloads/windows/).

2. Open a command prompt.3. To install Boto, run: pip install boto34. Download the script source code from GitHub (https://

github.com/aws-samples/amazon-detective-multiaccount-scripts).

Mac 1. Install Python 3 (https://www.python.org/downloads/mac-osx/).

51

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html

http://aws.amazon.com/blogs/security/easily-replace-or-attach-an-iam-role-to-an-existing-ec2-instance-by-using-the-ec2-console/

http://aws.amazon.com/blogs/security/easily-replace-or-attach-an-iam-role-to-an-existing-ec2-instance-by-using-the-ec2-console/

https://www.python.org/downloads/windows/

https://www.python.org/downloads/windows/




https://www.python.org/downloads/mac-osx/

https://www.python.org/downloads/mac-osx/

Amazon Detective Administration GuideCreating a .csv list of member accounts to add or remove

Platform Setup Instructions

2. Open a command prompt.3. To install Boto, run: pip install boto34. Download the script source code from GitHub (https://

github.com/aws-samples/amazon-detective-multiaccount-scripts).

Linux 1. To install Python 3, run one of the following:• sudo apt-get -y install install python3-pippython3 git

• sudo yum install git python

2. To install Boto, run: sudo pip install boto33. Clone the script source code from https://github.com/aws-

samples/amazon-detective-multiaccount-scripts.

Creating a .csv list of member accounts to add orremove

To identify the member accounts to add to or remove from the behavior graphs, you provide a .csv filethat contains the list of accounts.

List each account on a separate line. Each member account entry contains the AWS account ID and theaccount's root user email address.

See the following example:

111122223333,[email protected],[email protected]

Running enableDetective.pyYou can run the enableDetective.py script from an EC2 instance or your local machine.

To run enableDetective.py

1. Copy the .csv file to the amazon-detective-multiaccount-scripts directory on your EC2instance or local machine.

2. Change to the amazon-detective-multiaccount-scripts directory.3. Run the enableDetective.py script.

enableDetective.py --master_account masterAccountID --assume_role roleName inputFileName --enabled_regions regionList

When you run the script, replace the following values:

masterAccountID

The AWS account ID for the master account.

52






Amazon Detective Administration GuideRunning disableDetective.py

roleName

The name of the AWS role to assume in the master account and each member account.inputFileName

The name of the .csv file containing the list of member accounts to add to the master account'sbehavior graphs.

regionList

(Optional) A comma-separated list of Regions in which to add the member accounts to the masteraccount's behavior graph. For example:

--enabled_regions us-east-1,us-east-2,us-west-2

The master account might not already have Detective enabled in a Region. In that case, the scriptenables Detective and creates a new behavior graph for the master account.

If you do not provide a list of Regions, then the script acts across all Regions that Detective supports.

Running disableDetective.pyYou can run the disableDetective.py script from an EC2 instance or your local machine.

To run disableDetective.py

1. Copy the .csv file to the amazon-detective-multiaccount-scripts directory.2. To use the .csv file to delete the listed member accounts from the master account's behavior

graphs across a specified list of Regions, run the disableDetective.py script as follows:

disabledetective.py --master_account masterAccountID --assume_role roleName inputFileName --disabled_regions regionList

3. To disable Detective for the master account across all Regions, run the disableDetective.pyscript with the --delete-master flag.

disabledetective.py --master_account masterAccountID --assume_role roleName inputFileName --disabled_regions regionList --delete_master

When you run the script, replace the following values:

masterAccountID

The AWS account ID for the master account.roleName

The name of the AWS role to assume in the master account and each member account.inputFileName

The name of the .csv file containing the list of member accounts to remove from the masteraccount's behavior graphs.

You must provide a .csv file even if you are disabling Detective.regionList

(Optional) A comma-separated list of Regions in which to do one of the following:

53

Amazon Detective Administration GuideRunning disableDetective.py

• Remove the member accounts from the master account's behavior graphs.• If the --delete-master flag is included, disable Detective.

For example:

--disabled_regions us-east-1,us-east-2,us-west-2

If you do not provide a list of Regions, then the script acts across all Regions that Detective supports.

54


Document history for DetectiveAdministration Guide

The following table provides a history of the updates to this guide.

• API version: latest• Latest documentation update: January 21, 2020

History of updates for Detective Administration Guide

Change Description Date

New open source Python scriptson GitHub (p. 49)

The new amazon-detective-multiaccount-scripts repositoryon GitHub provides open sourcePython scripts you can use tomanage behavior graphs acrossRegions.

You can enable Detective for amaster account, add memberaccounts to behavior graphs,remove member accounts frombehavior graphs, and disableDetective for a master account.

January 21, 2020

Introducing Amazon Detective(preview)

Detective uses machine learningand purpose-built visualizationsto help you analyze andinvestigate security issues acrossyour Amazon Web Services(AWS) workloads.

Detective is currently in preview.

December 3, 2019

55



Date post:	22-May-2020
Category:	Documents
Upload:	others
View:	1 times
Download:	0 times

Amazon Detective - Administration Guide · Security Hub allows you to pivot from a GuardDuty...

Documents