VAST Rest API ("0.1")
Download OpenAPI specification:Download
This API can be used to interact with a VAST Node in a RESTful manner.
All API requests must be authenticated with a valid token, which must be
supplied in the X-VAST-Token
request header. The token can be generated
on the command-line using the vast rest generate-token
command.
Update pipeline state
Update the state of the pipeline. All values that are not explicitly included in the request are left in their old state.
Authorizations:
Request Body schema: application/json
Body for the update endpoint
id required | string The id of the pipeline to be updated. |
state | string Enum: "starting" "running" "stopping" "stopped" |
name | string Update the human-readable name of the pipeline to this value. |
restart_with_node | boolean Check if the pipeline should be restarted when the VAST Node is restarted. |
Responses
Request samples
- Payload
{- "id": 7,
- "state": "running",
- "name": "zeek-monitoring-pipeline",
- "restart_with_node": true
}
Response samples
- 200
- 400
{ }
Create a new pipeline
Creates a new pipeline.
Authorizations:
Request Body schema: application/json
Body for the create endpoint
definition required | string The pipeline definition. |
autostart | boolean Default: true |
name | string Default: "[an auto-generated id]" The human-readable name of the pipeline. |
restart_with_node | boolean Default: false Check if the pipeline should be restarted when the VAST Node is restarted. |
Responses
Request samples
- Payload
{- "definition": "export | where foo | publish /bar",
- "autostart": true,
- "name": "zeek-monitoring-pipeline",
- "restart_with_node": false
}
Response samples
- 200
- 400
{- "id": "string"
}
Delete an existing pipeline
Deletes an existing pipeline.
Authorizations:
Request Body schema: application/json
Body for the delete endpoint
id required | string The id of the pipeline to be deleted. |
Responses
Request samples
- Payload
{- "id": 7
}
Response samples
- 200
- 400
{ }
Response samples
- 200
- 400
{- "pipelines": [
- {
- "id": 7,
- "name": "user-assigned-name",
- "definition": "export | where foo | publish /bar",
- "state": "starting",
- "error": null,
- "operators": [
- {
- "id": 0,
- "definition": "export",
- "instrumented": false
}, - {
- "id": 1,
- "definition": "where foo",
- "instrumented": true
}, - {
- "id": 2,
- "definition": "publish /bar",
- "instrumented": true
}
]
}, - {
- "id": 8,
- "name": "wrong-pipeline",
- "definition": "export asdf",
- "state": "stopped",
- "error": "format 'asdf' not found",
- "operators": [
- {
- "id": 0,
- "definition": "export asdf",
- "instrumented": false
}
]
}
]
}
Return data from a pipeline
Returns events from an existing pipeline. The pipeline definition must include a serve operator.
Authorizations:
Request Body schema: application/json
Body for the serve endpoint
serve_id required | string The id that was passed to the serve operator. |
continuation_token | string The continuation token that was returned with the last response. For the initial request this is null. |
max_events | integer The maximum number of events returned. If unset, the number is unlimited |
timeout | string Default: "100.0ms" The maximum amount of time spent on the request. Hitting the timeout is not an error. |
Responses
Request samples
- Payload
{- "serve_id": "query1",
- "continuation_token": "340ce2j",
- "max_events": 50,
- "timeout": "100.0ms"
}
Response samples
- 200
- 400
{- "next_continuation_token": "340ce2j",
- "schemas": [
- {
- "schema_id": "c631d301e4b18f4",
- "definition": {
- "record": [
- {
- "timestamp": "time",
- "schema": "string",
- "schema_id": "string",
- "events": "uint64"
}
]
}
}
], - "data": [
- {
- "schema_id": "c631d301e4b18f4",
- "data": {
- "timestamp": "2023-04-26T12:00:00.000000",
- "schema": "zeek.conn",
- "schema_id": "ab2371bas235f1",
- "events": 50
}
}, - {
- "schema_id": "c631d301e4b18f4",
- "data": {
- "timestamp": "2023-04-26T12:05:00.000000",
- "schema": "suricata.dns",
- "schema_id": "cd4771bas235f1",
- "events": 50
}
}
]
}
Create new query
Create a new export query in VAST
Authorizations:
query Parameters
query required | string Example: query=where :ip in 10.42.0.0/16 | head 100 The query used in the form of a pipeline. |
ttl | string Example: ttl=5.0m The time after which a query is cancelled. Use the /query/:id/next endpoint to refresh the TTL. To refresh the TTL without requesting further events, request zero events. |
expand | boolean Whether to use the expanded output schema. |
flatten | boolean Default: false Flatten nested elements in the response data. |
omit-nulls | boolean Default: false Omit null elements in the response data. |
numeric-durations | boolean Default: false Render durations as numeric values. |
Responses
Response samples
- 200
{- "id": "c91019bf-21fe-4999-8323-4d28aeb111ab"
}
Get additional query results
Return n
additional results from the specified query.
Authorizations:
path Parameters
id required | string Example: e84308a2-1ba4-4559-9e0f-597dfea4fd3e The query ID. |
query Parameters
n | integer Example: n=10 Maximum number of returned events |
Responses
Response samples
- 200
{- "events": [
- {
- "schema-ref": "foobarbaz",
- "data": {
- "ts": "2009-11-18T22:11:04.011822",
- "uid": "iKxhjl8i1n3",
- "id": {
- "orig_h": "192.168.1.103"
}
}
}, - {
- "schema-ref": "foobarbaz",
- "data": {
- "ts": "2009-11-18T22:11:04.011822",
- "uid": "iKxhjl8i1n3",
- "id": {
- "orig_h": "192.168.1.103"
}
}
}
], - "schemas": [
- {
- "schema-ref": "foobarbaz",
- "definition": "<type-definition>"
}
]
}
Return current status
Returns the current status of the whole node.
Authorizations:
query Parameters
component | string Example: component=index If specified, return the status for that component only. |
verbosity | string Default: "info" Enum: "info" "detailed" "debug" Example: verbosity=detailed The verbosity level of the status response. |
Responses
Response samples
- 200
{- "catalog": {
- "num-partitions": 7092,
- "memory-usage": 52781901584
}, - "version": {
- "VAST": "v2.3.0-rc3-32-g8529a6c43f"
}
}