Skip to content
API Enriched

Top Malicious Bots by User Agent String v4.

POST
/api/shape/bot/namespaces/{namespace}/v4/reporting/top/type/malicious/dimension/ua
curl --request POST \
  --url https://example-corp.console.ves.volterra.io/api/v1/api/production/us-east-1/namespaces/default/api/shape/bot/namespaces/example/v4/reporting/top/type/malicious/dimension/ua \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "attack_type": "example", "end_time": "example", "filters": { "action_taken": { "actions_taken": [ "example" ], "op": "IN" }, "app_id_filter": { "app_id_strings": [ "example" ], "op": "IN" }, "application_name": { "application_names": [ "example" ], "op": "IN" }, "as_org_filter": { "as_orgs": [ "example" ], "op": "IN" }, "attack_intent_filter": { "attack_intent_strings": [ "example" ], "op": "IN" }, "automation_type_filter": { "automation_type_strings": [ "example" ], "op": "IN" }, "browser_filter": { "browser_strings": [ "example" ], "op": "IN" }, "country_filter": { "country_strings": [ "example" ], "op": "IN" }, "host_filter": { "host_strings": [ "example" ], "op": "IN" }, "inference_filter": { "inference_strings": [ "example" ], "op": "IN" }, "ip_filter": { "ips": [ "example" ], "op": "IN" }, "method_filter": { "method_strings": [ "example" ], "op": "IN" }, "os_filter": { "op": "IN", "os_strings": [ "example" ] }, "referer_filter": { "op": "IN", "referer_strings": [ "example" ] }, "region_filter": "US", "traffic_type_filter": { "op": "IN", "traffic_type_strings": [ "example" ] }, "ua_filter": { "op": "IN", "ua_strings": [ "example" ] }, "uri_filter": { "op": "IN", "uri_strings": [ "example" ] } }, "limit": 1, "namespace": "example", "start_time": "example", "virtual_host": "example" }'

GET top malicious bots by user agent string v4, with the new definition of malicious bot for sub categories feature.

Examples of this operation.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
namespace
required
string

Namespace

x-required namespace is used to scope traffic overview query. Only virtual_host in given namespace will be considered.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
TopRequest

Request for top malicious bots.

object
attack_type
Attack Intent Type

Optional: this is the query parameter for top source of attack types Used in TopTafficEventsByIP.

string
<= 1024 characters
end_time
End time

End time of traffic overview query period Format: unix_timestamp|RFC 3339

Optional: If not specified, then the end_time will be evaluated to start_time+10m If start_time is not specified, then the end_time will be evaluated to

string
<= 1024 characters
filters
object
action_taken
object
actions_taken
Action Taken

A list of strings Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
app_id_filter
object
app_id_strings
App ID Strings

An unordered list of App ID strings Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
application_name
object
application_names
Application Name

A list of strings Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
as_org_filter
object
as_orgs
AS Organizations

An unordered list of as org strings Required: YES.

Array<string>
>= 1 items <= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
attack_intent_filter
object
attack_intent_strings
Attack Intent Strings

An list of strings Required: YES.

Array<string>
>= 1 items <= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
automation_type_filter
object
automation_type_strings
Automation Type Strings

An list of strings Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
browser_filter
object
browser_strings
Browser Strings

An list of strings Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
country_filter
object
country_strings
Country Strings

An list of strings Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
host_filter
object
host_strings
Host Strings

An list of strings Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
inference_filter
object
inference_strings
Inference Strings

An list of strings Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
ip_filter
object
ips
IP Addresses

An unordered list of IPv4 addresses Required: YES.

Array<string>
<= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
method_filter
object
method_strings
Method Strings

An list of strings Required: YES.

Array<string>
>= 1 items <= 64 items
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
os_filter
object
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
os_strings
OS Strings

An list of strings Required: YES.

Array<string>
<= 64 items
referer_filter
object
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
referer_strings
Inference Strings

An list of strings Required: YES.

Array<string>
<= 64 items
region_filter
string
default: US
Allowed values: US EU ASIA CA
traffic_type_filter
object
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
traffic_type_strings
Traffic Type Strings

An list of strings Required: YES.

Array<string>
<= 64 items
ua_filter
object
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
ua_strings
User Agent Strings

An unordered list of user agent strings Required: YES.

Array<string>
<= 64 items
uri_filter
object
op
string
default: IN
Allowed values: IN NOT_IN MATCHES_REGEX DOES_NOT_MATCH_REGEX INCLUDES DOES_NOT_INCLUDE STARTS_WITH ENDS_WITH
uri_strings
URI Strings

An list of strings Required: YES.

Array<string>
<= 64 items
limit
Limit

Number of top malicious bots to query Optional: if not specified, the query will include top 10 malicious bots.

integer format: int64
namespace
Namespace

Namespace is used to scope traffic overview query. Only virtual_host in given namespace will be considered. Required: YES.

string
>= 6 characters <= 1024 characters
start_time
Start time

Start time of traffic overview query period Format: unix_timestamp|RFC 3339

Optional: If not specified, then the start_time will be evaluated to end_time-10m If end_time is not specified, then the start_time will be evaluated to -10m.

string
<= 1024 characters
virtual_host
Virtual Host Name

Name of Virtual Host to scope traffic overview query Required: YES.

string
<= 1024 characters

Responses

Section titled “Responses”

200

Section titled “200”

A successful response.

Media typeapplication/json
TopMaliciousBotsByUAResponseV4

Response for top malicious bots by user agent string with action distribution.

object
malicious_bots
Top Malicious Bots by User Agent

The list of top malicious bots by User Agent String.

Array<object>
Malicious Bot User Agent Data V4

Malicious bot user agent data with action distribution.

object
actions
Endpoint Traffic Actions

Endpoint Traffic Actions.

Array<object>
object
action_taken
Item Name

The Action Taken for automated bot traffic.

string
<= 1024 characters
count
Current Total Count for the action

The total count of the action taken.

string format: uint64
<= 1024 characters
browser
Browser

Browser name.

string
<= 1024 characters
malicious_bot_request_count
Malicious Bot Request Count

Number of HTTP requests identified as malicious bot.

string format: uint64
<= 1024 characters
malicious_bot_request_percentage
Malicious Bot Request Percentage

The percentage of malicious bot requests in total requests.

number format: double
total_percentage
Total Percentage

Total Percentage.

number format: double
ua
User Agent String

User Agent String.

string
<= 1024 characters
Examplegenerated
{
  "malicious_bots": [
    {
      "actions": [
        {
          "action_taken": "example",
          "count": "example"
        }
      ],
      "browser": "example",
      "malicious_bot_request_count": "example",
      "malicious_bot_request_percentage": 1,
      "total_percentage": 1,
      "ua": "example"
    }
  ]
}

401

Section titled “401”

Returned when operation is not authorized.

Media typeapplication/json
string format: string
Examplegenerated
example

403

Section titled “403”

Returned when there is no permission to access resource.

Media typeapplication/json
string format: string
Examplegenerated
example

404

Section titled “404”

Returned when resource is not found.

Media typeapplication/json
string format: string
Examplegenerated
example

409

Section titled “409”

Returned when operation on resource is conflicting with current value.

Media typeapplication/json
string format: string
Examplegenerated
example

429

Section titled “429”

Returned when operation has been rejected as it is happening too frequently.

Media typeapplication/json
string format: string
Examplegenerated
example

500

Section titled “500”

Returned when server encountered an error in processing API.

Media typeapplication/json
string format: string
Examplegenerated
example

503

Section titled “503”

Returned when service is unavailable temporarily.

Media typeapplication/json
string format: string
Examplegenerated
example

504

Section titled “504”

Returned when server timed out processing request.

Media typeapplication/json
string format: string
Examplegenerated
example