OpenAPI Specification
openapi: 3.0.2
info:
version: 1.0.0
title: Vectra Detect Accounts Hosts API
contact:
name: Vectra TME
email: tme@vectra.ai
description: Vectra Detect on-prem instance API
license:
name: TME Custom °-.-°
url: https://vectra.ai
servers:
- url: https://{fqdn}/api/{apiVersion}
description: Vectra Detect API
variables:
fqdn:
description: The FQDN or IP to join the Vectra Detect instance
default: detect-api.demo.vectra.io
apiVersion:
description: The API version to use
default: v2.3
security:
- VectraToken: []
tags:
- name: Hosts
description: Dedicated endpoint to Hosts.
paths:
/hosts:
description: Hosts objects.
get:
operationId: hostGetSeveral
summary: Get several Hosts
tags:
- Hosts
parameters:
- $ref: '#/components/parameters/pageNumber'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/ordering'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/oneOfTags'
- $ref: '#/components/parameters/certaintyScore'
- $ref: '#/components/parameters/certaintyScoreGte'
- $ref: '#/components/parameters/maxID'
- $ref: '#/components/parameters/minID'
- $ref: '#/components/parameters/name'
- $ref: '#/components/parameters/noteModifiedTimestampGte'
- $ref: '#/components/parameters/privilegeCategory'
- $ref: '#/components/parameters/privilegeLevel'
- $ref: '#/components/parameters/privilegeLevelGte'
- $ref: '#/components/parameters/threatScore'
- $ref: '#/components/parameters/threatScoreGte'
- name: fields
description: Filters returned attributes
in: query
schema:
$ref: '#/components/schemas/queryHostFields'
style: form
explode: false
- name: last_source
description: Filters by last source (IP address)
in: query
schema:
$ref: '#/components/schemas/IP'
- name: last_detection_timestamp
description: Filters by the last seen detection timestamp (should be exactly the same)
in: query
schema:
type: string
- name: all
description: No filter, returns all host objects
in: query
schema:
type: boolean
allowEmptyValue: true
deprecated: true
- name: key_asset
description: Filters key asset
in: query
schema:
type: boolean
- name: target_key_asset
description: Filters Hosts targeting key assets
in: query
schema:
type: boolean
- name: active_traffic
description: Filters Hosts that have generated active traffic within the last 2 hours
in: query
schema:
type: boolean
- name: mac_address
description: Fitlers Hosts having the given MAC Address
in: query
schema:
$ref: '#/components/schemas/macAddress'
responses:
'200':
description: Retrieved Hosts successfully
content:
application/json:
schema:
$ref: '#/components/schemas/resultsOfHosts'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/hosts/{hostID}:
parameters:
- name: hostID
description: ID of the Host you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: hostGetSingle
summary: Describe a specific Host
tags:
- Hosts
parameters:
- name: fields
description: Filters returned attributes
in: query
schema:
$ref: '#/components/schemas/queryHostFields'
style: form
explode: false
responses:
'200':
description: Describe a specific Host
content:
application/json:
schema:
$ref: '#/components/schemas/host'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
'404':
$ref: '#/components/responses/notFound'
/hosts/{hostID}/notes:
parameters:
- name: hostID
description: ID of the Host notes you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: hostNotesGetSeveral
summary: Get all Host notes
tags:
- Hosts
responses:
'200':
description: Retrieved Host notes successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/note'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
post:
operationId: hostNoteCreate
summary: Create a new Host note
tags:
- Hosts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/noteRequestBody'
responses:
'200':
description: Host note created
content:
application/json:
schema:
$ref: '#/components/schemas/note'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/hosts/{hostID}/notes/{noteID}:
parameters:
- name: hostID
description: ID of the Host you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
- name: noteID
description: ID of the Note you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: hostNoteGetSingle
summary: Get a single Host note
tags:
- Hosts
responses:
'200':
description: Retrieved Host note successfully
content:
application/json:
schema:
$ref: '#/components/schemas/note'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
patch:
operationId: hostNoteUpdate
summary: Update an existing Host note
tags:
- Hosts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/noteRequestBody'
responses:
'200':
description: Host note updated
content:
application/json:
schema:
$ref: '#/components/schemas/note'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
delete:
operationId: hostNoteDelete
summary: Delete an existing Host note
tags:
- Hosts
responses:
'200':
description: Host note deleted
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/search/hosts:
description: Search for hosts objects.
get:
operationId: searchHosts
summary: Search for Hosts
tags:
- Hosts
parameters:
- $ref: '#/components/parameters/pageNumber'
- $ref: '#/components/parameters/pageSize'
- name: query_string
description: The Lucene search query
in: query
schema:
type: string
responses:
'200':
description: Retrieved Hosts successfully
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/tagging/host/{hostID}:
description: The tagging endpoint can be used to manage Host tags
parameters:
- name: hostID
description: ID of the Host you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: hostTagsGetAll
summary: Get all Host's tags
tags:
- Hosts
responses:
'200':
description: Retrieved tags successfully
content:
application/json:
schema:
$ref: '#/components/schemas/tags'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
patch:
operationId: hostTagsReplace
summary: Replace all Host's tags
tags:
- Hosts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/tagsRequestBody'
responses:
'200':
description: Replaced tags successfully
content:
application/json:
schema:
$ref: '#/components/schemas/tags'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/hosts/{host_id}:
get:
summary: Retrieve single host details
operationId: getHostById
tags:
- Hosts
parameters:
- name: host_id
in: path
required: true
schema:
type: integer
description: Unique ID for the host
responses:
'200':
description: Host details
content:
application/json:
schema:
$ref: '#/components/schemas/Host'
components:
schemas:
assignmentOutcome:
description: Label resolution outcome for an assignment
type: object
properties:
id:
$ref: '#/components/schemas/ID'
builtin:
type: boolean
user_selectable:
type: boolean
title:
type: string
category:
$ref: '#/components/schemas/assignmentOutcomeCategory'
required:
- id
- builtin
- user_selectable
- title
- category
Host:
type: object
properties:
id:
type: integer
name:
type: string
state:
type: string
threat:
type: integer
certainty:
type: integer
ip:
type: string
last_detection_timestamp:
type: string
format: date-time
assignmentHistorycalEvent:
description: Assignment history event
type: object
properties:
assignment_id:
$ref: '#/components/schemas/ID'
actor:
$ref: '#/components/schemas/ID'
event_type:
$ref: '#/components/schemas/assignmentEventType'
datetime:
$ref: '#/components/schemas/isoDate'
context:
type: object
properties:
from:
$ref: '#/components/schemas/ID'
to:
$ref: '#/components/schemas/ID'
entity_c_score:
$ref: '#/components/schemas/vectraScore'
entity_t_score:
$ref: '#/components/schemas/vectraScore'
triage_as:
type: string
nullable: true
triaged_detection_ids:
oneOf:
- $ref: '#/components/schemas/arrayOfIDs'
- type: string
nullable: true
fixed_detection_ids:
oneOf:
- $ref: '#/components/schemas/arrayOfIDs'
- type: string
nullable: true
created_rule_ids:
oneOf:
- $ref: '#/components/schemas/arrayOfIDs'
- type: string
nullable: true
assignmentUser:
description: Assignment user (tiny Vectra User)
type: object
properties:
id:
$ref: '#/components/schemas/ID'
username:
$ref: '#/components/schemas/name'
example:
id: 123
username: SAML:dummy@company.com
IP:
description: IP Address
type: string
example: 192.168.1.55
macAddress:
type: string
groupType:
type: string
enum:
- ip
- host
link:
description: URL Link
type: string
nullable: true
format: uri
example: https://dummy.link
positiveInt:
type: integer
format: int32
minimum: 0
isoDate:
description: ISO representation of a date
type: string
format: date-time
example: '2022-01-01T00:00:00Z'
name:
type: string
minLength: 1
severity:
description: Severity
type: string
enum:
- low
- Low
- medium
- Medium
- high
- High
- critical
- Critical
example: medium
assignment:
description: Assignment
type: object
properties:
id:
$ref: '#/components/schemas/ID'
assigned_by:
$ref: '#/components/schemas/assignmentUser'
date_assigned:
$ref: '#/components/schemas/isoDate'
date_resolved:
oneOf:
- $ref: '#/components/schemas/isoDate'
- type: number
nullable: true
events:
type: array
items:
$ref: '#/components/schemas/assignmentHistorycalEvent'
outcome:
oneOf:
- $ref: '#/components/schemas/assignmentOutcome'
- type: string
nullable: true
resolved_by:
oneOf:
- $ref: '#/components/schemas/assignmentUser'
- type: string
nullable: true
triaged_detections:
type: array
nullable: true
items:
$ref: '#/components/schemas/ID'
host_id:
oneOf:
- $ref: '#/components/schemas/ID'
- type: string
nullable: true
account_id:
oneOf:
- $ref: '#/components/schemas/ID'
- type: string
nullable: true
assigned_to:
$ref: '#/components/schemas/assignmentUser'
required:
- id
- assigned_by
- date_assigned
- assigned_to
arrayOfIDs:
description: Array of IDs
type: array
items:
$ref: '#/components/schemas/ID'
host:
description: Host
type: object
properties:
id:
$ref: '#/components/schemas/ID'
name:
$ref: '#/components/schemas/name'
active_traffic:
type: boolean
has_active_traffic:
type: boolean
deprecated: true
threat:
$ref: '#/components/schemas/vectraScore'
t_score:
$ref: '#/components/schemas/vectraScore'
deprecated: true
certainty:
$ref: '#/components/schemas/vectraScore'
c_score:
$ref: '#/components/schemas/vectraScore'
deprecated: true
severity:
$ref: '#/components/schemas/severity'
last_source:
$ref: '#/components/schemas/IP'
ip:
$ref: '#/components/schemas/IP'
previous_ips:
type: array
items:
- $ref: '#/components/schemas/IP'
last_detection_timestamp:
$ref: '#/components/schemas/isoDate'
key_asset:
type: boolean
deprecated: true
is_key_asset:
type: boolean
state:
$ref: '#/components/schemas/state'
targets_key_asset:
type: boolean
deprecated: true
is_targeting_key_asset:
type: boolean
detection_set:
$ref: '#/components/schemas/arrayOfLinks'
host_artifact_set:
type: array
items:
- type: object
properties:
type:
type: string
value:
type: string
source:
type: string
siem:
type: boolean
sensor:
$ref: '#/components/schemas/name'
sensor_name:
$ref: '#/components/schemas/name'
tags:
$ref: '#/components/schemas/arrayOfNames'
note:
oneOf:
- $ref: '#/components/schemas/text'
- type: string
nullable: true
note_modified_by:
oneOf:
- $ref: '#/components/schemas/name'
- type: string
nullable: true
note_modified_timestamp:
oneOf:
- $ref: '#/components/schemas/isoDate'
- type: string
nullable: true
notes:
type: array
items:
$ref: '#/components/schemas/note'
url:
$ref: '#/components/schemas/link'
host_url:
$ref: '#/components/schemas/link'
last_modified:
oneOf:
- $ref: '#/components/schemas/isoDate'
- type: string
nullable: true
assigned_to:
oneOf:
- $ref: '#/components/schemas/name'
- type: string
nullable: true
assigned_date:
oneOf:
- $ref: '#/components/schemas/isoDate'
- type: string
nullable: true
groups:
type: array
items:
- type: object
properties:
id:
$ref: '#/components/schemas/ID'
name:
$ref: '#/components/schemas/name'
description:
$ref: '#/components/schemas/text'
last_modified:
$ref: '#/components/schemas/isoDate'
last_modified_by:
$ref: '#/components/schemas/name'
type:
$ref: '#/components/schemas/groupType'
has_custom_model:
type: boolean
privilege_level:
$ref: '#/components/schemas/privilegeLevel'
privilege_category:
$ref: '#/components/schemas/privilegeCategory'
probable_owner:
oneOf:
- $ref: '#/components/schemas/name'
- type: string
nullable: true
detection_profile:
$ref: '#/components/schemas/text'
assignment:
oneOf:
- $ref: '#/components/schemas/assignment'
- type: string
nullable: true
past_assignments:
type: array
items:
$ref: '#/components/schemas/assignment'
host_session_luids:
$ref: '#/components/schemas/arrayOfNames'
host_luid:
$ref: '#/components/schemas/name'
arrayOfLinks:
description: Array of links
type: array
items:
$ref: '#/components/schemas/link'
queryHostFields:
type: array
items:
type: string
enum:
- id
- name
- active_traffic
- has_active_traffic
- t_score
- threat
- c_score
- certainty
- severity
- last_source
- ip
- previous_ips
- last_detection_timestamp
- key_asset
- is_key_asset
- state
- targets_key_asset
- is_targeting_key_asset
- detection_set
- host_artifact_set
- sensor
- sensor_name
- tags
- note
- notes
- note_modified_by
- note_modified_timestamp
- url
- host_url
- last_modified
- assigned_to
- assigned_date
- groups
- has_custom_model
- privilege_level
- privilege_category
- probable_owner
- detection_profile
- assignment
- past_assignments
- detection_summaries
- host_session_luids
- host_luid
text:
type: string
resultsOfHosts:
allOf:
- $ref: '#/components/schemas/results'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/host'
tags:
type: object
properties:
status:
type: string
tag_id:
$ref: '#/components/schemas/ID'
tags:
type: array
items:
- $ref: '#/components/schemas/text'
error:
type: object
properties:
detail:
description: A human readable error message
type: string
details:
description: A human readable error message
type: string
state:
type: string
enum:
- active
- inactive
example: active
ID:
description: ID
type: integer
format: int32
minimum: 1
arrayOfNames:
description: Array of names
type: array
items:
$ref: '#/components/schemas/name'
vectraScore:
type: number
minimum: 0
maximum: 99
example: 80
tagsRequestBody:
type: object
properties:
tags:
type: array
items:
- $ref: '#/components/schemas/text'
required:
- tags
results:
type: object
properties:
count:
$ref: '#/components/schemas/positiveInt'
next:
$ref: '#/components/schemas/link'
previous:
$ref: '#/components/schemas/link'
note:
type: object
properties:
id:
$ref: '#/components/schemas/ID'
date_created:
oneOf:
- $ref: '#/components/schemas/isoDate'
- type: string
nullable: true
date_modified:
oneOf:
- $ref: '#/components/schemas/isoDate'
- type: string
nullable: true
created_by:
$ref: '#/components/schemas/name'
modified_by:
oneOf:
- $ref: '#/components/schemas/name'
- type: string
nullable: true
note:
$ref: '#/components/schemas/text'
privilegeLevel:
type: number
nullable: true
minimum: 1
maximum: 10
example: 8
assignmentEventType:
description: Type of event that can happen to an assignment
type: string
enum:
- created
- reassigned
- resolved
example: created
assignmentOutcomeCategory:
title: Assignment Outcome allowed categories
type: string
enum:
- benign_true_positive
- malicious_true_positive
- false_positive
noteRequestBody:
type: object
properties:
note:
$ref: '#/components/schemas/text'
required:
- note
privilegeCategory:
type: string
nullable: true
enum:
- null
- low
- Low
- medium
- Medium
- high
- High
example: Medium
parameters:
state:
name: state
description: Filters by state
in: query
schema:
$ref: '#/components/schemas/state'
threatScoreGte:
name: t_score_gte
description: Filters by threat score greater than or equals the provided score
in: query
schema:
$ref: '#/components/schemas/vectraScore'
privilegeCategory:
name: privilege_category
description: Filters by privilege category
in: query
schema:
$ref: '#/components/schemas/privilegeCategory'
oneOfTags:
name: tags
description: Filters by tags. Returns entries that contain any of the tags specified
in: query
schema:
$ref: '#/components/schemas/arrayOfNames'
certaintyScore:
name: c_score
description: Filters by certainty score
in: query
schema:
$ref: '#/components/schemas/vectraScore'
pageNumber:
name: page
description: The page result to look at
in: query
schema:
type: integer
format: int32
minimum: 1
example: 1
privilegeLevel:
name: privilege_level
description: Filters by exact privilege level
in: query
schema:
$ref: '#/components/schemas/privilegeLevel'
name:
name: name
description: Filters by name
in: query
schema:
$ref: '#/components/schemas/name'
certaintyScoreGte:
name: c_score_gte
description: Filters by certainty score greater than or equals the provided score
in: query
schema:
$ref: '#/components/schemas/vectraScore'
threatScore:
name: t_score
description: Filters by threat score
in: query
schema:
$ref: '#/components/schemas/vectraScore'
minID:
name: min_id
description: Filters by ID greater than or equals the provided ID
in: query
schema:
$ref: '#/components/schemas/ID'
pageSize:
name: page_size
description: The number of results to return per page
in: query
schema:
type: integer
minimum: 1
maximum: 5000
example: 50
noteModifiedTimestampGte:
name: note_modified_timestamp_gte
description: Filters on detection'notes modified timestamp
in: query
schema:
$ref: '#/components/schemas/isoDate'
privilegeLevelGte:
name: privilege_level_gte
description: Filters Account having a privilege level greater than or equal to the supplied number
in: query
schema:
$ref: '#/components/schemas/privilegeLevel'
maxID:
name: max_id
description: Filters by ID lower than or equals the provided ID
in: query
schema:
$ref: '#/components/schemas/ID'
ordering:
name: ordering
description: Orders results based on given attribute. Results can be sorted in descending order by prepending the query with “minus” symbol.
in: query
schema:
type: string
responses:
invalidToken:
description: Invalid User Token
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
details: Invalid token.
invalidPermissions:
description: Invalid User Permissions
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
details: You do not have permission to perform this action.
notFound:
description: Object not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
detail: Not Found.
securitySchemes:
VectraToken:
type: apiKey
name: authorization
in: header