Amazon GuardDuty

(1)

Amazon GuardDuty

API Reference

API Version 2017-11-28

(2)

Amazon GuardDuty: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

Amazon GuardDuty is a continuous security monitoring service that analyzes and processes the following data sources: VPC Flow Logs, AWS CloudTrail event logs, and DNS logs. It uses threat intelligence

feeds (such as lists of malicious IPs and domains) and machine learning to identify unexpected, potentially unauthorized, and malicious activity within your AWS environment. This can include issues like escalations of privileges, uses of exposed credentials, or communication with malicious IPs, URLs, or domains. For example, GuardDuty can detect compromised EC2 instances that serve malware or mine bitcoin.

GuardDuty also monitors AWS account access behavior for signs of compromise. Some examples of this are unauthorized infrastructure deployments such as EC2 instances deployed in a Region that has never been used, or unusual API calls like a password policy change to reduce password strength.

GuardDuty informs you of the status of your AWS environment by producing security ﬁndings that you can view in the GuardDuty console or through Amazon CloudWatch events. For more information, see the Amazon GuardDuty User Guide .

This document was last published on March 6, 2022.

API Version 2017-11-28 1

(17)

Actions

The following actions are supported:

• AcceptInvitation (p. 4)

• ArchiveFindings (p. 6)

• CreateDetector (p. 8)

• CreateFilter (p. 11)

• CreateIPSet (p. 16)

• CreateMembers (p. 19)

• CreatePublishingDestination (p. 22)

• CreateSampleFindings (p. 25)

• CreateThreatIntelSet (p. 27)

• DeclineInvitations (p. 30)

• DeleteDetector (p. 32)

• DeleteFilter (p. 34)

• DeleteInvitations (p. 36)

• DeleteIPSet (p. 38)

• DeleteMembers (p. 40)

• DeletePublishingDestination (p. 42)

• DeleteThreatIntelSet (p. 44)

• DescribeOrganizationConﬁguration (p. 46)

• DescribePublishingDestination (p. 48)

• DisableOrganizationAdminAccount (p. 51)

• DisassociateFromMasterAccount (p. 53)

• DisassociateMembers (p. 55)

• EnableOrganizationAdminAccount (p. 57)

• GetDetector (p. 59)

• GetFilter (p. 62)

• GetFindings (p. 65)

• GetFindingsStatistics (p. 72)

• GetInvitationsCount (p. 75)

• GetIPSet (p. 77)

• GetMasterAccount (p. 80)

• GetMemberDetectors (p. 82)

• GetMembers (p. 85)

• GetThreatIntelSet (p. 88)

• GetUsageStatistics (p. 91)

• InviteMembers (p. 95)

• ListDetectors (p. 98)

• ListFilters (p. 100)

• ListFindings (p. 102)

• ListInvitations (p. 106)

• ListIPSets (p. 108)

(18)

• ListMembers (p. 110)

• ListOrganizationAdminAccounts (p. 113)

• ListPublishingDestinations (p. 115)

• ListTagsForResource (p. 117)

• ListThreatIntelSets (p. 119)

• StartMonitoringMembers (p. 121)

• StopMonitoringMembers (p. 123)

• TagResource (p. 125)

• UnarchiveFindings (p. 127)

• UntagResource (p. 129)

• UpdateDetector (p. 131)

• UpdateFilter (p. 133)

• UpdateFindingsFeedback (p. 136)

• UpdateIPSet (p. 138)

• UpdateMemberDetectors (p. 140)

• UpdateOrganizationConﬁguration (p. 143)

• UpdatePublishingDestination (p. 145)

• UpdateThreatIntelSet (p. 147)

(19)

AcceptInvitation

Accepts the invitation to be monitored by a GuardDuty administrator account.

Request Syntax

POST /detector/detectorId/master HTTP/1.1 Content-type: application/json

{

"invitationId": "string", "masterId": "string"

}

URI Request Parameters

The request uses the following URI parameters.

detectorId (p. 4)

The unique ID of the detector of the GuardDuty member account.

Length Constraints: Minimum length of 1. Maximum length of 300.

Required: Yes

Request Body

The request accepts the following data in JSON format.

invitationId (p. 4)

The value that is used to validate the administrator account to the member account.

Type: String Required: Yes masterId (p. 4)

The account ID of the GuardDuty administrator account whose invitation you're accepting.

Type: String Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

(20)

Errors

For information about the errors that are common to all actions, see Common Errors (p. 257).

BadRequestException

A bad request exception object.

HTTP Status Code: 400 InternalServerErrorException

An internal server error exception object.

HTTP Status Code: 500

ArchiveFindings

Archives GuardDuty findings that are specified by the list of finding IDs.

NoteOnly the administrator account can archive ﬁndings. Member accounts don't have permission to archive ﬁndings from their accounts.

Request Syntax

POST /detector/detectorId/findings/archive HTTP/1.1 Content-type: application/json

{ "findingIds": [ "string" ] }

URI Request Parameters

The ID of the detector that speciﬁes the GuardDuty service whose ﬁndings you want to archive.

Required: Yes

Request Body

ﬁndingIds (p. 6)

The IDs of the ﬁndings that you want to archive.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

(22)

Errors

CreateDetector

Creates a single Amazon GuardDuty detector. A detector is a resource that represents the GuardDuty service. To start using GuardDuty, you must create a detector in each Region where you enable the service. You can have only one detector per account per Region. All data sources are enabled in a new detector by default.

Request Syntax

POST /detector HTTP/1.1

Content-type: application/json {

"clientToken": "string", "dataSources": { "kubernetes": { "auditLogs": { "enable": boolean }

},

"s3Logs": {

"enable": boolean }

},

"enable": boolean,

"findingPublishingFrequency": "string", "tags": {

"string" : "string"

}}

URI Request Parameters

The request does not use any URI parameters.

Request Body

clientToken (p. 8)

The idempotency token for the create request.

Type: String

Required: No dataSources (p. 8)

Describes which data sources will be enabled for the detector.

Type: DataSourceConﬁgurations (p. 171) object Required: No

enable (p. 8)

A Boolean value that speciﬁes whether the detector is to be enabled.

(24)

Response Syntax

Type: Boolean Required: Yes

ﬁndingPublishingFrequency (p. 8)

A value that speciﬁes how frequently updated ﬁndings are exported.

Type: String

Valid Values: FIFTEEN_MINUTES | ONE_HOUR | SIX_HOURS Required: No

tags (p. 8)

The tags to be added to a new detector resource.

Type: String to string map

Map Entries: Maximum number of 200 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^(?!aws:)[a-zA-Z+-=._:/]+$

Value Length Constraints: Maximum length of 256.

Required: No

Response Syntax

HTTP/1.1 200

"detectorId": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

The unique ID of the created detector.

Type: String

Errors

(25)

See Also

CreateFilter

Creates a filter using the specified finding criteria.

Request Syntax

POST /detector/detectorId/filter HTTP/1.1 Content-type: application/json

{

"action": "string", "clientToken": "string", "description": "string", "findingCriteria": { "criterion": { "string" : {

"eq": [ "string" ], "equals": [ "string" ], "greaterThan": number,

"greaterThanOrEqual": number, "gt": number,

"gte": number, "lessThan": number, "lessThanOrEqual": number, "lt": number,

"lte": number, "neq": [ "string" ], "notEquals": [ "string" ] }

} },

"name": "string", "rank": number, "tags": {

"string" : "string"

}}

URI Request Parameters

The ID of the detector belonging to the GuardDuty account that you want to create a ﬁlter for.

Required: Yes

Request Body

action (p. 11)

Specifies the action that is to be applied to the findings that match the filter.

(27)

Request Body

Type: String

Valid Values: NOOP | ARCHIVE Required: No

Type: String

Required: No description (p. 11)

The description of the ﬁlter.

Type: String

Required: No ﬁndingCriteria (p. 11)

Represents the criteria to be used in the ﬁlter for querying ﬁndings.

You can only use the following attributes to query ﬁndings:

• accountId

• region

• conﬁdence

• id

• resource.accessKeyDetails.accessKeyId

• resource.accessKeyDetails.principalId

• resource.accessKeyDetails.userName

• resource.accessKeyDetails.userType

• resource.instanceDetails.iamInstanceProﬁle.id

• resource.instanceDetails.imageId

• resource.instanceDetails.instanceId

• resource.instanceDetails.outpostArn

• resource.instanceDetails.networkInterfaces.ipv6Addresses

• resource.instanceDetails.networkInterfaces.privateIpAddresses.privateIpAddress

• resource.instanceDetails.networkInterfaces.publicDnsName

• resource.instanceDetails.networkInterfaces.publicIp

• resource.instanceDetails.networkInterfaces.securityGroups.groupId

• resource.instanceDetails.networkInterfaces.securityGroups.groupName

• resource.instanceDetails.networkInterfaces.subnetId

• resource.instanceDetails.networkInterfaces.vpcId

• resource.instanceDetails.tags.key

• resource.instanceDetails.tags.value

• resource.resourceType

(28)

Request Body

• service.action.actionType

• service.action.awsApiCallAction.api

• service.action.awsApiCallAction.callerType

• service.action.awsApiCallAction.errorCode

• service.action.awsApiCallAction.userAgent

• service.action.awsApiCallAction.remoteIpDetails.city.cityName

• service.action.awsApiCallAction.remoteIpDetails.country.countryName

• service.action.awsApiCallAction.remoteIpDetails.ipAddressV4

• service.action.awsApiCallAction.remoteIpDetails.organization.asn

• service.action.awsApiCallAction.remoteIpDetails.organization.asnOrg

• service.action.awsApiCallAction.serviceName

• service.action.dnsRequestAction.domain

• service.action.networkConnectionAction.blocked

• service.action.networkConnectionAction.connectionDirection

• service.action.networkConnectionAction.localPortDetails.port

• service.action.networkConnectionAction.protocol

• service.action.networkConnectionAction.localIpDetails.ipAddressV4

• service.action.networkConnectionAction.remoteIpDetails.city.cityName

• service.action.networkConnectionAction.remoteIpDetails.country.countryName

• service.action.networkConnectionAction.remoteIpDetails.ipAddressV4

• service.action.networkConnectionAction.remoteIpDetails.organization.asn

• service.action.networkConnectionAction.remoteIpDetails.organization.asnOrg

• service.action.networkConnectionAction.remotePortDetails.port

• service.additionalInfo.threatListName

• resource.s3BucketDetails.publicAccess.eﬀectivePermissions

• resource.s3BucketDetails.name

• resource.s3BucketDetails.tags.key

• resource.s3BucketDetails.tags.value

• resource.s3BucketDetails.type

• service.archived

When this attribute is set to TRUE, only archived findings are listed. When it's set to FALSE, only unarchived findings are listed. When this attribute is not set, all existing findings are listed.

• service.resourceRole

• severity

• type

• updatedAt

Type: ISO 8601 string format: YYYY-MM-DDTHH:MM:SS.SSSZ or YYYY-MM-DDTHH:MM:SSZ depending on whether the value contains milliseconds.

Type: FindingCriteria (p. 185) object Required: Yes

name (p. 11)

The name of the ﬁlter. Minimum length of 3. Maximum length of 64. Valid characters include alphanumeric characters, dot (.), underscore (_), and dash (-). Spaces are not allowed.

Type: String

(29)

Response Syntax

Required: Yes rank (p. 11)

Specifies the position of the filter in the list of current filters. Also specifies the order in which this filter is applied to the findings.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No tags (p. 11)

The tags to be added to a new ﬁlter resource.

Required: No

Response Syntax

HTTP/1.1 200

"name": "string"

}

Response Elements

name (p. 14)

The name of the successfully created ﬁlter.

Type: String

Errors

(30)

See Also

CreateIPSet

Creates a new IPSet, which is called a trusted IP list in the console user interface. An IPSet is a list of IP addresses that are trusted for secure communication with AWS infrastructure and applications.

GuardDuty doesn't generate ﬁndings for IP addresses that are included in IPSets. Only users from the administrator account can use this operation.

Request Syntax

POST /detector/detectorId/ipset HTTP/1.1 Content-type: application/json

{ "activate": boolean, "clientToken": "string", "format": "string", "location": "string", "name": "string", "tags": {

"string" : "string"

}}

URI Request Parameters

The unique ID of the detector of the GuardDuty account that you want to create an IPSet for.

Required: Yes

Request Body

activate (p. 16)

A Boolean value that indicates whether GuardDuty is to start using the uploaded IPSet.

Type: Boolean Required: Yes clientToken (p. 16)

Type: String

Required: No

(32)

Response Syntax

format (p. 16)

The format of the ﬁle that contains the IPSet.

Type: String

location (p. 16)

The URI of the ﬁle that contains the IPSet.

Type: String

Required: Yes name (p. 16)

The user-friendly name to identify the IPSet.

Allowed characters are alphanumerics, spaces, hyphens (-), and underscores (_).

Type: String

Required: Yes tags (p. 16)

The tags to be added to a new IP set resource.

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json { "ipSetId": "string"

}

Response Elements

(33)

Errors

ipSetId (p. 17)

The ID of the IPSet resource.

Type: String

Errors

CreateMembers

Creates member accounts of the current AWS account by specifying a list of AWS account IDs. This step is a prerequisite for managing the associated member accounts either by invitation or through an organization.

When using Create Members as an organizations delegated administrator this action will enable GuardDuty in the added member accounts, with the exception of the organization delegated administrator account, which must enable GuardDuty prior to being added as a member.

If you are adding accounts by invitation use this action after GuardDuty has been enabled in potential member accounts and before using Invite Members.

Request Syntax

POST /detector/detectorId/member HTTP/1.1 Content-type: application/json

{ "accountDetails": [ {

"accountId": "string", "email": "string"

} ]}

URI Request Parameters

The unique ID of the detector of the GuardDuty account that you want to associate member accounts with.

Required: Yes

Request Body

accountDetails (p. 19)

A list of account ID and email address pairs of the accounts that you want to associate with the GuardDuty administrator account.

Type: Array of AccountDetail (p. 154) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: Yes

(35)

Response Syntax

HTTP/1.1 200

"unprocessedAccounts": [ {

"accountId": "string", "result": "string"

} ]}

Response Elements

unprocessedAccounts (p. 20)

A list of objects that include the accountIds of the unprocessed accounts and a result string that explains why each was unprocessed.

Type: Array of UnprocessedAccount (p. 247) objects

Errors

CreatePublishingDestination

Creates a publishing destination to export ﬁndings to. The resource to export ﬁndings to must exist before you use this operation.

Request Syntax

POST /detector/detectorId/publishingDestination HTTP/1.1 Content-type: application/json

{ "clientToken": "string", "destinationProperties": { "destinationArn": "string", "kmsKeyArn": "string"

},

"destinationType": "string"

}

URI Request Parameters

The ID of the GuardDuty detector associated with the publishing destination.

Required: Yes

Request Body

The idempotency token for the request.

Type: String

Required: No

destinationProperties (p. 22)

The properties of the publishing destination, including the ARNs for the destination and the KMS key used for encryption.

Type: DestinationProperties (p. 175) object Required: Yes

destinationType (p. 22)

The type of resource for the publishing destination. Currently only Amazon S3 buckets are supported.

(38)

Response Syntax

Type: String

Valid Values: S3 Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "destinationId": "string"

}

Response Elements

destinationId (p. 23)

The ID of the publishing destination that is created.

Type: String

Errors

CreateSampleFindings

Generates example findings of types specified by the list of finding types. If 'NULL' is specified for findingTypes, the API generates example findings of all supported finding types.

Request Syntax

POST /detector/detectorId/findings/create HTTP/1.1 Content-type: application/json

{ "findingTypes": [ "string" ] }

URI Request Parameters

The ID of the detector to create sample ﬁndings for.

Required: Yes

Request Body

ﬁndingTypes (p. 25)

The types of sample ﬁndings to generate.

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(41)

See Also

CreateThreatIntelSet

Creates a new ThreatIntelSet. ThreatIntelSets consist of known malicious IP addresses. GuardDuty generates ﬁndings based on ThreatIntelSets. Only users of the administrator account can use this operation.

Request Syntax

POST /detector/detectorId/threatintelset HTTP/1.1 Content-type: application/json

{

"activate": boolean, "clientToken": "string", "format": "string", "location": "string", "name": "string", "tags": {

"string" : "string"

}}

URI Request Parameters

The unique ID of the detector of the GuardDuty account that you want to create a threatIntelSet for.

Required: Yes

Request Body

activate (p. 27)

A Boolean value that indicates whether GuardDuty is to start using the uploaded ThreatIntelSet.

Type: Boolean Required: Yes clientToken (p. 27)

Type: String

Required: No format (p. 27)

The format of the ﬁle that contains the ThreatIntelSet.

(43)

Response Syntax

Type: String

location (p. 27)

The URI of the ﬁle that contains the ThreatIntelSet.

Type: String

Required: Yes name (p. 27)

A user-friendly ThreatIntelSet name displayed in all ﬁndings that are generated by activity that involves IP addresses included in this ThreatIntelSet.

Type: String

Required: Yes tags (p. 27)

The tags to be added to a new threat list resource.

Required: No

Response Syntax

HTTP/1.1 200

Content-type: application/json { "threatIntelSetId": "string"

}

Response Elements

(44)

Errors

threatIntelSetId (p. 28)

The ID of the ThreatIntelSet resource.

Type: String

Errors

DeclineInvitations

Declines invitations sent to the current member account by AWS accounts speciﬁed by their account IDs.

Request Syntax

POST /invitation/decline HTTP/1.1 Content-type: application/json {

"accountIds": [ "string" ] }

URI Request Parameters

Request Body

accountIds (p. 30)

A list of account IDs of the AWS accounts that sent invitations to the current member account that you want to decline invitations from.

Length Constraints: Fixed length of 12.

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "unprocessedAccounts": [ {

} ] }

Response Elements

(46)

Errors

A list of objects that contain the unprocessed account and a result string that explains why it was unprocessed.

Errors

DeleteDetector

Deletes an Amazon GuardDuty detector that is speciﬁed by the detector ID.

Request Syntax

DELETE /detector/detectorId HTTP/1.1

URI Request Parameters

The unique ID of the detector that you want to delete.

Required: Yes

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements

Errors

DeleteFilter

Deletes the filter specified by the filter name.

Request Syntax

DELETE /detector/detectorId/filter/filterName HTTP/1.1

URI Request Parameters

The unique ID of the detector that the ﬁlter is associated with.

Required: Yes ﬁlterName (p. 34)

The name of the ﬁlter that you want to delete.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(50)

See Also

DeleteInvitations

Deletes invitations sent to the current member account by AWS accounts speciﬁed by their account IDs.

Request Syntax

POST /invitation/delete HTTP/1.1 Content-type: application/json {

"accountIds": [ "string" ] }

URI Request Parameters

Request Body

A list of account IDs of the AWS accounts that sent invitations to the current member account that you want to delete invitations from.

Required: Yes

Response Syntax

HTTP/1.1 200

} ] }

Response Elements

(52)

Errors

A list of objects that contain the unprocessed account and a result string that explains why it was unprocessed.

Errors

DeleteIPSet

Deletes the IPSet speciﬁed by the ipSetId. IPSets are called trusted IP lists in the console user interface.

Request Syntax

DELETE /detector/detectorId/ipset/ipSetId HTTP/1.1

URI Request Parameters

The unique ID of the detector associated with the IPSet.

Required: Yes ipSetId (p. 38)

The unique ID of the IPSet to delete.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(54)

See Also

DeleteMembers

Deletes GuardDuty member accounts (to the current GuardDuty administrator account) speciﬁed by the account IDs.

Request Syntax

POST /detector/detectorId/member/delete HTTP/1.1 Content-type: application/json

{ "accountIds": [ "string" ] }

URI Request Parameters

The unique ID of the detector of the GuardDuty account whose members you want to delete.

Required: Yes

Request Body

A list of account IDs of the GuardDuty member accounts that you want to delete.

Required: Yes

Response Syntax

HTTP/1.1 200

} ]

(56)

Response Elements

}

Response Elements

The accounts that could not be processed.

Errors

DeletePublishingDestination

Deletes the publishing deﬁnition with the speciﬁed destinationId.

Request Syntax

DELETE /detector/detectorId/publishingDestination/destinationId HTTP/1.1

URI Request Parameters

destinationId (p. 42)

The ID of the publishing destination to delete.

Required: Yes detectorId (p. 42)

The unique ID of the detector associated with the publishing destination to delete.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(58)

See Also

Amazon GuardDuty

Amazon GuardDuty

API Reference

API Version 2017-11-28

Amazon GuardDuty: API Reference

Table of Contents

Welcome

Actions

AcceptInvitation

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

ArchiveFindings

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateDetector

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateFilter

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateIPSet

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateMembers

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreatePublishingDestination

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateSampleFindings

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateThreatIntelSet

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also