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.
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 accountOpen the GuardDuty console at https://console.aws.amazon.com/guardduty/.
-
In the navigation pane, choose Accounts.
-
Choose Add accounts by invitation in the top
pane.
-
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.
-
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.
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
-
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 accountOpen the GuardDuty console at https://console.aws.amazon.com/guardduty/.
-
In the navigation pane, choose Accounts.
-
Select one or more accounts that you want to invite to Amazon GuardDuty.
-
Choose Actions dropdown menu and then choose
Invite.
-
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.
-
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/.
-
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 invitationOpen the GuardDuty console at https://console.aws.amazon.com/guardduty/.
You must enable GuardDuty before you can view or accept a membership
invitation.
-
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.
-
After you enable GuardDuty for your account, use the following steps to accept
the membership invitation:
-
In the navigation pane, choose
Settings.
-
Choose Accounts.
-
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.
-
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-
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
-
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.
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.
-
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
-
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.
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
-
Open the GuardDuty console at https://console.aws.amazon.com/guardduty/.
To log in, use the credentials of the management account of the organization.
-
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.
-
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:
Open the GuardDuty console at https://console.aws.amazon.com/guardduty/.
To log in, use the credentials of the pre-existing
administrator account.
In the navigation pane, choose
Accounts.
On the Accounts page, select one or more
accounts that you want to disassociate from the administrator account.
Choose Actions and then choose
Disassociate account.
Choose Confirm to finalize the step.
Open the GuardDuty console at https://console.aws.amazon.com/guardduty/.
To log in, use the management account credentials.
In the navigation pane, choose Settings. On the
Settings page, designate the delegated GuardDuty administrator account for the organization.
-
Log in to the designated delegated GuardDuty administrator account.
-
Add members from the organization. For more information, see
Managing GuardDuty accounts with AWS Organizations.
- API/CLI
-
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.
-
Make sure all the member accounts are associated with the account that you want to designate
as the single delegated GuardDuty administrator account.
Run DisassociateMembers to disassociate any member account
that is still associated with the pre-existing administrator accounts.
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
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
Add members from the organization. For more information, see
Create or add member member accounts using API.
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.
-
Create an IAM role in the GuardDuty administrator account and attach the AWS managed policy:
AmazonGuardDutyFullAccess
policy to enable GuardDuty.
-
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.
-
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"
}
]
}
-
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
-
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
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
-
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