Skip to content
API Enriched

Security Events Query.

POST
/api/data/namespaces/{namespace}/app_security/events
curl --request POST \
  --url https://example-corp.console.ves.volterra.io/api/v1/api/production/us-east-1/namespaces/default/api/data/namespaces/example/app_security/events \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "aggs": {}, "end_time": "example", "limit": 1, "namespace": "example", "query": "example", "scroll": true, "sort": "DESCENDING", "sort_by": "example", "start_time": "example", "search_after": true, "sort_values": { "last_doc_id": "example", "last_timestamp": 1 } }'

GET security events for the given namespace. For system namespace, all security events for the tenant matching the query specified in the request will be returned in the response. User may query security events that matches various fields such as vh_name, sec_event_type, src_site, city, country.

Examples of this operation.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
namespace
required
string

Namespace

fetch security events for a given namespace.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
Security Events Request

Request to fetch security events.

object
aggs
aggregations

Aggregations provide summary/analytics data over the security events response. If the number of security events that matched the query is large and cannot be returned in a single response message, user can GET helpful insights/summary using aggregations. The aggregations are key’ed by user-defined aggregation name. The response will be key’ed with the same name. Optional.

object
end_time
end time

Fetch security events whose timestamp <= end_time 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
limit
limit

Limits the number of security events returned in the response Optional: If not specified, first or last 500 security events that matches the query (depending on the sort order) will be returned in the response. The maximum value for limit is 500.

integer format: int32
namespace
namespace

Fetch security events for a given namespace.

string
>= 6 characters <= 1024 characters
query
query

Query is used to specify the list of matchers syntax for query := {[]} := <field_name>"" <field_name> := string One or more of these fields in the security event may be specified in the query. Vh_name - name of the virtual host src_site - source site city - name of the city country - country code := string := [”=”|”!=”|”=”|”!”] = : equal to != : not equal to =~ : regex match !~ : not regex match When more than one matcher is specified in the query, then security events matching ALL the matchers will be returned in the response. Example: query={country=“United States”, city=“California”} will return all security events originating from California, United States.

Optional: If not specified, all the security events matching the given tenant and namespace will be returned in the response.

string
<= 1024 characters
scroll
scroll

Scroll is used to retrieve large number of security events (or all security events) that matches the query. If scroll is set to true, the scroll_id in the response can be used in the scroll API to fetch the next batch of security events until there are no more security events left to return. The number of messages in each batch is determined by the limit field. Note: Scroll is used for processing large amount of data and therefore is not intended for real time user request. Optional: default is false.

boolean format: boolean
sort
string
default: DESCENDING
Allowed values: DESCENDING ASCENDING
sort_by
sort by

Optional: default is sort by last_event_time.

string
<= 1024 characters
start_time
start time

Fetch security events whose timestamp >= start_time 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
search_after
search after

Search After is used to retrieve large number of log messages (or all log messages) that matches the query. If search_after is set to true, the sort_values in the response can be used in the API to fetch the next batch of logs. The number of messages in each batch is determined by the limit field. Note: Search After is used for processing large amount of data and therefore is not intended for real time user request. Optional: default is false.

boolean format: boolean
sort_values
object
last_doc_id
last_doc_id

This is a unique UUID generated by elastic search.

string
<= 1024 characters
last_timestamp
last timestamp

Configuration parameter for last timestamp

number format: double

Responses

Section titled “Responses”

200

Section titled “200”

A successful response.

Media typeapplication/json
Security Events Response

Response message for SecurityEventsRequest/SecurityEventsScrollRequest.

object
aggs
aggregations

Aggregations provide summary/analytics data over the security events response. If the number of security events that matched the query is large and cannot be returned in a single response message, user can GET helpful insights/summary using aggregations.

object
events
events

List of security events that matched the query. Contains no more than 500 messages.

Array<string>
scroll_id
scroll id

Long Base-64 encoded string which can be used to retrieve the next batch of security events using the scroll request. Empty scroll_id indicates no more messages to scroll (EOF). Note: scroll_id is valid only for 2 minutes. I.e., If one intend to retrieve next batch of the result, then the scroll request should be sent within 2 minutes upon receiving the SecurityEventsResponse.

string
<= 1024 characters
total_hits
total hits

Total number of security events that matched the query.

string format: uint64
<= 1024 characters
last_sort_values
object
last_doc_id
last_doc_id

This is a unique UUID generated by elastic search.

string
<= 1024 characters
last_timestamp
last timestamp

Configuration parameter for last timestamp

number format: double
Examplegenerated
{
  "aggs": {},
  "events": [
    "example"
  ],
  "scroll_id": "example",
  "total_hits": "example",
  "last_sort_values": {
    "last_doc_id": "example",
    "last_timestamp": 1
  }
}

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