openapi: 3.1.0
info:
  title: Varonis DatAlert 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

externalDocs:
  description: Varonis Help Center
  url: https://help.varonis.com/s/

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.
- name: Events
  description: >-
    Access forensic event data associated with specific alerts for
    investigation and threat hunting.
- name: Threat Models
  description: >-
    Retrieve threat model definitions used to generate alerts, including
    categories and severity levels.

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/GetAlertedEvents:
    post:
      operationId: getAlertedEvents
      summary: Varonis Get Alerted Events
      description: >-
        Retrieves the underlying events associated with a specific alert for
        forensic investigation. Returns event-level data including operation
        types, source and destination accounts, affected resources, IP
        addresses, and geolocation information. Essential for threat hunting
        and understanding the full scope of a security incident.
      tags:
      - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAlertedEventsRequest'
            examples:
              getAlertedEventsRequestExample:
                summary: Default getAlertedEvents request
                x-microcks-default: true
                value:
                  alertId: example-string
                  startTime: '2025-03-15T14:30:00Z'
                  endTime: '2025-03-15T14:30:00Z'
                  lastDays: 1
                  extraFields:
                  - example-string
                  descendingOrder: true
      responses:
        '200':
          description: Successfully retrieved alerted events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertedEventsResponse'
              examples:
                getAlertedEvents200Example:
                  summary: Default getAlertedEvents 200 response
                  x-microcks-default: true
                  value:
                    events:
                    - id: example-string
                      time: '2025-03-15T14:30:00Z'
                      operationType: example-string
                      sourceAccount: example-string
                      destinationAccount: example-string
                      resource: example-string
                      ipAddress: 10.1.2.3
                      ipReputation: example-string
                      country: example-string
                      state: example-string
                      deviceName: example-string
                    totalCount: 1
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                getAlertedEvents400Example:
                  summary: Default getAlertedEvents 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:
                getAlertedEvents401Example:
                  summary: Default getAlertedEvents 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:
                getAlertedEvents404Example:
                  summary: Default getAlertedEvents 404 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
  /threatdetection/api/alert/alert/GetThreatModels:
    get:
      operationId: getThreatModels
      summary: Varonis Get Threat Models
      description: >-
        Retrieves the list of threat models configured in Varonis DatAlert.
        Threat models define the behavioral patterns and rules used to generate
        alerts. Each threat model includes a name, category, severity level,
        and source classification. Supports optional filtering by name with
        wildcard support.
      tags:
      - Threat Models
      parameters:
      - $ref: '#/components/parameters/ThreatModelName'
      responses:
        '200':
          description: Successfully retrieved threat models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreatModelsResponse'
              examples:
                getThreatModels200Example:
                  summary: Default getThreatModels 200 response
                  x-microcks-default: true
                  value:
                    threatModels:
                    - id: example-string
                      name: example-string
                      category: example-string
                      severity: Low
                      source: example-string
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

              examples:
                getThreatModels401Example:
                  summary: Default getThreatModels 401 response
                  x-microcks-default: true
                  value:
                    error: example-string
                    message: example-string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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.

  parameters:
    ThreatModelName:
      name: name
      in: query
      required: false
      description: >-
        Filter threat models by name. Supports pipe-separated values and
        wildcard characters for pattern matching.
      schema:
        type: string
        example: 'Abnormal*'

  schemas:
    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.

    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.

    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.

    GetAlertedEventsRequest:
      type: object
      required:
      - alertId
      properties:
        alertId:
          type: string
          description: >-
            Unique identifier of the alert to retrieve events for.
        startTime:
          type: string
          format: date-time
          description: >-
            Start of the time range for event retrieval.
        endTime:
          type: string
          format: date-time
          description: >-
            End of the time range for event retrieval.
        lastDays:
          type: integer
          minimum: 1
          description: >-
            Retrieve events from the last N days.
        extraFields:
          type: array
          items:
            type: string
          description: >-
            Additional fields to include in the response.
        descendingOrder:
          type: boolean
          description: >-
            When true, results are returned in descending order by time.

    AlertedEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/AlertedEvent'
          description: >-
            Array of event objects associated with the specified alert.
        totalCount:
          type: integer
          description: >-
            Total number of events associated with the alert.

    AlertedEvent:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for the event.
        time:
          type: string
          format: date-time
          description: >-
            Timestamp when the event occurred.
        operationType:
          type: string
          description: >-
            Type of operation performed such as file access, permission change,
            or login attempt.
        sourceAccount:
          type: string
          description: >-
            Account that initiated the operation.
        destinationAccount:
          type: string
          description: >-
            Target account affected by the operation.
        resource:
          type: string
          description: >-
            Resource path or name affected by the event.
        ipAddress:
          type: string
          format: ipv4
          description: >-
            IP address from which the operation was performed.
        ipReputation:
          type: string
          description: >-
            Reputation classification of the IP address.
        country:
          type: string
          description: >-
            Country associated with the IP address.
        state:
          type: string
          description: >-
            State or region associated with the IP address.
        deviceName:
          type: string
          description: >-
            Name of the device from which the operation was performed.

    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.

    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.

    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.

    ThreatModelsResponse:
      type: object
      properties:
        threatModels:
          type: array
          items:
            $ref: '#/components/schemas/ThreatModel'
          description: >-
            Array of threat model objects.

    ThreatModel:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for the threat model.
        name:
          type: string
          description: >-
            Display name of the threat model.
        category:
          type: string
          description: >-
            Category classification of the threat model aligned with MITRE
            ATT&CK framework.
        severity:
          type: string
          enum:
          - Low
          - Medium
          - High
          description: >-
            Default severity level assigned to alerts generated by this model.
        source:
          type: string
          description: >-
            Source or origin of the threat model such as built-in or custom.

    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: >-
            Indicates whether the operation completed successfully.
        message:
          type: string
          description: >-
            Human-readable message describing the result.

    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.