Managing GuardDuty accounts by invitation - Amazon GuardDuty

Managing GuardDuty accounts by invitation

To manage accounts outside of your organization, you can use the legacy invitation method. When you use this method, your account is designated as a administrator account when another account accepts your invitation to become a member account.

If your account is not an administrator account, you can accept an invitation from another account. When you accept, your account becomes a member account. An AWS account cannot be a GuardDuty administrator account and member account at the same time.

When you accept an invitation from one account, you can't accept an invitation from another account. To accept an invitation from another account, you will first need to disassociate your account from the existing administrator account. Alternatively, the administrator account can also disassociate and remove your account from their organization.

Accounts associated by invitation have the same overall administrator account-to-member relationship as accounts associated by AWS Organizations, as described in Understanding the relationship between GuardDuty administrator account and member accounts. However, invitation administrator account users cannot enable GuardDuty on behalf of associated member accounts or view other non-member accounts within their AWS Organizations organization.

Important

Cross-regional data transfer may occur when GuardDuty creates member accounts using this method. In order to verify member accounts' email addresses, GuardDuty uses an email verification service that operates only in the US East (N. Virginia) Region.

Adding and managing accounts by invitations

Choose one of the access methods to add and invite accounts to become GuardDuty member accounts as a GuardDuty administrator account.

Console
Step 1 - Add an account
  1. Open the GuardDuty console at https://console.aws.amazon.com/guardduty/.

  2. In the navigation pane, choose Accounts.

  3. Choose Add accounts by invitation in the top pane.

  4. On the Add member accounts page, under Enter account details, enter the AWS account ID and email address associated with the account that you want to add.

  5. To add another row to enter account details one at a time, choose Add another account. You can also choose Upload .csv file with account details to add accounts in bulk.

    Important

    The first line of your csv file must contain the header, as depicted in the following example – Account ID,Email. Each subsequent line must contain a single valid AWS account ID and its associated email address. The format of a row is valid if it contains only one AWS account ID and the associated email address separated by a comma.

    Account ID,Email 555555555555,user@example.com
  6. After you have added all the accounts' details, choose Next. You can view the newly-added accounts in the Accounts table. The Status of these accounts will be Invite not sent. For information about sending an invite to one or more added accounts, see Step 2 - Invite an account.

Step 2 - Invite an account
  1. Open the GuardDuty console at https://console.aws.amazon.com/guardduty/.

  2. In the navigation pane, choose Accounts.

  3. Select one or more accounts that you want to invite to Amazon GuardDuty.

  4. Choose Actions dropdown menu and then choose Invite.

  5. In the Invitation to GuardDuty dialog box, enter an (optional) invitation message.

    If the invited account does not have access to email, select the checkbox Also send an email notification to the root user on the invitee's AWS account and generate an alert in the invitee's AWS Health Dashboard.

  6. Choose Send invitation. If the invitees have access to the specified email address they can view the invite by opening the GuardDuty console at https://console.aws.amazon.com/guardduty/.

  7. When an invitee accepts the invite, the value in the Status column changes to Invited. For information about accepting an invite, see Step 3 - Accept an invitation.

Step 3 - Accept an invitation
  1. Open the GuardDuty console at https://console.aws.amazon.com/guardduty/.

    Important

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

  2. Do the following only if you haven't enabled GuardDuty yet; otherwise, you can skip this step and continue with the next step.

    If you haven't yet enabled GuardDuty, choose Get Started on the Amazon GuardDuty page.

    On the Welcome to GuardDuty page, choose Enable GuardDuty.

  3. After you enable GuardDuty for your account, use the following steps to accept the membership invitation:

    1. In the navigation pane, choose Settings.

    2. Choose Accounts.

    3. On the Accounts, ensure to verify the owner of the account from which you accept the invitation. Turn on Accept to accept the membership invite.

  4. After you accept the invite, your account becomes a GuardDuty member account. The account whose owner sent the invitation becomes the GuardDuty administrator account. The administrator account will know that you have accepted the invitation. The Accounts table in their GuardDuty account will get updated. The value in the Status column corresponding to your member account ID will change to Monitored. The administrator account owner can now view and manage GuardDuty and protection plan configurations on behalf of your account. The administrator account can also view and manage GuardDuty findings generated for your member account.

API/CLI

You can designate a GuardDuty administrator account, and create or add GuardDuty member accounts by invitation through the API operations. Run the following GuardDuty API operations in order to designate administrator account and member accounts in GuardDuty.

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

Creating or adding member accounts
  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 administrator account GuardDuty account.

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

    You can also use AWS Command Line Tools to designate a administrator account by running the following CLI command. Make sure to use your own valid detector ID, account ID, and email.

    To find the detectorId for your account and current Region, see Settings page in the https://console.aws.amazon.com/guardduty/ console.

    aws guardduty create-members --detector-id 12abc34d567e8fa901bc2d34e56789f0 --account-details AccountId=111122223333,Email=guardduty-member@organization.com
  2. Run InviteMembers by using the credentials of the AWS account that has GuardDuty enabled. This is the account that you want to be the administrator account GuardDuty account.

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

    Note

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

    You can also use AWS Command Line Interface to designate member accounts by running the following command. Make sure to use your own valid detector ID and valid account IDs for the accounts you want to invite.

    To find the detectorId for your account and current Region, see Settings page in the https://console.aws.amazon.com/guardduty/ console.

    aws guardduty invite-members --detector-id 12abc34d567e8fa901bc2d34e56789f0 --account-ids 111122223333
Accepting invitations

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

  1. Run the CreateDetector API operation for each AWS account that was invited to become a GuardDuty member account and that 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 using the following CLI command.

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

    You must specify the detector ID of this AWS account for the member account, the account ID of the administrator account that sent the invitation, and the invitation ID of the invitation that you are accepting. You can find the account ID of the administrator account in the invitation email or by using the ListInvitations operation of the API.

    You can also accept an invitation using AWS Command Line Tools by running the following CLI command. Make sure to use a valid detector ID, administrator account ID, and an invitation ID.

    To find the detectorId for your account and current Region, see Settings page in the https://console.aws.amazon.com/guardduty/ console.

    aws guardduty accept-invitation --detector-id 12abc34d567e8fa901bc2d34e56789f0 --administrator-id 444455556666 --invitation-id 84b097800250d17d1872b34c4daadcf5

Consolidating GuardDuty administrator accounts under a single organization delegated GuardDuty administrator account

GuardDuty recommends using association through AWS Organizations to manage member accounts under a delegated GuardDuty administrator account. You can use the example process outlined below to consolidate administrator account and member associated by invitation in an organization under a single GuardDuty delegated GuardDuty administrator account.

Note

Accounts that are already being managed by a delegated GuardDuty administrator account, or active member accounts that are associated with delegated GuardDuty administrator account can't be added to a different delegated GuardDuty administrator account. Each organization can have only one delegated GuardDuty administrator account per Region, and each member account can have only one delegated GuardDuty administrator account.

Choose one of the access methods to consolidate GuardDuty administrator accounts under a single delegated GuardDuty administrator account.

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

    To log in, use the credentials of the management account of the organization.

  2. All the accounts for which you want to manage GuardDuty must be a part of your organization. For information about adding an account to your organization, see Inviting an AWS account to join your organization.

  3. Make sure all the member accounts are associated with the account that you want to designate as the single delegated GuardDuty administrator account. Disassociate any member account that is still associated with the pre-existing administrator accounts.

    The following steps will help you disassociate member accounts from the pre-existing administrator account:

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

    2. To log in, use the credentials of the pre-existing administrator account.

    3. In the navigation pane, choose Accounts.

    4. On the Accounts page, select one or more accounts that you want to disassociate from the administrator account.

    5. Choose Actions and then choose Disassociate account.

    6. Choose Confirm to finalize the step.

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

    To log in, use the management account credentials.

  5. In the navigation pane, choose Settings. On the Settings page, designate the delegated GuardDuty administrator account for the organization.

  6. Log in to the designated delegated GuardDuty administrator account.

  7. Add members from the organization. For more information, see Managing GuardDuty accounts with AWS Organizations.

API/CLI
  1. All the accounts for which you want to manage GuardDuty must be a part of your organization. For information about adding an account to your organization, see Inviting an AWS account to join your organization.

  2. Make sure all the member accounts are associated with the account that you want to designate as the single delegated GuardDuty administrator account.

    1. Run DisassociateMembers to disassociate any member account that is still associated with the pre-existing administrator accounts.

    2. Alternatively, you can use AWS Command Line Interface to run the following command and replace 777777777777 with the detector ID of the pre-existing administrator account from which you want to disassociate the member account. Replace 666666666666 with the AWS account ID of the member account that you want to disassociate.

      aws guardduty disassociate-members --detector-id 777777777777 --account-ids 666666666666
  3. Run EnableOrganizationAdminAccount to delegate an AWS account as the delegated GuardDuty administrator account.

    Alternatively, you can use AWS Command Line Interface to run the following command to delegate a delegated GuardDuty administrator account:

    aws guardduty enable-organization-admin-account --admin-account-id 777777777777
  4. Add members from the organization. For more information, see Create or add member member accounts using API.

Important

To maximize the effectiveness of GuardDuty, a regional service, we recommend that you designate your delegated GuardDuty administrator account and add all your member accounts in every Region.

Enable GuardDuty in multiple accounts simultaneously

Use the following method to enable GuardDuty in multiple accounts at the same time.

Use Python scripts to enable GuardDuty in multiple accounts simultaneously

You can automate the enabling or disabling of GuardDuty on multiple accounts using the scripts from the sample repository at Amazon GuardDuty multiaccount scripts. Use the process in this section to enable GuardDuty for a list of member accounts using Amazon EC2. For information about using the disable script or setting up the script locally, see to the instructions in the shared link.

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

These scripts have a dependency on a shared IAM role with the managed policy – AWS managed policy: AmazonGuardDutyFullAccess. This policy provides entities access to GuardDuty and must be present on the administrator account and in each account for which you want to enable GuardDuty.

The following process enables GuardDuty in all available Regions by default. You can enable GuardDuty in specified Regions only by using the optional --enabled_regions argument and providing a comma-separated list of Regions. You can also optionally customize the invitation message that is sent to member accounts by opening the enableguardduty.py and editing the gd_invite_message string.

  1. Create an IAM role in the GuardDuty administrator account and attach the AWS managed policy: AmazonGuardDutyFullAccess policy to enable GuardDuty.

  2. Create an IAM role in each member account you want to be managed by your GuardDuty administrator account. This role must have the same name as the role created in step 1, it should allow the administrator account as a trusted entity, and it should have the same AmazonGuardDutyFullAccess managed policy described previously.

  3. Launch a new Amazon Linux instance with an attached role that has the following trust relationship that allows the instance to assume a service role.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
  4. Log in to the new instance and run the following commands to set it up.

    sudo yum install git python sudo yum install python-pip 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
  5. Create a CSV file containing a list of account IDs and emails of the member accounts that you added a role to in step 2. Accounts must appear one per line, and the account ID and email address must be separated by a comma, as in the following example.

    111122223333,guardduty-member@organization.com
    Note

    The CSV file must be in the same location as your enableguardduty.py script. You can copy an existing CSV file from Amazon S3 to your current directory with the following method.

    aws s3 cp s3://my-bucket/my_key_name example.csv
  6. Run the Python script. Make sure to supply your GuardDuty administrator account ID, the name of the role created in the first steps, and the name of your CSV file as arguments.

    python enableguardduty.py --master_account 444455556666 --assume_role roleName accountID.csv