GuardDuty examples using Amazon CLI - Amazon Command Line Interface
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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-id 123456789111 \ --invitation-id d6b94fb03a66ff665f7db8764example

This command produces no output.

For more information, see Managing GuardDuty Accounts by Invitation in the GuardDuty User Guide.

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-ids d6b94fb03a66ff665f7db8764example 3eb970e0de00c16ec14e6910fexample

This command produces no output.

For more information, see Managing GuardDuty Accounts by Invitation in the GuardDuty User Guide.

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 \ --action ARCHIVE \ --name myFilter \ --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 \ --name new-ip-set \ --format TXT --location s3://AWSDOC-EXAMPLE-BUCKET/customtrustlist.csv --activate

Output:

{ "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-details AccountId=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-type S3 \ --destination-properties DestinationArn=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.

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-types UnauthorizedAccess:EC2/TorClient UnauthorizedAccess:EC2/TorRelay

This command produces no output.

For more information, see Sample findings in the GuardDuty User Guide.

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 \ --name myThreatSet \ --format TXT \ --location s3://EXAMPLEBUCKET/threatlist.csv \ --activate

Output:

{ "ThreatIntelSetId": "20b9a4691aeb33506b808878cexample" }

For more information, see Trusted IP and threat lists in the GuardDuty User Guide.

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.

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-name byebyeFilter

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.

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.

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-id 1ab92989eaf0e742df4a014d5example

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-id d4b94fc952d6912b8f3060768example

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.

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-criteria file://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.

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-id d4b94fc952d6912b8f3060768example \ --location https://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.