OpenAPI Specification
openapi: 3.0.2
info:
version: 1.0.0
title: Vectra Detect Accounts Detections 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: Detections
description: Dedicated endpoint to Detections.
paths:
/detections:
description: Detection objects contain all the information related to security events detected on the network.
get:
operationId: detectionGetSeveral
summary: Get all detections
tags:
- Detections
parameters:
- $ref: '#/components/parameters/pageNumber'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/ordering'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/oneOfTags'
- $ref: '#/components/parameters/certainty'
- $ref: '#/components/parameters/certaintyGte'
- $ref: '#/components/parameters/certaintyScore'
- $ref: '#/components/parameters/certaintyScoreGte'
- $ref: '#/components/parameters/maxID'
- $ref: '#/components/parameters/minID'
- $ref: '#/components/parameters/noteModifiedTimestampGte'
- $ref: '#/components/parameters/threat'
- $ref: '#/components/parameters/threatGte'
- $ref: '#/components/parameters/threatScore'
- $ref: '#/components/parameters/threatScoreGte'
- name: fields
description: Filters returned attributes
in: query
schema:
$ref: '#/components/schemas/queryDetectionFields'
style: form
explode: false
- name: category
description: Filters by detection category
in: query
schema:
$ref: '#/components/schemas/queryDetectionCategory'
- name: detection_category
description: Filters by detection category
in: query
schema:
$ref: '#/components/schemas/queryDetectionCategory'
- name: detection_type
description: Filters by the name of the detected threat
in: query
schema:
type: string
- name: src_ip
description: Filters by source (IP address)
in: query
schema:
$ref: '#/components/schemas/IP'
- name: last_timestamp
in: query
schema:
type: string
- name: last_timestamp_gte
in: query
schema:
type: string
- name: host_id
description: Filters by the ID of the host object the detection is attributed to
in: query
schema:
$ref: '#/components/schemas/ID'
- name: destination
description: Filters by the destination in the detection details set
in: query
schema:
type: string
- name: proto
description: Filters by the protocol in the detection details set
in: query
schema:
type: string
- name: is_targeting_key_asset
description: Filters on detections targeting key assets
in: query
schema:
type: boolean
responses:
'200':
description: Retrieved detections successfully
content:
application/json:
schema:
$ref: '#/components/schemas/resultsOfDetections'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
patch:
operationId: detectionMarkSeveral
summary: Mark/Unmark several Detections as fixed
tags:
- Detections
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/detectionMarkRequestBody'
responses:
'200':
description: Mark/Unmark as fixed several detections successfully
content:
application/json:
schema:
type: object
properties:
_meta:
type: object
properties:
level:
type: string
example: Success
message:
type: string
example: Successfully marked detections
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/detections/{detectionID}:
parameters:
- name: detectionID
description: ID of the Detection you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: detectionGetSingle
summary: Describe a specific detection
tags:
- Detections
parameters:
- name: fields
description: Filters returned attributes
in: query
schema:
$ref: '#/components/schemas/queryDetectionFields'
style: form
explode: false
responses:
'200':
description: Describe a specific Detection
content:
application/json:
schema:
$ref: '#/components/schemas/detection'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
'404':
$ref: '#/components/responses/notFound'
/detections/{detectionID}/notes:
parameters:
- name: detectionID
description: ID of the Detection notes you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: detectionNotesGetSeveral
summary: Get all Detection notes
tags:
- Detections
responses:
'200':
description: Retrieved Detection 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: detectionNoteCreate
summary: Create a new Detection note
tags:
- Detections
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/noteRequestBody'
responses:
'200':
description: Detection note created
content:
application/json:
schema:
$ref: '#/components/schemas/note'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/detections/{detectionID}/notes/{noteID}:
parameters:
- name: detectionID
description: ID of the Detection 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: detectionNoteGetSingle
summary: Get a single Detection note
tags:
- Detections
responses:
'200':
description: Retrieved Detection note successfully
content:
application/json:
schema:
$ref: '#/components/schemas/note'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
patch:
operationId: detectionNoteUpdate
summary: Update an existing Detection note
tags:
- Detections
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/noteRequestBody'
responses:
'200':
description: Detection note updated
content:
application/json:
schema:
$ref: '#/components/schemas/note'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
delete:
operationId: detectionNoteDelete
summary: Delete an existing Detection note
tags:
- Detections
responses:
'200':
description: Detection note deleted
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/detections/{detectionID}/pcap:
parameters:
- name: detectionID
description: ID of the Detection you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: detectionDownloadPCAP
summary: Download a Detection PCAP
tags:
- Detections
responses:
'200':
description: Detection PCAP retrieved
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/search/detections:
description: Search for detections objects.
get:
operationId: searchDetections
summary: Search for Detections
tags:
- Detections
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/detection/{detectionID}:
description: The tagging endpoint can be used to manage Detection tags
parameters:
- name: detectionID
description: ID of the Detection you're looking for
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: detectionTagsGetAll
summary: Get all Detection's tags
tags:
- Detections
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: detectionTagsReplace
summary: Replace all Detection's tags
tags:
- Detections
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'
/detections/{detection_id}:
get:
summary: Retrieve a single detection event
operationId: getDetectionById
tags:
- Detections
parameters:
- name: detection_id
in: path
required: true
schema:
type: integer
description: Unique ID for the detection
responses:
'200':
description: Detection event details
content:
application/json:
schema:
$ref: '#/components/schemas/Detection'
patch:
summary: Mark detection as fixed
operationId: markDetectionAsFixed
tags:
- Detections
parameters:
- name: detection_id
in: path
required: true
schema:
type: integer
description: Unique ID for the detection
requestBody:
content:
application/json:
schema:
type: object
properties:
detectionIdList:
type: array
items:
type: integer
description: List of detection IDs to mark as fixed
mark_as_fixed:
type: boolean
description: Boolean to mark detection as fixed
responses:
'204':
description: Detection marked as fixed successfully
/detections/{id}/pcap:
get:
summary: Download PCAP data for detection
operationId: getPCAP
tags:
- Detections
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: PCAP file
content:
application/vnd.tcpdump.pcap:
schema:
type: string
format: binary
/detections/{id}/notes:
get:
summary: Get detection notes
tags:
- Detections
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: List of notes
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Note'
post:
summary: Add note to detection
tags:
- Detections
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
responses:
'200':
description: Created note
content:
application/json:
schema:
$ref: '#/components/schemas/Note'
components:
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'
certaintyGte:
name: certainty_gte
description: Filters by certainty score greater than or equals the provided score
in: query
schema:
$ref: '#/components/schemas/vectraScore'
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
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'
threatGte:
name: threat_gte
description: Filters by threat score greater than or equals the provided score
in: query
schema:
$ref: '#/components/schemas/vectraScore'
threat:
name: threat
description: Filters by threat score
in: query
schema:
$ref: '#/components/schemas/vectraScore'
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'
certainty:
name: certainty
description: Filters by certainty score
in: query
schema:
$ref: '#/components/schemas/vectraScore'
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
schemas:
queryDetectionCategory:
type: string
enum:
- command
- botnet
- reconnaissance
- lateral
- exfiltration
- info
example: command
IP:
description: IP Address
type: string
example: 192.168.1.55
Detection:
type: object
properties:
id:
type: integer
detection:
type: string
category:
type: string
src_ip:
type: string
state:
type: string
threat:
type: integer
certainty:
type: integer
first_timestamp:
type: string
format: date-time
last_timestamp:
type: string
format: date-time
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
queryDetectionFields:
type: array
items:
type: string
enum:
- id
- url
- detection_url
- category
- detection
- detection_category
- detection_type
- customer_detection
- description
- src_ip
- state
- t_score
- threat
- c_score
- certainty
- created_timestamp
- first_timestamp
- last_timestamp
- targets_key_asset
- is_targeting_key_asset
- src_account
- src_host
- note
- notes
- note_modified_by
- note_modified_timestamp
- sensor
- sensor_name
- tags
- triage_rule_id
- assigned_to
- assigned_date
- groups
- is_marked_custom
- is_custom_model
- grouped_details
- summary
booleanString:
type: string
enum:
- 'true'
- 'false'
isoDate:
description: ISO representation of a date
type: string
format: date-time
example: '2022-01-01T00:00:00Z'
name:
type: string
minLength: 1
arrayOfIDs:
description: Array of IDs
type: array
items:
$ref: '#/components/schemas/ID'
Note:
type: object
properties:
id:
type: integer
created_by:
type: string
modified_by:
type: string
note:
type: string
date_created:
type: string
format: date-time
date_modified:
type: string
format: date-time
detectionCategory:
type: string
enum:
- COMMAND & CONTROL
- botnet
- reconnaissance
- lateral
- exfiltration
- INFO
example: INFO
detectionType:
type: string
enum:
- Hidden HTTP Tunnel
text:
type: string
state:
type: string
enum:
- active
- inactive
example: active
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
resultsOfDetections:
allOf:
- $ref: '#/components/schemas/results'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/detection'
ID:
description: ID
type: integer
format: int32
minimum: 1
detectionMarkRequestBody:
type: object
properties:
detectionIdList:
$ref: '#/components/schemas/arrayOfIDs'
mark_as_fixed:
$ref: '#/components/schemas/booleanString'
required:
- detectionIdList
- mark_as_fixed
arrayOfNames:
description: Array of names
type: array
items:
$ref: '#/components/schemas/name'
vectraScore:
type: number
minimum: 0
maximum: 99
example: 80
port:
type: integer
format: int32
minimum: 0
maximum: 65535
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'
detection:
type: object
properties:
id:
$ref: '#/components/schemas/ID'
url:
$ref: '#/components/schemas/link'
detection_url:
$ref: '#/components/schemas/link'
category:
$ref: '#/components/schemas/detectionCategory'
detection_category:
$ref: '#/components/schemas/detectionCategory'
detection:
$ref: '#/components/schemas/detectionType'
detection_type:
$ref: '#/components/schemas/detectionType'
custom_detection:
oneOf:
- $ref: '#/components/schemas/name'
- type: string
nullable: true
description:
oneOf:
- $ref: '#/components/schemas/text'
- type: string
nullable: true
src_ip:
$ref: '#/components/schemas/IP'
state:
$ref: '#/components/schemas/state'
t_score:
$ref: '#/components/schemas/vectraScore'
threat:
$ref: '#/components/schemas/vectraScore'
c_score:
$ref: '#/components/schemas/vectraScore'
certainty:
$ref: '#/components/schemas/vectraScore'
created_timestamp:
$ref: '#/components/schemas/isoDate'
first_timestamp:
$ref: '#/components/schemas/isoDate'
last_timestamp:
$ref: '#/components/schemas/isoDate'
targets_key_asset:
type: boolean
is_targeting_key_asset:
type: boolean
src_account:
type: object
src_host:
oneOf:
- type: object
properties:
id:
$ref: '#/components/schemas/ID'
ip:
$ref: '#/components/schemas/IP'
name:
$ref: '#/components/schemas/name'
url:
$ref: '#/components/schemas/link'
is_key_asset:
type: boolean
threat:
$ref: '#/components/schemas/vectraScore'
certainty:
$ref: '#/components/schemas/vectraScore'
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'
- type: string
nullable: true
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'
sensor:
$ref: '#/components/schemas/vectraScore'
sensor_name:
$ref: '#/components/schemas/vectraScore'
tags:
$ref: '#/components/schemas/arrayOfNames'
triage_rule_id:
oneOf:
- $ref: '#/components/schemas/positiveInt'
- 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'
is_marked_custom:
type: boolean
is_custom_model:
type: boolean
filtered_by_ai:
type: boolean
filtered_by_user:
type: boolean
filtered_by_rule:
type: boolean
grouped_details:
type: array
items:
- type: object
summary:
oneOf:
- type: object
properties:
uuids:
type: array
items:
- $ref: '#/components/schemas/name'
num_attempts:
$ref: '#/components/schemas/positiveInt'
- type: object
properties:
dst_ips:
type: array
items:
- $ref: '#/components/schemas/IP'
num_sessions:
$ref: '#/components/schemas/positiveInt'
bytes_sent:
$ref: '#/components/schemas/positiveInt'
bytes_received:
$ref: '#/components/schemas/positiveInt'
description:
$ref: '#/components/schemas/text'
- type: object
properties:
custom_model_query:
$ref: '#/components/schemas/text'
bytes_sent:
$ref: '#/components/schemas/positiveInt'
bytes_received:
$ref: '#/components/schemas/positiveInt'
matches:
$ref: '#/components/schemas/positiveInt'
first_matched:
$ref: '#/components/schemas/isoDate'
last_matched:
$ref: '#/components/schemas/isoDate'
description:
$ref: '#/components/schemas/text'
- type: object
properties:
dst_ips:
type: array
items:
- $ref: '#/components/schemas/IP'
dst_ports:
type: array
items:
- $ref: '#/components/schemas/port'
protocols:
type: array
items:
- $ref: '#/components/schemas/name'
bytes_sent:
$ref: '#/components/schemas/positiveInt'
- type: object
noteRequestBody:
type: object
properties:
note:
$ref: '#/components/schemas/text'
required:
- note
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