OpenAPI Specification
openapi: 3.0.2
info:
version: 1.0.0
title: Vectra Detect Accounts Assignments 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: Assignments
description: Dedicated endpoint to Assignments.
paths:
/assignments:
description: Assignments are used to assign account or host entities to analysts for investigation.
get:
operationId: assignmentGetSeveral
summary: Get all assignments
tags:
- Assignments
parameters:
- name: accounts
description: Filter by Accounts (list of Account IDs)
in: query
schema:
$ref: '#/components/schemas/arrayOfIDs'
style: form
explode: false
- name: assignees
description: Filter by Assignees (list of User IDs)
in: query
schema:
$ref: '#/components/schemas/arrayOfIDs'
style: form
explode: false
- name: created_after
description: Filter by creation timestamp (ISO Timestamp)
in: query
schema:
$ref: '#/components/schemas/isoDate'
- name: hosts
description: Filter by Hosts (list of Host IDs)
in: query
schema:
$ref: '#/components/schemas/arrayOfIDs'
style: form
explode: false
- name: resolution
description: Filter by Outcomes (list of Assignment outcome IDs)
in: query
schema:
$ref: '#/components/schemas/arrayOfIDs'
style: form
explode: false
- name: resolved
description: Filter by resolution status (true or false)
in: query
schema:
type: boolean
responses:
'200':
description: Retrieved assignments successfully
content:
application/json:
schema:
$ref: '#/components/schemas/resultsOfAssignments'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
post:
operationId: assignmentAssign
summary: Used to assign an entity to a user
tags:
- Assignments
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/assignmentAccountRequestBody'
- $ref: '#/components/schemas/assignmentHostRequestBody'
responses:
'201':
description: Assignment created
content:
application/json:
schema:
type: object
properties:
assignment:
$ref: '#/components/schemas/assignment'
examples:
Created Assignment:
$ref: '#/components/examples/assignmentCreated'
'400':
description: Invalid Assigned User
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
title:
type: string
examples:
Bad User:
$ref: '#/components/examples/userCannotBeAssigned'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
'409':
description: Assignment already exists
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
detail: Entity already has an open assignment.
/assignment/{assignmentID}:
parameters:
- name: assignmentID
description: ID of the Assignment you're working on
in: path
schema:
$ref: '#/components/schemas/ID'
get:
operationId: assignmentGetSingle
summary: Describe a specific assignment
tags:
- Assignments
responses:
'200':
description: Describe a specific Assignment
content:
application/json:
schema:
type: object
properties:
assignment:
$ref: '#/components/schemas/assignment'
examples:
Created Assignment:
$ref: '#/components/examples/assignmentCreated'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
'404':
$ref: '#/components/responses/notFound'
put:
operationId: assignmentUpdate
summary: Reassign an assignment
tags:
- Assignments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/assignmentUpdateRequestBody'
responses:
'200':
description: Assignment successfully reassigned
content:
application/json:
schema:
type: object
properties:
assignment:
$ref: '#/components/schemas/assignment'
examples:
Created Assignment:
$ref: '#/components/examples/assignmentReassigned'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
delete:
operationId: assignmentDelete
summary: Delete an assignment
tags:
- Assignments
responses:
'204':
description: Assignment successfully deleted
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
/assignment/{assignmentID}/resolve:
parameters:
- name: assignmentID
description: ID of the Assignment you're working on
in: path
schema:
$ref: '#/components/schemas/ID'
put:
operationId: assignmentResolve
summary: Resolve an assignment
tags:
- Assignments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/assignmentResolveRequestBody'
examples:
False Positive No Triage:
$ref: '#/components/examples/assignmentFalsePositiveResolveNoTriageRequestBody'
Benign Positive With Triage:
$ref: '#/components/examples/assignmentBenignPositiveResolveWithTriageRequestBody'
True Positive With Mark as fixed:
$ref: '#/components/examples/assignmentTruePositiveResolveWithMarkAsFixedRequestBody'
responses:
'200':
description: Assignment resolved
content:
application/json:
schema:
type: object
properties:
assignment:
$ref: '#/components/schemas/assignment'
examples:
Simple Resolution:
$ref: '#/components/examples/assignmentSimpleResolution'
Triageg Resolution:
$ref: '#/components/examples/assignmentTriagedResolution'
'401':
$ref: '#/components/responses/invalidToken'
'403':
$ref: '#/components/responses/invalidPermissions'
'409':
description: Assignment already resolved
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
detail: Assignment has already been resolved.
/assignments/{assignment_id}:
get:
summary: Retrieve specific assignment details
operationId: getAssignmentById
tags:
- Assignments
parameters:
- name: assignment_id
in: path
required: true
schema:
type: integer
description: Unique ID for the assignment
responses:
'200':
description: Assignment details
content:
application/json:
schema:
$ref: '#/components/schemas/Assignment'
patch:
summary: Resolve an assignment
operationId: resolveAssignment
tags:
- Assignments
parameters:
- name: assignment_id
in: path
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
outcome:
type: integer
description: Outcome of the assignment
note:
type: string
description: Additional notes for assignment resolution
responses:
'204':
description: Assignment resolved successfully
components:
examples:
assignmentSimpleResolution:
value:
assignment:
id: 18
assigned_by:
id: 12
username: other-user
date_assigned: '2022-01-02T12:34:56Z'
date_resolved: '2022-01-03T12:34:56Z'
events:
- assignment_id: 18
actor: 82
event_type: resolved
datetime: '2022-01-03T12:34:56Z'
context:
entity_t_score: 75
entity_c_score: 85
triage_as: null
triaged_detection_ids: null
fixed_detection_ids: null
created_rule_ids: null
- assignment_id: 18
actor: 12
event_type: reassigned
datetime: '2022-01-02T12:34:56Z'
context:
from: 80
to: 82
entity_t_score: 75
entity_c_score: 85
- assignment_id: 18
actor: 123
event_type: created
datetime: '2022-01-01T12:34:56Z'
context:
to: 80
entity_t_score: 55
entity_c_score: 65
outcome:
id: 3
builtin: true
user_selectable: true
title: False Positive
category: false_positive
resolved_by:
id: 82
username: SAML:other-user@company.com
triaged_detections: []
host_id: null
account_id: 25
assigned_to:
id: 82
username: SAML:other-user@company.com
assignmentCreated:
value:
assignment:
id: 18
assigned_by:
id: 456
username: dummy-user
date_assigned: '2022-01-01T12:34:56Z'
date_resolved: null
events:
- assignment_id: 18
actor: 123
event_type: created
datetime: '2022-01-01T12:34:56Z'
context:
to: 80
entity_t_score: 55
entity_c_score: 65
outcome: null
resolved_by: null
triaged_detections: null
host_id: null
account_id: 25
assigned_to:
id: 80
username: SAML:dummy-user@company.com
userCannotBeAssigned:
value:
errors:
- title: User 101 does not have permissions to be assigned to hosts.
assignmentBenignPositiveResolveWithTriageRequestBody:
value:
outcome: 1
note: This is a benign positive assignment resolution with triage rules
triage_as: My triage rule name
detection_ids:
- 1
- 2
- 3
assignmentFalsePositiveResolveNoTriageRequestBody:
value:
outcome: 3
note: This is a test false positive assignment resolution
assignmentTriagedResolution:
value:
assignment:
id: 22
assigned_by:
id: 82
username: SAML:other-user@company.com
date_assigned: '2022-09-25T12:34:56Z'
date_resolved: '2022-09-30T12:34:56Z'
events:
- assignment_id: 22
actor: 82
event_type: resolved
datetime: '2022-09-30T12:34:56Z'
context:
entity_t_score: 20
entity_c_score: 55
triage_as: Dummy Triage Rule
triaged_detection_ids:
- 1
- 2
fixed_detection_ids: null
created_rule_ids:
- 500
- 501
- assignment_id: 22
actor: 82
event_type: created
datetime: '2022-09-25T12:34:56Z'
context:
to: 82
entity_t_score: 20
entity_c_score: 55
outcome:
id: 3
builtin: true
user_selectable: true
title: False Positive
category: false_positive
resolved_by:
id: 82
username: SAML:other-user@company.com
triaged_detections:
- 1
- 2
host_id: null
account_id: 331
assigned_to:
id: 82
username: SAML:other-user@company.com
assignmentTruePositiveResolveWithMarkAsFixedRequestBody:
value:
outcome: 1
note: This is a true positive assignment resolution with mark as fixed
mark_as_fixed: true
detection_ids:
- 1
- 2
- 3
assignmentReassigned:
value:
assignment:
id: 18
assigned_by:
id: 12
username: other-user
date_assigned: '2022-01-02T12:34:56Z'
date_resolved: null
events:
- assignment_id: 18
actor: 12
event_type: reassigned
datetime: '2022-01-02T12:34:56Z'
context:
from: 80
to: 82
entity_t_score: 75
entity_c_score: 85
- assignment_id: 18
actor: 123
event_type: created
datetime: '2022-01-01T12:34:56Z'
context:
to: 80
entity_t_score: 55
entity_c_score: 65
outcome: null
resolved_by: null
triaged_detections: null
host_id: null
account_id: 25
assigned_to:
id: 82
username: SAML:other-user@company.com
schemas:
Assignment:
type: object
properties:
id:
type: integer
assigned_by:
type: string
assigned_to:
type: string
date_assigned:
type: string
format: date-time
date_resolved:
type: string
format: date-time
outcome:
type: integer
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
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
link:
description: URL Link
type: string
nullable: true
format: uri
example: https://dummy.link
positiveInt:
type: integer
format: int32
minimum: 0
assignmentUpdateRequestBody:
type: object
properties:
assign_to_user_id:
$ref: '#/components/schemas/ID'
required:
- assign_to_user_id
resultsOfAssignments:
allOf:
- $ref: '#/components/schemas/results'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/assignment'
isoDate:
description: ISO representation of a date
type: string
format: date-time
example: '2022-01-01T00:00:00Z'
name:
type: string
minLength: 1
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
assignmentAccountRequestBody:
type: object
properties:
assign_account_id:
$ref: '#/components/schemas/ID'
assign_to_user_id:
$ref: '#/components/schemas/ID'
required:
- assign_account_id
- assign_to_user_id
arrayOfIDs:
description: Array of IDs
type: array
items:
$ref: '#/components/schemas/ID'
text:
type: string
assignmentResolveRequestBody:
type: object
properties:
outcome:
$ref: '#/components/schemas/ID'
note:
$ref: '#/components/schemas/text'
triage_as:
$ref: '#/components/schemas/name'
mark_as_fixed:
type: boolean
detection_ids:
$ref: '#/components/schemas/arrayOfIDs'
required:
- outcome
error:
type: object
properties:
detail:
description: A human readable error message
type: string
details:
description: A human readable error message
type: string
ID:
description: ID
type: integer
format: int32
minimum: 1
vectraScore:
type: number
minimum: 0
maximum: 99
example: 80
results:
type: object
properties:
count:
$ref: '#/components/schemas/positiveInt'
next:
$ref: '#/components/schemas/link'
previous:
$ref: '#/components/schemas/link'
assignmentEventType:
description: Type of event that can happen to an assignment
type: string
enum:
- created
- reassigned
- resolved
example: created
assignmentHostRequestBody:
type: object
properties:
assign_host_id:
$ref: '#/components/schemas/ID'
assign_to_user_id:
$ref: '#/components/schemas/ID'
required:
- assign_host_id
- assign_to_user_id
assignmentOutcomeCategory:
title: Assignment Outcome allowed categories
type: string
enum:
- benign_true_positive
- malicious_true_positive
- false_positive
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