# CreateFilter Creates a filter using the specified finding criteria. The maximum number of saved filters per AWS account per Region is 100. For more information, see [Quotas for GuardDuty](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_limits.html). ## 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, "matches": [ "string" ], "neq": [ "string" ], "notEquals": [ "string" ], "notMatches": [ "string" ] } } }, "name": "string", "rank": number, "tags": { "string" : "string" } } ``` ## URI Request Parameters The request uses the following URI parameters. ** [detectorId](#API_CreateFilter_RequestSyntax) ** The detector ID associated with the GuardDuty account for which you want to create a filter. To find the `detectorId` in the current Region, see the Settings page in the GuardDuty console, or run the [ListDetectors](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListDetectors.html) API. Length Constraints: Minimum length of 1. Maximum length of 300. Required: Yes ## Request Body The request accepts the following data in JSON format. ** [action](#API_CreateFilter_RequestSyntax) ** 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](#API_CreateFilter_RequestSyntax) ** The idempotency token for the create request. Type: String Length Constraints: Minimum length of 0. Maximum length of 64. Required: No ** [description](#API_CreateFilter_RequestSyntax) ** 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 ** [findingCriteria](#API_CreateFilter_RequestSyntax) ** 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 AWS CLI use the following input list for the [FindingCriteria](https://docs.aws.amazon.com/guardduty/latest/APIReference/API_FindingCriteria.html) condition: + **Low**: `["1", "2", "3"]` + **Medium**: `["4", "5", "6"]` + **High**: `["7", "8"]` + **Critical**: `["9", "10"]` For more information, see [Findings severity levels](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_findings-severity.html) in the *Amazon GuardDuty User Guide*. + 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.iamInstanceProfile.id + 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.name + 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.city.cityName + service.action.awsApiCallAction.remoteIpDetails.country.countryName + service.action.awsApiCallAction.remoteIpDetails.ipAddressV4 + service.action.awsApiCallAction.remoteIpDetails.ipAddressV6 + 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.dnsRequestAction.vpcOwnerAccountId + service.action.networkConnectionAction.blocked + service.action.networkConnectionAction.connectionDirection + service.action.networkConnectionAction.localPortDetails.port + service.action.networkConnectionAction.protocol + service.action.networkConnectionAction.remoteIpDetails.city.cityName + service.action.networkConnectionAction.remoteIpDetails.country.countryName + service.action.networkConnectionAction.remoteIpDetails.ipAddressV4 + service.action.networkConnectionAction.remoteIpDetails.ipAddressV6 + 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.remoteIpDetails.ipAddressV6 + service.action.kubernetesApiCallAction.namespace + service.action.kubernetesApiCallAction.remoteIpDetails.organization.asn + service.action.kubernetesApiCallAction.requestUri + service.action.kubernetesApiCallAction.statusCode + service.action.networkConnectionAction.localIpDetails.ipAddressV4 + service.action.networkConnectionAction.localIpDetails.ipAddressV6 + service.action.networkConnectionAction.protocol + service.action.awsApiCallAction.serviceName + service.action.awsApiCallAction.remoteAccountDetails.accountId + service.additionalInfo.threatListName + service.resourceRole + resource.eksClusterDetails.name + resource.kubernetesDetails.kubernetesWorkloadDetails.name + 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.name + service.ebsVolumeScanDetails.scanDetections.threatDetectedByName.threatNames.severity + service.ebsVolumeScanDetails.scanDetections.threatDetectedByName.threatNames.filePaths.hash + resource.ecsClusterDetails.name + 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 + service.runtimeDetails.process.name + service.runtimeDetails.process.executablePath + resource.lambdaDetails.functionName + resource.lambdaDetails.functionArn + resource.lambdaDetails.tags.key + resource.lambdaDetails.tags.value Type: [FindingCriteria](API_FindingCriteria.md) object Required: Yes ** [name](#API_CreateFilter_RequestSyntax) ** The name of the filter. Valid characters include period (.), underscore (\$1), 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 ** [rank](#API_CreateFilter_RequestSyntax) ** 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](#API_CreateFilter_RequestSyntax) ** 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](#API_CreateFilter_ResponseSyntax) ** 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 Error Types](CommonErrors.md). ** BadRequestException ** A bad request exception object. ** Message ** The error message. ** Type ** The error type. HTTP Status Code: 400 ** InternalServerErrorException ** An internal server error exception object. ** Message ** The error message. ** Type ** The error type. 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 V2](https://docs.aws.amazon.com/goto/cli2/guardduty-2017-11-28/CreateFilter) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/guardduty-2017-11-28/CreateFilter) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/guardduty-2017-11-28/CreateFilter) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/guardduty-2017-11-28/CreateFilter) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/guardduty-2017-11-28/CreateFilter) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/guardduty-2017-11-28/CreateFilter) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/guardduty-2017-11-28/CreateFilter) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/guardduty-2017-11-28/CreateFilter) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/guardduty-2017-11-28/CreateFilter) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/guardduty-2017-11-28/CreateFilter)