openapi: 3.1.0
info:
  title: Trellix Web Gateway Policy Anti-Malware Security Events API
  description: API for creating, updating, and managing security policies, rule sets, and configurations for web filtering and threat prevention on Trellix Web Gateway (formerly McAfee Web Gateway). Provides programmatic access to policy rules, URL filter settings, anti-malware settings, and SSL scanning configurations.
  version: '1.0'
  contact:
    name: Trellix Support
    url: https://www.trellix.com/support/
    email: support@trellix.com
  termsOfService: https://www.trellix.com/legal/terms-of-use/
servers:
- url: https://{mwg-server}:{port}/Konfigurator/REST/policy
  description: Trellix Web Gateway Policy Endpoint
  variables:
    mwg-server:
      default: mwg.example.com
      description: Hostname or IP address of the Web Gateway appliance
    port:
      default: '4712'
      description: Management port for the REST API
security:
- cookieAuth: []
tags:
- name: Security Events
  description: Security event and threat detection data
paths:
  /events/security:
    get:
      operationId: getSecurityEvents
      summary: Retrieve security events
      description: Query security events including malware detections, policy violations, blocked threats, and suspicious activity alerts.
      tags:
      - Security Events
      parameters:
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      - name: severity
        in: query
        description: Filter by event severity
        schema:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
      - name: eventType
        in: query
        description: Filter by event type
        schema:
          type: string
          enum:
          - malware
          - phishing
          - policy_violation
          - data_leak
          - certificate_error
          - authentication_failure
      - name: sourceIp
        in: query
        description: Filter by source IP address
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Security events returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalCount:
                    type: integer
                    description: Total number of matching events
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecurityEvent'
        '401':
          description: Unauthorized
  /events/security/{eventId}:
    get:
      operationId: getSecurityEvent
      summary: Get a specific security event
      description: Retrieve detailed information about a specific security event, including full threat analysis data.
      tags:
      - Security Events
      parameters:
      - $ref: '#/components/parameters/eventId'
      responses:
        '200':
          description: Security event details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityEvent'
        '401':
          description: Unauthorized
        '404':
          description: Event not found
components:
  parameters:
    endTime:
      name: endTime
      in: query
      description: End time for the query range (ISO 8601)
      schema:
        type: string
        format: date-time
    eventId:
      name: eventId
      in: path
      required: true
      description: Unique identifier of the security event
      schema:
        type: string
    startTime:
      name: startTime
      in: query
      description: Start time for the query range (ISO 8601)
      schema:
        type: string
        format: date-time
    offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
    limit:
      name: limit
      in: query
      description: Maximum number of results to return
      schema:
        type: integer
        default: 100
        maximum: 1000
  schemas:
    SecurityEvent:
      type: object
      properties:
        id:
          type: string
          description: Unique event identifier
        timestamp:
          type: string
          format: date-time
          description: Time the event occurred
        severity:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
          description: Event severity level
        eventType:
          type: string
          enum:
          - malware
          - phishing
          - policy_violation
          - data_leak
          - certificate_error
          - authentication_failure
          description: Type of security event
        sourceIp:
          type: string
          description: Source IP address
        user:
          type: string
          description: Associated user name
        url:
          type: string
          description: URL involved in the event
        threatName:
          type: string
          description: Name of the detected threat
        action:
          type: string
          enum:
          - blocked
          - quarantined
          - logged
          - cleaned
          description: Action taken
        ruleName:
          type: string
          description: Policy rule that triggered the event
        details:
          type: string
          description: Additional event details
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: JSESSIONID
      description: Session cookie obtained via the Konfigurator REST /login endpoint.
externalDocs:
  description: Trellix Web Gateway Policy API Documentation
  url: https://docs.trellix.com/bundle/web-gateway-policy-api