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
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: