Menu
Amazon GuardDuty
Amazon Guard Duty User Guide

Managing AWS Accounts in Amazon GuardDuty

You can invite other accounts to enable GuardDuty and become associated with your AWS account. If your invitations are accepted, your account is designated as the master GuardDuty account, and the associated accounts become your member accounts. You can then view and manage their GuardDuty findings on their behalf. In GuardDuty, a master account (per region) can have up to 1000 member accounts.

An AWS account cannot be a GuardDuty master and member account at the same time. An AWS account can accept only one GuardDuty membership invitation. Accepting a membership invitation is optional.

The sections below describe how you can create master and member accounts using the GuardDuty console, CLI, and APIs. You can also create master and member accounts through AWS CloudFormation. For more information, see AWS::GuardDuty::Master and AWS::GuardDuty::Member.

Note

Cross-regional data transfer can occur when GuardDuty member accounts are created. In order to verify member accounts' email addresses, GuardDuty uses a non-AWS account information verification service that operates only in the AWS US East (N. Virginia) region.

GuardDuty Master Accounts

Users from the master account can configure GuardDuty as well as view and manage GuardDuty findings for their own account and all of their member accounts.

The following is how users from a master account can configure GuardDuty:

  • Users from a master account can generate sample findings in their own account. Users from a master account CANNOT generate sample findings in members' accounts.

  • Users from a master account can archive findings in their own accounts and in all member accounts.

  • Users from a master account can upload and further manage trusted IP lists and threat lists in their own account.

    Important

    Trusted IP lists and threat lists that are uploaded by the master account and in the master account are imposed on GuardDuty functionality in its member accounts. In other words, in member accounts GuardDuty generates findings based on activity that involves known malicious IP addresses from the master's threat lists and does not generate findings based on activity that involves IP addresses from the master's trusted IP lists.

  • Users from a master account can suspend GuardDuty for its own (master) account. Users from a master account can also suspend GuardDuty in its member accounts.

    Note

    If a master account user suspends GuardDuty in the master account, this suspension is NOT automatically imposed on the member accounts. To suspend GuardDuty for member accounts, a user from a master account must select these member accounts and suspend GuardDuty through the console or specify their account IDs when running the StopMonitoringMembers API.

    A master account user can also re-enable GuardDuty in member accounts either through the console or by running the StartMonitoringMembers API.

  • Users from a master account can disable GuardDuty in its own (master) account. However, all member accounts must first be removed to disable GuardDuty in the master account. Users from a master account CANNOT disable GuardDuty for member accounts.

GuardDuty Member Accounts

Users from member accounts can configure GuardDuty as well as view and manage GuardDuty findings in their account. Member account users CANNOT configure GuardDuty or view or manage findings in the master or other member accounts.

The following is how users from a member account can configure GuardDuty:

  • Users from a member account can generate sample findings in their own member account. Users from a member account CANNOT generate sample findings in the master or other member accounts.

  • Users from a member account CANNOT archive findings either in their own account or in their master's account, or in other member accounts.

  • Users from a member account CANNOT upload and further manage trusted IP lists and threat lists.

    Trusted IP lists and threat lists that are uploaded by the master account are imposed on GuardDuty functionality in its member accounts. In other words, in member accounts GuardDuty generates findings based on activity that involves known malicious IP addresses from the master's threat lists and does not generate findings based on activity that involves IP addresses from the master's trusted IP lists.

    Note

    When a GuardDuty account becomes a GuardDuty member account, all of its trusted IP lists and threat lists (uploaded prior to becoming a GuardDuty member account) are disabled. If a GuardDuty member account disassociates from its GuardDuty master account, all of its trusted IP lists and threat lists (uploaded prior to becoming a GuardDuty member account) are re-enabled. Once no longer a GuardDuty member account, this account's users can upload and further manage trusted IP lists and threat lists in this account.

  • Users from a member account can suspend GuardDuty for their own account. Users from a member account CANNOT suspend GuardDuty for the master account or other member accounts.

  • Users from member accounts can disable GuardDuty for their own account. Users from a member account CANNOT disable GuardDuty for the master account or other member accounts.

Designating Master and Member Accounts Through GuardDuty Console

In GuardDuty, your account is designated a master account when you add another AWS account to be associated with your account or when another account accepts your invitation to become a member account.

If your account is a non-master account, you can accept an invitation from another account. When you accept, your account becomes a member account.

Use the following procedures to add an account, invite an account, or accept an invitation from another account.

  • Step 1 - Add an account

  • Step 2 - Invite an account

  • Step 3 - Accept an invitation

Step 1 - Add an account

  1. Open the GuardDuty console at https://console.aws.amazon.com/guardduty.

  2. In the navigation pane, under Settings, choose Accounts.

  3. Choose Add accounts.

  4. On the Add member accounts page, under Enter accounts, type the AWS account ID and email address of the account that you want to add. Then choose Add account.

    You can add more accounts, one at a time, by specifying their IDs and email addresses. You can also choose Upload list (.csv) to bulk add accounts. This can be useful if you want to invite some of these accounts to enable GuardDuty right away but want to delay for others.

    Important

    In your .csv list, accounts must appear one per line. For each account in your .csv list, you must specify the account ID and the email address separated by a comma. The first line of your .csv file must contain the following header, as shown in the example below: Account ID,Email. Each subsequent line must contain a valid account ID and a valid email address for the account that you want to add. The account ID and email address must be separated by a comma.

    Account ID,Email 111111111111,user@example.com
  5. When you are finished adding accounts, choose Done.

    The added accounts appear in a list on the Accounts page. Each added account in this list has an Invite link in the Status column.

Step 2 - Invite an account

  1. Open the GuardDuty console at https://console.aws.amazon.com/guardduty.

  2. In the navigation pane, under Settings, choose Accounts.

  3. For the account that you want to invite to enable GuardDuty, choose the Invite link that appears in the Status column of the added accounts list.

  4. In the Invitation to GuardDuty dialog box, type an invitation message (optional), and then choose Send notification.

    The value in the Status column for the invited account changes to Pending.

Step 3 - Accept an invitation

  1. Open the GuardDuty console at https://console.aws.amazon.com/guardduty.

  2. Do one of the following:

    • If you don't have GuardDuty enabled, on the Enable GuardDuty page, choose Enable GuardDuty. Then use the Accept widget and the Accept invitation button to accept the membership invitation.

      Important

      You must enable GuardDuty before you can accept a membership invitation.

    • If you already have GuardDuty enabled, use the Accept widget and the Accept invitation button to accept the membership invitation.

    After you accept the invitation, your account becomes a GuardDuty member account. The account whose user sent the invitation becomes the GuardDuty master account. The master account user can see that the value in the Status column for your member account changes to Monitored. The master account user can now view and manage GuardDuty findings for your member account.

Designating Master and Member Accounts Through the GuardDuty API Operations

You can also designate master and member GuardDuty accounts through the API operations. The following is the order in which these particular GuardDuty API operations must be run in order to designate master and member accounts in GuardDuty.

Complete the following procedure using the credentials of the AWS account that you want to designate as the GuardDuty master account.

  1. Run the CreateMembers API operation using the credentials of the AWS account that has GuardDuty enabled (this is the account that you want to be the master GuardDuty account).

    You must specify the detector ID of the current AWS account and the account details (account ID and email address) of the account(s) of the accounts that you want to become GuardDuty members (you can create one or more members with this API operation).

    You can also do this by using AWS Command Line Tools. You can run the following CLI command (make sure to use your own valid detector ID, account ID, and email:

    aws guardduty create-members --detector-id 12abc34d567e8fa901bc2d34e56789f0 --account-details AccountId=123456789012,Email=guarddutymember@amazon.com
  2. Run the InviteMembers API operation using the credentials of the AWS account that has GuardDuty enabled (this is the account that you want to be the master GuardDuty account.

    You must specify the detector ID of the current AWS account and the account IDs (you can invite one or more members with this API operation) of the accounts that you want to become GuardDuty members.

    Note

    You can also specify an optional invitation message using the message request parameter.

    You can also do this by using AWS Command Line Tools. You can run the following CLI command (make sure to use your own valid detector ID and account IDs:

    aws guardduty invite-members --detector-id 12abc34d567e8fa901bc2d34e56789f0 --account-ids 123456789012

Complete the following procedure using the credentials of each AWS account that you want to designate as the GuardDuty member account.

  1. Run the CreateDetector API operation for each AWS account that was invited to become a GuardDuty member account and where you want to accept an invitation.

    You must specify if the detector resource is to be enabled using the GuardDuty service. A detector must be created and enabled in order for GuardDuty to become operational. You must first enable GuardDuty before accepting an invitation.

    You can also do this by using AWS Command Line Tools. You can run the following CLI command:

    aws guardduty create-detector --enable
  2. Run the AcceptInvitation API operation for each AWS account where you want to accept the membership invitation using that account's credentials.

    You must specify the detector ID of this AWS account (member account), the master ID of the AWS account that sent the invitation that you are accepting (you can get this value either from the invitation email or by running the ListInvitations API operation. It is the value of the accountID response parameter), and the invitation ID of the invitation that you are accepting.

    You can also do this by using AWS Command Line Tools. You can run the following CLI command (make sure to use valide detector ID, master account ID, and invitation ID:

    aws guardduty accept-invitation --detector-id 12abc34d567e8fa901bc2d34e56789f0 --master-id 012345678901 --invitation-id 84b097800250d17d1872b34c4daadcf5

Enable GuardDuty in Multiple Accounts Simultaneously

To enable GuardDuty in multiple accounts at the same time, you can run enableguardduty.py and disableguardduty.py, which you can download from the following page: https://github.com/aws-samples/amazon-guardduty-multiaccount-scripts.

enableguardduty.py enables GuardDuty, sends invitations from the master account and accepts invitations in all member accounts. The result is a master GuardDuty account that contains all security findings for all member accounts. Since GuardDuty is regionally isolated, findings for each member account roll up to the corresponding region in the master account. For example, the us-east-1 region in your GuardDuty master account contains the security findings for all us-east-1 findings from all associated member accounts.

The scripts are modelled with the StackSets service in mind and are therefore dependent on having the IAM role called AWSCloudFormationStackSetExecutionRole in each account where you want to enable GuardDuty. This role provides StackSets with access to GuardDuty. If you already use StackSets, the scripts can leverage your existing roles. If not, you can use the instructions in https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-prereqs.html to setup the AWSCloudFormationStackSetExecutionRole in each account where you want to enable GuardDuty.

Launch a new Amazon Linux instance with a role that has administrative permissions. Login to this instance and run the following commands:

sudo yum install git python sudo pip install boto3 aws configure git clone https://github.com/aws-samples/amazon-guardduty-multiaccount-scripts.git cd amazon-guardduty-multiaccount-scripts sudo chmod +x disableguardduty.py enableguardduty.py

Note

When prompted, set the region to us-east-1 or whatever default region you want.

The scripts have one parameter - the account ID of your GuardDuty master account. Before you execute enableguardduty.py or disableguardduty.py, update either script’s global variables to map to your AWS accounts. You can create a list of the accounts and their associated email addresses. Specify the master GuardDuty account and (optionally) customize the invite message that is sent to member accounts.