Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors 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 request uses the following URI parameters.

detectorId

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

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

Type: String

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

Valid Values: NOOP | ARCHIVE

Required: No

clientToken

The idempotency token for the create request.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 64.

Required: No

description

The description of the filter.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 512.

Required: No

findingCriteria

Represents the criteria to be used in the filter for querying findings.

You can only use the following attributes to query findings:

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.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
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.effectivePermissions
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 object

Required: Yes

name

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

Length Constraints: Minimum length of 3. Maximum length of 64.

Required: Yes

rank

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

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

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.

BadRequestException

A bad request exception object.

HTTP Status Code: 400

InternalServerErrorException

An internal server error exception object.

HTTP Status Code: 500