This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.
GuardDuty examples using Amazon CLI
The following code examples show you how to perform actions and implement common scenarios by using the Amazon Command Line Interface with GuardDuty.
Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.
Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.
Topics
Actions
The following code example shows how to use accept-invitation
.
- Amazon CLI
-
To accept an invitation to become a GuardDuty member account in the current region
The following
accept-invitation
example shows how to accept an invitation to become a GuardDuty member account in the current region.aws guardduty accept-invitation \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --master-id123456789111
\ --invitation-idd6b94fb03a66ff665f7db8764example
This command produces no output.
For more information, see Managing GuardDuty Accounts by Invitation
in the GuardDuty User Guide. -
For API details, see AcceptInvitation
in Amazon CLI Command Reference.
-
The following code example shows how to use archive-findings
.
- Amazon CLI
-
To archive findings in the current region
This example shows how to archive findings in the current region.
aws guardduty archive-findings \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --finding-idsd6b94fb03a66ff665f7db8764example
3eb970e0de00c16ec14e6910fexample
This command produces no output.
For more information, see Managing GuardDuty Accounts by Invitation
in the GuardDuty User Guide. -
For API details, see ArchiveFindings
in Amazon CLI Command Reference.
-
The following code example shows how to use create-detector
.
- Amazon CLI
-
To enable GuardDuty in the current region
This example shows how to create a new detector, which enables GuardDuty, in the current region.:
aws guardduty create-detector \ --enable
Output:
{ "DetectorId": "b6b992d6d2f48e64bc59180bfexample" }
For more information, see Enable Amazon GuardDuty
in the GuardDuty User Guide. -
For API details, see CreateDetector
in Amazon CLI Command Reference.
-
The following code example shows how to use create-filter
.
- Amazon CLI
-
To create a new filter for the current region
This example creates a filter that matches all portscan findings for instance created from a specific image.:
aws guardduty create-filter \ --detector-id
b6b992d6d2f48e64bc59180bfexample
\ --actionARCHIVE
\ --namemyFilter
\ --finding-criteria '{"Criterion": {"type": {"Eq": ["Recon:EC2/Portscan"]},"resource.instanceDetails.imageId": {"Eq": ["ami-0a7a207083example"]}}}
'Output:
{ "Name": "myFilter" }
For more information, see Filtering findings
in the GuardDuty User Guide. -
For API details, see CreateFilter
in Amazon CLI Command Reference.
-
The following code example shows how to use create-ip-set
.
- Amazon CLI
-
To create a trusted IP set
The following
create-ip-set
example creates and activates a trusted IP set in the current region.aws guardduty create-ip-set \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --namenew-ip-set
\ --formatTXT
--locations3://AWSDOC-EXAMPLE-BUCKET/customtrustlist.csv
--activateOutput:
{ "IpSetId": "d4b94fc952d6912b8f3060768example" }
For more information, see Working with Trusted IP Lists and Threat Lists
in the GuardDuty User Guide. -
For API details, see CreateIpSet
in Amazon CLI Command Reference.
-
The following code example shows how to use create-members
.
- Amazon CLI
-
To associate a new member with your GuardDuty master account in the current region.
This example shows how to associate member accounts to be managed by the current account as the GuardDuty master.
aws guardduty create-members --detector-id
b6b992d6d2f48e64bc59180bfexample
\ --account-detailsAccountId=111122223333,Email=first+member@example.com
AccountId=111111111111
,Email=another+member@example.com
Output:
{ "UnprocessedAccounts": [] }
For more information, see Managing multiple accounts
in the GuardDuty User Guide. -
For API details, see CreateMembers
in Amazon CLI Command Reference.
-
The following code example shows how to use create-publishing-destination
.
- Amazon CLI
-
To create a publishing destination to export GuardDuty findings in the current region to.
This example shows how to create a publishing destination for GuardDuty findings.
aws guardduty create-publishing-destination \ --detector-id
b6b992d6d2f48e64bc59180bfexample
\ --destination-typeS3
\ --destination-propertiesDestinationArn=arn:aws:s3:::yourbucket,KmsKeyArn=arn:aws:kms:us-west-1:111122223333:key/84cee9c5-dea1-401a-ab6d-e1de7example
Output:
{ "DestinationId": "46b99823849e1bbc242dfbe3cexample" }
For more information, see Exporting findings
in the GuardDuty User Guide. -
For API details, see CreatePublishingDestination
in Amazon CLI Command Reference.
-
The following code example shows how to use create-sample-findings
.
- Amazon CLI
-
To create sample GuardDuty findings in the current region.
This example shows how to create a sample finding of the provided types.
aws guardduty create-sample-findings \ --detector-id
b6b992d6d2f48e64bc59180bfexample
\ --finding-typesUnauthorizedAccess:EC2/TorClient
UnauthorizedAccess:EC2/TorRelay
This command produces no output.
For more information, see Sample findings
in the GuardDuty User Guide. -
For API details, see CreateSampleFindings
in Amazon CLI Command Reference.
-
The following code example shows how to use create-threat-intel-set
.
- Amazon CLI
-
To create a new threat intel set in the current region.
This example shows how to upload a threat intel set to GuardDuty and activate it immediately.
aws guardduty create-threat-intel-set \ --detector-id
b6b992d6d2f48e64bc59180bfexample
\ --namemyThreatSet
\ --formatTXT
\ --locations3://EXAMPLEBUCKET/threatlist.csv
\ --activateOutput:
{ "ThreatIntelSetId": "20b9a4691aeb33506b808878cexample" }
For more information, see Trusted IP and threat lists
in the GuardDuty User Guide. -
For API details, see CreateThreatIntelSet
in Amazon CLI Command Reference.
-
The following code example shows how to use decline-invitations
.
- Amazon CLI
-
To decline an invitation to have Guardduty managed by another account in the current region.
This example shows how to decline a membership invitation.
aws guardduty decline-invitations \ --account-ids
111122223333
Output:
{ "UnprocessedAccounts": [] }
For more information, see Managing GuardDuty accounts by invitation
in the GuardDuty User Guide. -
For API details, see DeclineInvitations
in Amazon CLI Command Reference.
-
The following code example shows how to use delete-detector
.
- Amazon CLI
-
To delete a detector, and disable GuardDuty, in the current region.
This example shows how to delete a detector, if successful, this will disable GuardDuty in the region associated with that detector.
aws guardduty delete-detector \ --detector-id
b6b992d6d2f48e64bc59180bfexample
This command produces no output.
For more information, see Suspending or disabling GuardDuty
in the GuardDuty User Guide. -
For API details, see DeleteDetector
in Amazon CLI Command Reference.
-
The following code example shows how to use delete-filter
.
- Amazon CLI
-
To delete an existing filter in the current region
This example shows how to create delete a filter.
aws guardduty delete-filter \ --detector-id
b6b992d6d2f48e64bc59180bfexample
\ --filter-namebyebyeFilter
This command produces no output.
For more information, see Filtering findings
in the GuardDuty User Guide. -
For API details, see DeleteFilter
in Amazon CLI Command Reference.
-
The following code example shows how to use disable-organization-admin-account
.
- Amazon CLI
-
To remove an account as the delegated administrator for GuardDuty within your organization
This example shows how to remove an account as the delegated administrator for GuardDuty.
aws guardduty disable-organization-admin-account \ --admin-account-id
111122223333
This command produces no output.
For more information, see Managing accounts with Amazon organizations
in the GuardDuty User Guide. -
For API details, see DisableOrganizationAdminAccount
in Amazon CLI Command Reference.
-
The following code example shows how to use disassociate-from-master-account
.
- Amazon CLI
-
To disassociate from your current master account in the current region
The following
disassociate-from-master-account
example dissassociates your account from the current GuardDuty master account in the current Amazon region.aws guardduty disassociate-from-master-account \ --detector-id
d4b040365221be2b54a6264dcexample
This command produces no output.
For more information, see Understanding the Relationship between GuardDuty Master and Member Accounts
in the GuardDuty User Guide. -
For API details, see DisassociateFromMasterAccount
in Amazon CLI Command Reference.
-
The following code example shows how to use get-detector
.
- Amazon CLI
-
To retrieve details of a specific detector
The following
get-detector
example displays the configurations details of the specified detector.aws guardduty get-detector \ --detector-id
12abc34d567e8fa901bc2d34eexample
Output:
{ "Status": "ENABLED", "ServiceRole": "arn:aws:iam::111122223333:role/aws-service-role/guardduty.amazonaws.com/AWSServiceRoleForAmazonGuardDuty", "Tags": {}, "FindingPublishingFrequency": "SIX_HOURS", "UpdatedAt": "2018-11-07T03:24:22.938Z", "CreatedAt": "2017-12-22T22:51:31.940Z" }
For more information, see Concepts and Terminology
in the GuardDuty User Guide. -
For API details, see GetDetector
in Amazon CLI Command Reference.
-
The following code example shows how to use get-findings
.
- Amazon CLI
-
Example 1: To retrieve the details of a specific finding
The following
get-findings
example retrieves the full JSON finding details of the specified finding.aws guardduty get-findings \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --finding-id1ab92989eaf0e742df4a014d5example
Output:
{ "Findings": [ { "Resource": { "ResourceType": "AccessKey", "AccessKeyDetails": { "UserName": "testuser", "UserType": "IAMUser", "PrincipalId": "AIDACKCEVSQ6C2EXAMPLE", "AccessKeyId": "ASIASZ4SI7REEEXAMPLE" } }, "Description": "APIs commonly used to discover the users, groups, policies and permissions in an account, was invoked by IAM principal testuser under unusual circumstances. Such activity is not typically seen from this principal.", "Service": { "Count": 5, "Archived": false, "ServiceName": "guardduty", "EventFirstSeen": "2020-05-26T22:02:24Z", "ResourceRole": "TARGET", "EventLastSeen": "2020-05-26T22:33:55Z", "DetectorId": "d4b040365221be2b54a6264dcexample", "Action": { "ActionType": "AWS_API_CALL", "AwsApiCallAction": { "RemoteIpDetails": { "GeoLocation": { "Lat": 51.5164, "Lon": -0.093 }, "City": { "CityName": "London" }, "IpAddressV4": "52.94.36.7", "Organization": { "Org": "Amazon.com", "Isp": "Amazon.com", "Asn": "16509", "AsnOrg": "AMAZON-02" }, "Country": { "CountryName": "United Kingdom" } }, "Api": "ListPolicyVersions", "ServiceName": "iam.amazonaws.com", "CallerType": "Remote IP" } } }, "Title": "Unusual user permission reconnaissance activity by testuser.", "Type": "Recon:IAMUser/UserPermissions", "Region": "us-east-1", "Partition": "aws", "Arn": "arn:aws:guardduty:us-east-1:111122223333:detector/d4b040365221be2b54a6264dcexample/finding/1ab92989eaf0e742df4a014d5example", "UpdatedAt": "2020-05-26T22:55:21.703Z", "SchemaVersion": "2.0", "Severity": 5, "Id": "1ab92989eaf0e742df4a014d5example", "CreatedAt": "2020-05-26T22:21:48.385Z", "AccountId": "111122223333" } ] }
For more information, see Findings
in the GuardDuty User Guide. -
For API details, see GetFindings
in Amazon CLI Command Reference.
-
The following code example shows how to use get-ip-set
.
- Amazon CLI
-
To list get details on a specified trusted IP set
The following
get-ip-set
example shows the status and details of the specififed trusted IP set.aws guardduty get-ip-set \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --ip-set-idd4b94fc952d6912b8f3060768example
Output:
{ "Status": "ACTIVE", "Location": "s3://AWSDOC-EXAMPLE-BUCKET.s3-us-west-2.amazonaws.com/customlist.csv", "Tags": {}, "Format": "TXT", "Name": "test-ip-set" }
For more information, see Working with Trusted IP Lists and Threat Lists
in the GuardDuty User Guide. -
For API details, see GetIpSet
in Amazon CLI Command Reference.
-
The following code example shows how to use get-master-account
.
- Amazon CLI
-
To retrieve details about your master account in the current region
The following
get-master-account
example displays the status and details of the master account associated with your detector in the current region.aws guardduty get-master-account \ --detector-id
12abc34d567e8fa901bc2d34eexample
Output:
{ "Master": { "InvitationId": "04b94d9704854a73f94e061e8example", "InvitedAt": "2020-06-09T22:23:04.970Z", "RelationshipStatus": "Enabled", "AccountId": "123456789111" } }
For more information, see Understanding the Relationship between GuardDuty Master and Member Accounts
in the GuardDuty User Guide. -
For API details, see GetMasterAccount
in Amazon CLI Command Reference.
-
The following code example shows how to use list-detectors
.
- Amazon CLI
-
To list the available detectors in the current region
The following
list-detectors
example lists the available detectors in your current Amazon region.aws guardduty list-detectors
Output:
{ "DetectorIds": [ "12abc34d567e8fa901bc2d34eexample" ] }
For more information, see Concepts and Terminology
in the GuardDuty User Guide. -
For API details, see ListDetectors
in Amazon CLI Command Reference.
-
The following code example shows how to use list-findings
.
- Amazon CLI
-
Example 1: To list all findings for the current region
The following
list-findings
example displays a list of all findingIds for the current region sorted by severity from highest to lowest.aws guardduty list-findings \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --sort-criteria '{"AttributeName": "severity","OrderBy":"DESC"}
'Output:
{ "FindingIds": [ "04b8ab50fd29c64fc771b232dexample", "5ab8ab50fd21373735c826d3aexample", "90b93de7aba69107f05bbe60bexample", ... ] }
For more information, see Findings
in the GuardDuty User Guide. Example 2: To list findings for the current region matching a specific finding criteria
The following
list-findings
example displays a list of all findingIds that match a specified finding type.aws guardduty list-findings \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --finding-criteria '{"Criterion":{"type": {"Eq":["UnauthorizedAccess:EC2/SSHBruteForce"]}}}
'Output:
{ "FindingIds": [ "90b93de7aba69107f05bbe60bexample", "6eb9430d7023d30774d6f05e3example", "2eb91a2d060ac9a21963a5848example", "44b8ab50fd2b0039a9e48f570example", "9eb8ab4cd2b7e5b66ba4f5e96example", "e0b8ab3a38e9b0312cc390ceeexample" ] }
For more information, see Findings
in the GuardDuty User Guide. Example 3: To list findings for the current region matching a specific set of finding criteria defined within a JSON file
The following
list-findings
example displays a list of all findingIds that are not archived, and involve the IAM user named "testuser", as specified in a JSON file.aws guardduty list-findings \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --finding-criteriafile://myfile.json
Contents of
myfile.json
:{"Criterion": { "resource.accessKeyDetails.userName":{ "Eq":[ "testuser" ] }, "service.archived": { "Eq": [ "false" ] } } }
Output:
{ "FindingIds": [ "1ab92989eaf0e742df4a014d5example" ] }
For more information, see Findings
in the GuardDuty User Guide. -
For API details, see ListFindings
in Amazon CLI Command Reference.
-
The following code example shows how to use list-invitations
.
- Amazon CLI
-
To list details on your invitations to become a member account in the current region
The following
list-invitations
example lists details and statuses on your invitations to become a GuardDuty member account in the current region.aws guardduty list-invitations
Output:
{ "Invitations": [ { "InvitationId": "d6b94fb03a66ff665f7db8764example", "InvitedAt": "2020-06-10T17:56:38.221Z", "RelationshipStatus": "Invited", "AccountId": "123456789111" } ] }
For more information, see Managing GuardDuty Accounts by Invitation
in the GuardDuty User Guide. -
For API details, see ListInvitations
in Amazon CLI Command Reference.
-
The following code example shows how to use list-ip-sets
.
- Amazon CLI
-
To list trusted IP sets in the current region
The following
list-ip-sets
example lists the trusted IP sets in your current Amazon region.aws guardduty list-ip-sets \ --detector-id
12abc34d567e8fa901bc2d34eexample
Output:
{ "IpSetIds": [ "d4b94fc952d6912b8f3060768example" ] }
For more information, see Working with Trusted IP Lists and Threat Lists
in the GuardDuty User Guide. -
For API details, see ListIpSets
in Amazon CLI Command Reference.
-
The following code example shows how to use list-members
.
- Amazon CLI
-
To list all members in the current region
The following
list-members
example lists all member accounts and their details for the current region.aws guardduty list-members \ --detector-id
12abc34d567e8fa901bc2d34eexample
Output:
{ "Members": [ { "RelationshipStatus": "Enabled", "InvitedAt": "2020-06-09T22:49:00.910Z", "MasterId": "123456789111", "DetectorId": "7ab8b2f61b256c87f793f6a86example", "UpdatedAt": "2020-06-09T23:08:22.512Z", "Email": "your+member@example.com", "AccountId": "123456789222" } ] }
For more information, see Understanding the Relationship between GuardDuty Master and Member Accounts
in the GuardDuty User Guide. -
For API details, see ListMembers
in Amazon CLI Command Reference.
-
The following code example shows how to use update-ip-set
.
- Amazon CLI
-
To update a trusted IP set
The following
update-ip-set
example shows how to update the details of a trusted IP set.aws guardduty update-ip-set \ --detector-id
12abc34d567e8fa901bc2d34eexample
\ --ip-set-idd4b94fc952d6912b8f3060768example
\ --locationhttps://AWSDOC-EXAMPLE-BUCKET.s3-us-west-2.amazonaws.com/customtrustlist2.csv
This command produces no output.
For more information, see Working with Trusted IP Lists and Threat Lists
in the GuardDuty User Guide. -
For API details, see UpdateIpSet
in Amazon CLI Command Reference.
-