Vectra AI Accounts API

openapi: 3.0.2
info:
  version: 1.0.0
  title: Vectra Detect Accounts 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: Accounts
  description: Dedicated endpoint to Accounts.
paths:
  /accounts:
    description: Accounts objects.
    get:
      operationId: accountGetSeveral
      summary: Get several Accounts
      tags:
      - Accounts
      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/queryAccountFields'
        style: form
        explode: false
      - name: all
        description: No filter, returns all objects
        in: query
        schema:
          type: boolean
        allowEmptyValue: true
        deprecated: true
      responses:
        '200':
          description: Retrieved Accounts successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resultsOfAccounts'
        '401':
          $ref: '#/components/responses/invalidToken'
        '403':
          $ref: '#/components/responses/invalidPermissions'
  /accounts/{accountID}:
    parameters:
    - name: accountID
      description: ID of the Account you're looking for
      in: path
      schema:
        $ref: '#/components/schemas/ID'
    get:
      operationId: accountGetSingle
      summary: Describe a specific Account
      tags:
      - Accounts
      parameters:
      - name: fields
        description: Filters returned attributes
        in: query
        schema:
          $ref: '#/components/schemas/queryAccountFields'
        style: form
        explode: false
      responses:
        '200':
          description: Describe a specific Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/account'
        '401':
          $ref: '#/components/responses/invalidToken'
        '403':
          $ref: '#/components/responses/invalidPermissions'
        '404':
          $ref: '#/components/responses/notFound'
  /accounts/{accountID}/notes:
    parameters:
    - name: accountID
      description: ID of the Account notes you're looking for
      in: path
      schema:
        $ref: '#/components/schemas/ID'
    get:
      operationId: accountNotesGetSeveral
      summary: Get all account notes
      tags:
      - Accounts
      responses:
        '200':
          description: Retrieved account 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: accountNoteCreate
      summary: Create a new Account note
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/noteRequestBody'
      responses:
        '200':
          description: Account note created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/note'
        '401':
          $ref: '#/components/responses/invalidToken'
        '403':
          $ref: '#/components/responses/invalidPermissions'
  /accounts/{accountID}/notes/{noteID}:
    parameters:
    - name: accountID
      description: ID of the Account 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: accountNoteGetSingle
      summary: Get a single Account note
      tags:
      - Accounts
      responses:
        '200':
          description: Retrieved account note successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/note'
        '401':
          $ref: '#/components/responses/invalidToken'
        '403':
          $ref: '#/components/responses/invalidPermissions'
    patch:
      operationId: accountNoteUpdate
      summary: Update an existing Account note
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/noteRequestBody'
      responses:
        '200':
          description: Account note updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/note'
        '401':
          $ref: '#/components/responses/invalidToken'
        '403':
          $ref: '#/components/responses/invalidPermissions'
    delete:
      operationId: accountNoteDelete
      summary: Delete an existing Account note
      tags:
      - Accounts
      responses:
        '200':
          description: Account note deleted
        '401':
          $ref: '#/components/responses/invalidToken'
        '403':
          $ref: '#/components/responses/invalidPermissions'
  /search/accounts:
    description: Search for accounts objects.
    get:
      operationId: searchAccounts
      summary: Search for Accounts
      tags:
      - Accounts
      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/account/{accountID}:
    description: The tagging endpoint can be used to manage Account tags
    parameters:
    - name: accountID
      description: ID of the Account you're looking for
      in: path
      schema:
        $ref: '#/components/schemas/ID'
    get:
      operationId: accountTagsGetAll
      summary: Get all Account's tags
      tags:
      - Accounts
      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: accountTagsReplace
      summary: Replace all Account's tags
      tags:
      - Accounts
      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'
  /accounts/{account_id}:
    get:
      summary: Retrieve single account details
      operationId: getAccountById
      tags:
      - Accounts
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: integer
        description: Unique ID for the account
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
    post:
      summary: Add note to account
      tags:
      - Accounts
      parameters:
      - name: account_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
  /accounts/{id}/notes:
    get:
      summary: Get account notes
      tags:
      - Accounts
      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'
components:
  schemas:
    queryAccountFields:
      type: array
      items:
        type: string
        enum:
        - id
        - url
        - name
        - state
        - threat
        - certainty
        - severity
        - account_type
        - tags
        - note
        - notes
        - note_modified_by
        - note_modified_timestamp
        - privilege_level
        - privilege_category
        - last_detection_timestamp
        - detection_set
        - probable_home
        - detection_summaries
    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
    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'
    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
    Account:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        state:
          type: string
        threat:
          type: integer
        certainty:
          type: integer
        last_detection_timestamp:
          type: string
          format: date-time
    arrayOfLinks:
      description: Array of links
      type: array
      items:
        $ref: '#/components/schemas/link'
    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
    accountType:
      description: Account's type
      type: array
      items:
        type: string
        enum:
        - kerberos
        - o365
        example: kerberos
    ID:
      description: ID
      type: integer
      format: int32
      minimum: 1
    arrayOfNames:
      description: Array of names
      type: array
      items:
        $ref: '#/components/schemas/name'
    resultsOfAccounts:
      allOf:
      - $ref: '#/components/schemas/results'
      - type: object
        properties:
          results:
            type: array
            items:
              $ref: '#/components/schemas/account'
    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
    account:
      description: Account
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        url:
          $ref: '#/components/schemas/link'
        name:
          $ref: '#/components/schemas/name'
        state:
          $ref: '#/components/schemas/state'
        threat:
          $ref: '#/components/schemas/vectraScore'
        certainty:
          $ref: '#/components/schemas/vectraScore'
        severity:
          $ref: '#/components/schemas/severity'
        account_type:
          $ref: '#/components/schemas/accountType'
        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'
        privilege_level:
          $ref: '#/components/schemas/privilegeLevel'
        privilege_category:
          $ref: '#/components/schemas/privilegeCategory'
        last_detection_timestamp:
          $ref: '#/components/schemas/isoDate'
        detection_set:
          $ref: '#/components/schemas/arrayOfLinks'
        probable_home:
          oneOf:
          - $ref: '#/components/schemas/text'
          - type: string
            nullable: true
        assignment:
          oneOf:
          - $ref: '#/components/schemas/assignment'
          - type: string
            nullable: true
        past_assignments:
          type: array
          items:
            $ref: '#/components/schemas/assignment'
        sensors:
          $ref: '#/components/schemas/arrayOfNames'
    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