Varonis Alerts API

openapi: 3.1.0
info:
  title: Varonis DatAlert Alerts API
  description: API for accessing threat detection and incident response capabilities from Varonis DatAlert. Provides endpoints for retrieving alerts, managing alert status, adding notes to alerts, and accessing alerted events for investigation and threat hunting. The DatAlert API enables integration with SIEM and SOAR platforms for centralized security operations.
  version: '1.0'
  contact:
    name: Varonis Support
    url: https://www.varonis.com/resources/support
  termsOfService: https://www.varonis.com/terms
  license:
    name: Proprietary
    url: https://www.varonis.com/terms
servers:
- url: https://{domain}/api
  description: Varonis SaaS Instance
  variables:
    domain:
      default: your-instance.varonis.io
      description: The domain of your Varonis SaaS instance, typically in the format your-instance.varonis.io.
security:
- apiKeyHeader: []
tags:
- name: Alerts
  description: Retrieve, filter, and manage security alerts generated by Varonis DatAlert threat detection engine.
paths:
  /threatdetection/api/alert/alert/GetAlerts:
    post:
      operationId: getAlerts
      summary: Varonis Get Alerts
      description: Retrieves alerts from Varonis DatAlert based on specified filter criteria. Supports filtering by threat model name, time range, alert status, severity, device name, and user name. Returns comprehensive alert data including severity, category, status, user details, device information, and asset paths.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAlertsRequest'
            examples:
              getAlertsRequestExample:
                summary: Default getAlerts request
                x-microcks-default: true
                value:
                  threatModelName:
                  - example-string
                  startTime: '2025-03-15T14:30:00Z'
                  endTime: '2025-03-15T14:30:00Z'
                  alertStatus:
                  - Open
                  alertSeverity:
                  - Low
                  deviceName: example-string
                  userName: example-string
                  lastDays: 1
                  extraFields:
                  - example-string
                  descendingOrder: true
                  maxResults: 1
                  offset: 1
      responses:
        '200':
          description: Successfully retrieved alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsResponse'
              examples:
                getAlerts200Example:
                  summary: Default getAlerts 200 response
                  x-microcks-default: true
                  value:
                    alerts:
                    - id: example-string
                      name: example-string
                      time: '2025-03-15T14:30:00Z'
                      severity: Low
                      category: Reconnaissance
                      status: Open
                      closeReason: Resolved
                      country: example-string
                      state: example-string
                      userName: example-string
                      userAccountType: example-string
                      userDepartment: example-string
                      deviceName: example-string
                      isMaliciousIP: true
                      assetPath: example-string
                      platform: Windows
                      eventCount: 1
                      isFlagged: true
                      containsSensitiveData: true
                    totalCount: 1
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                getAlerts400Example:
                  summary: Default getAlerts 400 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                getAlerts401Example:
                  summary: Default getAlerts 401 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /threatdetection/api/alert/alert/SetAlertStatus:
    post:
      operationId: updateAlertStatus
      summary: Varonis Update Alert Status
      description: Updates the status of an existing alert in Varonis DatAlert. Allows transitioning an alert between Open and Under Investigation statuses. Optionally accepts a note to document the reason for the status change.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlertStatusRequest'
            examples:
              updateAlertStatusRequestExample:
                summary: Default updateAlertStatus request
                x-microcks-default: true
                value:
                  alertId: example-string
                  status: Open
                  note: example-string
      responses:
        '200':
          description: Alert status updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                updateAlertStatus200Example:
                  summary: Default updateAlertStatus 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: example-string
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                updateAlertStatus400Example:
                  summary: Default updateAlertStatus 400 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                updateAlertStatus401Example:
                  summary: Default updateAlertStatus 401 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
        '404':
          description: Alert not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                updateAlertStatus404Example:
                  summary: Default updateAlertStatus 404 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /threatdetection/api/alert/alert/CloseAlert:
    post:
      operationId: closeAlert
      summary: Varonis Close Alert
      description: Closes an alert in Varonis DatAlert with a specified close reason. The close reason helps track resolution patterns and improve threat model accuracy over time. Supported reasons include Resolved, Misconfiguration, Threat model disabled or deleted, Account misclassification, Legitimate activity, and Other.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseAlertRequest'
            examples:
              closeAlertRequestExample:
                summary: Default closeAlert request
                x-microcks-default: true
                value:
                  alertId: example-string
                  closeReason: Resolved
                  note: example-string
      responses:
        '200':
          description: Alert closed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                closeAlert200Example:
                  summary: Default closeAlert 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: example-string
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                closeAlert400Example:
                  summary: Default closeAlert 400 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                closeAlert401Example:
                  summary: Default closeAlert 401 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
        '404':
          description: Alert not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                closeAlert404Example:
                  summary: Default closeAlert 404 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /threatdetection/api/alert/alert/AddNote:
    post:
      operationId: addAlertNote
      summary: Varonis Add Note to Alert
      description: Adds a note to an existing alert in Varonis DatAlert. Notes provide an audit trail of investigation activities and can be used to document findings, remediation steps, or communication between security team members during incident response.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddNoteRequest'
            examples:
              addAlertNoteRequestExample:
                summary: Default addAlertNote request
                x-microcks-default: true
                value:
                  alertId: example-string
                  note: example-string
      responses:
        '200':
          description: Note added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                addAlertNote200Example:
                  summary: Default addAlertNote 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    message: example-string
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                addAlertNote400Example:
                  summary: Default addAlertNote 400 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                addAlertNote401Example:
                  summary: Default addAlertNote 401 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
        '404':
          description: Alert not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                addAlertNote404Example:
                  summary: Default addAlertNote 404 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates whether the operation completed successfully.
        message:
          type: string
          description: Human-readable message describing the result.
    AddNoteRequest:
      type: object
      required:
      - alertId
      - note
      properties:
        alertId:
          type: string
          description: Unique identifier of the alert to add the note to.
        note:
          type: string
          description: Text content of the note to add to the alert.
    GetAlertsRequest:
      type: object
      properties:
        threatModelName:
          type: array
          items:
            type: string
          description: Filter by threat model names. Supports pipe-separated values.
        startTime:
          type: string
          format: date-time
          description: Start of the time range for alert retrieval in ISO 8601 format.
        endTime:
          type: string
          format: date-time
          description: End of the time range for alert retrieval in ISO 8601 format.
        alertStatus:
          type: array
          items:
            type: string
            enum:
            - Open
            - Under Investigation
            - Closed
          description: Filter by alert status values.
        alertSeverity:
          type: array
          items:
            type: string
            enum:
            - Low
            - Medium
            - High
          description: Filter by alert severity levels.
        deviceName:
          type: string
          description: Filter by the name of the device associated with the alert.
        userName:
          type: string
          description: Filter by the user name associated with the alert.
        lastDays:
          type: integer
          minimum: 1
          description: Retrieve alerts from the last N days. Alternative to using startTime and endTime.
        extraFields:
          type: array
          items:
            type: string
          description: Additional fields to include in the response beyond default fields.
        descendingOrder:
          type: boolean
          description: When true, results are returned in descending order by time.
        maxResults:
          type: integer
          minimum: 1
          maximum: 5000
          description: Maximum number of alerts to return in the response.
        offset:
          type: integer
          minimum: 0
          description: Number of alerts to skip for pagination.
    CloseAlertRequest:
      type: object
      required:
      - alertId
      - closeReason
      properties:
        alertId:
          type: string
          description: Unique identifier of the alert to close.
        closeReason:
          type: string
          enum:
          - Resolved
          - Misconfiguration
          - Threat model disabled or deleted
          - Account misclassification
          - Legitimate activity
          - Other
          description: Reason for closing the alert. Helps track resolution patterns.
        note:
          type: string
          description: Optional note to provide additional context for closing the alert.
    Alert:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the alert.
        name:
          type: string
          description: Name of the alert, typically derived from the threat model.
        time:
          type: string
          format: date-time
          description: Timestamp when the alert was triggered.
        severity:
          type: string
          enum:
          - Low
          - Medium
          - High
          description: Severity level of the alert.
        category:
          type: string
          enum:
          - Reconnaissance
          - Intrusion
          - Exploitation
          - Privilege Escalation
          - Lateral Movement
          description: MITRE ATT&CK-aligned category of the alert.
        status:
          type: string
          enum:
          - Open
          - Under Investigation
          - Closed
          description: Current status of the alert.
        closeReason:
          type: string
          enum:
          - Resolved
          - Misconfiguration
          - Threat model disabled or deleted
          - Account misclassification
          - Legitimate activity
          - Other
          description: Reason for closing the alert, populated only when status is Closed.
        country:
          type: string
          description: Country associated with the alert activity.
        state:
          type: string
          description: State or region associated with the alert activity.
        userName:
          type: string
          description: Name of the user whose activity triggered the alert.
        userAccountType:
          type: string
          description: Type of user account such as service account, admin, or regular user.
        userDepartment:
          type: string
          description: Department of the user whose activity triggered the alert.
        deviceName:
          type: string
          description: Name of the device involved in the alert.
        isMaliciousIP:
          type: boolean
          description: Indicates whether the IP address associated with the alert is known to be malicious.
        assetPath:
          type: string
          description: File system or resource path of the affected asset.
        platform:
          type: string
          enum:
          - Windows
          - Exchange
          - SharePoint
          - DNS
          - Active Directory
          - Azure AD
          - Microsoft 365
          description: Platform or data source where the alert was generated.
        eventCount:
          type: integer
          description: Number of events associated with the alert.
        isFlagged:
          type: boolean
          description: Whether the alert has been flagged for special attention.
        containsSensitiveData:
          type: boolean
          description: Whether the affected resource contains classified sensitive data.
    UpdateAlertStatusRequest:
      type: object
      required:
      - alertId
      - status
      properties:
        alertId:
          type: string
          description: Unique identifier of the alert to update.
        status:
          type: string
          enum:
          - Open
          - Under Investigation
          description: New status for the alert. Use CloseAlert endpoint to close.
        note:
          type: string
          description: Optional note to document the reason for the status change.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code identifying the type of error.
        message:
          type: string
          description: Human-readable description of the error.
    AlertsResponse:
      type: object
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
          description: Array of alert objects matching the filter criteria.
        totalCount:
          type: integer
          description: Total number of alerts matching the filter criteria.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authenticating with the Varonis DatAlert API. Generate an API key from the Varonis Web Interface under Configuration, then API Keys. The key must have the Threat Detection Integrator role.
externalDocs:
  description: Varonis Help Center
  url: https://help.varonis.com/s/