CreateFilter - Amazon GuardDuty
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).


Creates a filter using the specified finding criteria. The maximum number of saved filters per Amazon account per Region is 100. For more information, see Quotas for GuardDuty.

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.


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.


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


The idempotency token for the create request.

Type: String

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

Required: No


The description of the filter. Valid characters include alphanumeric characters, and special characters such as hyphen, period, colon, underscore, parentheses ({ }, [ ], and ( )), forward slash, horizontal tab, vertical tab, newline, form feed, return, and whitespace.

Type: String

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

Required: No


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

You can only use the following attributes to query findings:

  • accountId

  • id

  • region

  • severity

    To filter on the basis of severity, the API and Amazon CLI use the following input list for the FindingCriteria condition:

    • Low: ["1", "2", "3"]

    • Medium: ["4", "5", "6"]

    • High: ["7", "8", "9"]

    For more information, see Severity levels for GuardDuty findings.

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

  • resource.accessKeyDetails.accessKeyId

  • resource.accessKeyDetails.principalId

  • resource.accessKeyDetails.userName

  • resource.accessKeyDetails.userType


  • resource.instanceDetails.imageId

  • resource.instanceDetails.instanceId

  • resource.instanceDetails.tags.key

  • resource.instanceDetails.tags.value

  • 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.outpostArn

  • resource.resourceType

  • resource.s3BucketDetails.publicAccess.effectivePermissions


  • resource.s3BucketDetails.tags.key

  • resource.s3BucketDetails.tags.value

  • resource.s3BucketDetails.type

  • service.action.actionType

  • service.action.awsApiCallAction.api

  • service.action.awsApiCallAction.callerType

  • service.action.awsApiCallAction.errorCode



  • 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.remoteIpDetails.ipAddressV4

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

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

  • service.action.networkConnectionAction.remotePortDetails.port

  • service.action.awsApiCallAction.remoteAccountDetails.affiliated

  • service.action.kubernetesApiCallAction.remoteIpDetails.ipAddressV4

  • service.action.kubernetesApiCallAction.requestUri

  • service.action.networkConnectionAction.localIpDetails.ipAddressV4

  • service.action.networkConnectionAction.protocol

  • service.action.awsApiCallAction.serviceName

  • service.action.awsApiCallAction.remoteAccountDetails.accountId

  • service.additionalInfo.threatListName

  • service.resourceRole



  • resource.kubernetesDetails.kubernetesWorkloadDetails.namespace

  • resource.kubernetesDetails.kubernetesUserDetails.username

  • resource.kubernetesDetails.kubernetesWorkloadDetails.containers.image

  • resource.kubernetesDetails.kubernetesWorkloadDetails.containers.imagePrefix

  • service.ebsVolumeScanDetails.scanId


  • service.ebsVolumeScanDetails.scanDetections.threatDetectedByName.threatNames.severity

  • service.ebsVolumeScanDetails.scanDetections.threatDetectedByName.threatNames.filePaths.hash


  • resource.ecsClusterDetails.taskDetails.containers.image

  • resource.ecsClusterDetails.taskDetails.definitionArn

  • resource.containerDetails.image

  • resource.rdsDbInstanceDetails.dbInstanceIdentifier

  • resource.rdsDbInstanceDetails.dbClusterIdentifier

  • resource.rdsDbInstanceDetails.engine

  • resource.rdsDbUserDetails.user

  • resource.rdsDbInstanceDetails.tags.key

  • resource.rdsDbInstanceDetails.tags.value

  • service.runtimeDetails.process.executableSha256



  • resource.lambdaDetails.functionName

  • resource.lambdaDetails.functionArn

  • resource.lambdaDetails.tags.key

  • resource.lambdaDetails.tags.value

Type: FindingCriteria object

Required: Yes


The name of the filter. Valid characters include period (.), underscore (_), dash (-), and alphanumeric characters. A whitespace is considered to be an invalid character.

Type: String

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

Required: Yes


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


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.


The name of the successfully created filter.

Type: String

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


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


A bad request exception object.

HTTP Status Code: 400


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 Amazon SDKs, see the following: