For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
API Version 2017-11-28 7
CreateDetector
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": {
"enable": boolean,
"findingPublishingFrequency": "string", "tags": {
"string" : "string"
}}
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
clientToken (p. 8)
The idempotency token for the create request.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 64.
Required: No dataSources (p. 8)
Describes which data sources will be enabled for the detector.
Type: DataSourceConfigurations (p. 171) object Required: No
enable (p. 8)
A Boolean value that specifies whether the detector is to be enabled.
Response Syntax
Type: Boolean Required: Yes
findingPublishingFrequency (p. 8)
A value that specifies how frequently updated findings 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
Content-type: application/json {
"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.
detectorId (p. 9)
The unique ID of the created detector.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 257).
BadRequestException
A bad request exception object.
API Version 2017-11-28 9
See Also
HTTP Status Code: 400 InternalServerErrorException
An internal server error exception object.
HTTP Status Code: 500
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
CreateFilter
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": {
"name": "string", "rank": number, "tags": {
"string" : "string"
}}
URI Request Parameters
The request uses the following URI parameters.
detectorId (p. 11)
The ID of the detector belonging to the GuardDuty account that you want to create a filter for.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes
Request Body
The request accepts the following data in JSON format.
action (p. 11)
Specifies the action that is to be applied to the findings that match the filter.
API Version 2017-11-28 11
Request Body
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Valid Values: NOOP | ARCHIVE Required: No
clientToken (p. 11)
The idempotency token for the create request.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 64.
Required: No description (p. 11)
The description of the filter.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 512.
Required: No findingCriteria (p. 11)
Represents the criteria to be used in the filter for querying findings.
You can only use the following attributes to query findings:
• accountId
Request Body
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 filter. Minimum length of 3. Maximum length of 64. Valid characters include alphanumeric characters, dot (.), underscore (_), and dash (-). Spaces are not allowed.
Type: String
API Version 2017-11-28 13
Response Syntax
Length Constraints: Minimum length of 3. Maximum length of 64.
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 filter 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
Content-type: application/json {
"name": "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.
name (p. 14)
The name of the successfully created filter.
Type: String
Length Constraints: Minimum length of 3. Maximum length of 64.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 257).
See Also
BadRequestException
A bad request exception object.
HTTP Status Code: 400 InternalServerErrorException
An internal server error exception object.
HTTP Status Code: 500
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
API Version 2017-11-28 15
CreateIPSet
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 findings 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 request uses the following URI parameters.
detectorId (p. 16)
The unique ID of the detector of the GuardDuty account that you want to create an IPSet for.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes
Request Body
The request accepts the following data in JSON format.
activate (p. 16)
A Boolean value that indicates whether GuardDuty is to start using the uploaded IPSet.
Type: Boolean Required: Yes clientToken (p. 16)
The idempotency token for the create request.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 64.
Required: No
Response Syntax
format (p. 16)
The format of the file that contains the IPSet.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Valid Values: TXT | STIX | OTX_CSV | ALIEN_VAULT | PROOF_POINT | FIRE_EYE Required: Yes
location (p. 16)
The URI of the file that contains the IPSet.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes name (p. 16)
The user-friendly name to identify the IPSet.
Allowed characters are alphanumerics, spaces, hyphens (-), and underscores (_).
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes tags (p. 16)
The tags to be added to a new IP set 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
Content-type: application/json { "ipSetId": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
API Version 2017-11-28 17
Errors
The following data is returned in JSON format by the service.
ipSetId (p. 17)
The ID of the IPSet resource.
Type: String
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
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
CreateMembers
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 request uses the following URI parameters.
detectorId (p. 19)
The unique ID of the detector of the GuardDuty account that you want to associate member accounts with.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes
Request Body
The request accepts the following data in JSON format.
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
API Version 2017-11-28 19
Response Syntax
Response Syntax
HTTP/1.1 200
Content-type: application/json {
"unprocessedAccounts": [ {
"accountId": "string", "result": "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.
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
Array Members: Minimum number of 0 items. Maximum number of 50 items.
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
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
See Also
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
API Version 2017-11-28 21
CreatePublishingDestination
CreatePublishingDestination
Creates a publishing destination to export findings to. The resource to export findings 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 request uses the following URI parameters.
detectorId (p. 22)
The ID of the GuardDuty detector associated with the publishing destination.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes
Request Body
The request accepts the following data in JSON format.
clientToken (p. 22)
The idempotency token for the request.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 64.
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.
Response Syntax
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Valid Values: S3 Required: Yes
Response Syntax
HTTP/1.1 200
Content-type: application/json { "destinationId": "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.
destinationId (p. 23)
The ID of the publishing destination that is created.
Type: String
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
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
API Version 2017-11-28 23
See Also
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
CreateSampleFindings
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 request uses the following URI parameters.
detectorId (p. 25)
The ID of the detector to create sample findings for.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes
Request Body
The request accepts the following data in JSON format.
findingTypes (p. 25)
The types of sample findings to generate.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 50 items.
Length Constraints: Minimum length of 1. Maximum length of 50.
Required: No
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.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 257).
API Version 2017-11-28 25
See Also
BadRequestException
A bad request exception object.
HTTP Status Code: 400 InternalServerErrorException
An internal server error exception object.
HTTP Status Code: 500
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
CreateThreatIntelSet
CreateThreatIntelSet
Creates a new ThreatIntelSet. ThreatIntelSets consist of known malicious IP addresses. GuardDuty generates findings 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 request uses the following URI parameters.
detectorId (p. 27)
The unique ID of the detector of the GuardDuty account that you want to create a threatIntelSet for.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes
Request Body
The request accepts the following data in JSON format.
activate (p. 27)
A Boolean value that indicates whether GuardDuty is to start using the uploaded ThreatIntelSet.
Type: Boolean Required: Yes clientToken (p. 27)
The idempotency token for the create request.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 64.
Required: No format (p. 27)
The format of the file that contains the ThreatIntelSet.
API Version 2017-11-28 27
Response Syntax
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Valid Values: TXT | STIX | OTX_CSV | ALIEN_VAULT | PROOF_POINT | FIRE_EYE Required: Yes
location (p. 27)
The URI of the file that contains the ThreatIntelSet.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes name (p. 27)
A user-friendly ThreatIntelSet name displayed in all findings that are generated by activity that involves IP addresses included in this ThreatIntelSet.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes tags (p. 27)
The tags to be added to a new threat list 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
Content-type: application/json { "threatIntelSetId": "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.
Errors
threatIntelSetId (p. 28)
The ID of the ThreatIntelSet resource.
Type: String
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
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
API Version 2017-11-28 29
DeclineInvitations
DeclineInvitations
Declines invitations sent to the current member account by AWS accounts specified by their account IDs.
Request Syntax
POST /invitation/decline HTTP/1.1 Content-type: application/json {
"accountIds": [ "string" ] }
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
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.
Type: Array of strings
Array Members: Minimum number of 1 item. Maximum number of 50 items.
Length Constraints: Fixed length of 12.
Required: Yes
Response Syntax
HTTP/1.1 200
Content-type: application/json { "unprocessedAccounts": [ {
"accountId": "string", "result": "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.
Errors
unprocessedAccounts (p. 30)
A list of objects that contain the unprocessed account and a result string that explains why it was unprocessed.
Type: Array of UnprocessedAccount (p. 247) objects
Array Members: Minimum number of 0 items. Maximum number of 50 items.
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
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
API Version 2017-11-28 31
DeleteDetector
DeleteDetector
Deletes an Amazon GuardDuty detector that is specified by the detector ID.
Request Syntax
DELETE /detector/detectorId HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
detectorId (p. 32)
The unique ID of the detector that you want to delete.
Length Constraints: Minimum length of 1. Maximum length of 300.
Required: Yes
Request Body
The request does not have a request body.
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.
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
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
See Also
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
API Version 2017-11-28 33
DeleteFilter
DeleteFilter
Deletes the filter specified by the filter name.
Request Syntax
DELETE /detector/detectorId/filter/filterName HTTP/1.1
URI Request Parameters
The request uses the following URI parameters.
detectorId (p. 34)
The unique ID of the detector that the filter is associated with.
Length Constraints: Minimum length of 1. Maximum length of 300.
Length Constraints: Minimum length of 1. Maximum length of 300.