Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

ListFindings

Lists GuardDuty findings for the specified detector ID.

There might be regional differences because some flags might not be available in all the Regions where GuardDuty is currently supported. For more information, see Regions and endpoints.

Request Syntax


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

{
   "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" ]
         }
      }
   },
   "maxResults": number,
   "nextToken": "string",
   "sortCriteria": { 
      "attributeName": "string",
      "orderBy": "string"
   }
}

URI Request Parameters

The request uses the following URI parameters.

detectorId

The ID of the detector that specifies the GuardDuty service whose findings you want to list.

To find the detectorId in the current Region, see the Settings page in the GuardDuty console, or run the ListDetectors API.

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

Required: Yes

Request Body

The request accepts the following data in JSON format.

findingCriteria

Represents the criteria used for querying findings. Valid values include:

JSON field name
accountId
region
confidence
id
resource.accessKeyDetails.accessKeyId
resource.accessKeyDetails.principalId
resource.accessKeyDetails.userName
resource.accessKeyDetails.userType
resource.instanceDetails.iamInstanceProfile.id
resource.instanceDetails.imageId
resource.instanceDetails.instanceId
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
service.action.actionType
service.action.awsApiCallAction.api
service.action.awsApiCallAction.callerType
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.dnsRequestAction.domainWithSuffix
service.action.networkConnectionAction.blocked
service.action.networkConnectionAction.connectionDirection
service.action.networkConnectionAction.localPortDetails.port
service.action.networkConnectionAction.protocol
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
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.ebsVolumeScanDetails.scanId
service.resourceRole
severity
type
updatedAt

Type: Timestamp in Unix Epoch millisecond format: 1486685375000

Type: FindingCriteria object

Required: No

maxResults

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 50. The maximum value is 50.

Type: Integer

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

Required: No

nextToken

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the list action. For subsequent calls to the action, fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

Type: String

Required: No

sortCriteria

Represents the criteria used for sorting findings.

Type: SortCriteria object

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "findingIds": [ "string" ],
   "nextToken": "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.

findingIds

The IDs of the findings that you're listing.

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 300.

nextToken

The pagination parameter to be used on the next list operation to retrieve more items.

Type: String

Errors

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

BadRequestException

A bad request exception object.

HTTP Status Code: 400

InternalServerErrorException

An internal server error exception object.

HTTP Status Code: 500