McAfee ESM API

openapi: 3.1.0
info:
  title: McAfee ESM API
  description: >-
    McAfee Enterprise Security Manager (ESM) SIEM REST API for managing
    security events, alarms, watchlists, data sources, and executing queries
    against the event database for security monitoring and incident response.
  version: '11.0'
  contact:
    name: McAfee Support
    url: https://www.mcafee.com/enterprise/en-us/support.html
  termsOfService: https://www.mcafee.com/enterprise/en-us/about/legal/terms-of-use.html
externalDocs:
  description: McAfee ESM API Reference Guide
  url: https://docs.mcafee.com/bundle/enterprise-security-manager-api-reference-guide
servers:
  - url: https://{esm-server}/rs/esm
    description: McAfee ESM Server
    variables:
      esm-server:
        default: your-esm-server
        description: Hostname or IP of the ESM server
tags:
  - name: Alarms
    description: Manage security alarms
  - name: Authentication
    description: Session authentication and management
  - name: Cases
    description: Manage incident response cases
  - name: Data Sources
    description: Manage event data sources
  - name: Devices
    description: Manage ESM device hierarchy
  - name: Events
    description: Query and retrieve security events
  - name: Watchlists
    description: Manage security watchlists
security:
  - sessionAuth: []
paths:
  /v2/login:
    post:
      operationId: login
      summary: McAfee Authenticate and create session
      description: >-
        Authenticate with ESM credentials to obtain a session token. The
        session token must be included in subsequent requests as a cookie
        or header.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: ESM administrator username
                password:
                  type: string
                  description: Base64-encoded password
                locale:
                  type: string
                  description: Locale for the session
                  default: en_US
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
      security: []
  /v2/logout:
    delete:
      operationId: logout
      summary: McAfee End current session
      description: >-
        Terminate the current authenticated session.
      tags:
        - Authentication
      responses:
        '200':
          description: Session terminated
        '401':
          description: Not authenticated
  /v2/alarmGetTriggeredAlarms:
    post:
      operationId: getTriggeredAlarms
      summary: McAfee Get triggered alarms
      description: >-
        Retrieve a list of triggered alarms within a specified time range,
        optionally filtered by status or severity.
      tags:
        - Alarms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                triggeredTimeRange:
                  type: string
                  enum:
                    - LAST_24_HOURS
                    - LAST_WEEK
                    - LAST_MONTH
                    - CUSTOM
                  description: Time range for triggered alarms
                customStart:
                  type: string
                  format: date-time
                  description: Custom start time (when triggeredTimeRange is CUSTOM)
                customEnd:
                  type: string
                  format: date-time
                  description: Custom end time (when triggeredTimeRange is CUSTOM)
                status:
                  type: string
                  enum:
                    - acknowledged
                    - unacknowledged
                    - all
                  description: Filter by alarm acknowledgment status
                pageSize:
                  type: integer
                  description: Number of results per page
                  default: 50
                pageNumber:
                  type: integer
                  description: Page number for pagination
                  default: 1
      responses:
        '200':
          description: List of triggered alarms
          content:
            application/json:
              schema:
                type: object
                properties:
                  triggeredAlarms:
                    type: array
                    items:
                      $ref: '#/components/schemas/TriggeredAlarm'
                  totalCount:
                    type: integer
        '401':
          description: Not authenticated
  /v2/alarmAcknowledgeTriggeredAlarm:
    post:
      operationId: acknowledgeAlarm
      summary: McAfee Acknowledge a triggered alarm
      description: >-
        Acknowledge one or more triggered alarms, marking them as reviewed
        by an analyst.
      tags:
        - Alarms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - triggeredIds
              properties:
                triggeredIds:
                  type: array
                  items:
                    type: integer
                  description: List of triggered alarm IDs to acknowledge
      responses:
        '200':
          description: Alarms acknowledged
        '401':
          description: Not authenticated
  /v2/alarmDeleteTriggeredAlarm:
    post:
      operationId: deleteTriggeredAlarm
      summary: McAfee Delete triggered alarms
      description: >-
        Delete one or more triggered alarm records from the ESM database.
      tags:
        - Alarms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - triggeredIds
              properties:
                triggeredIds:
                  type: array
                  items:
                    type: integer
                  description: List of triggered alarm IDs to delete
      responses:
        '200':
          description: Alarms deleted
        '401':
          description: Not authenticated
  /v2/qryExecuteDetail:
    post:
      operationId: executeQuery
      summary: McAfee Execute an event query
      description: >-
        Execute a query against the ESM event database to retrieve security
        events matching specified criteria. Returns a result ID for fetching
        results asynchronously.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - config
              properties:
                config:
                  type: object
                  properties:
                    timeRange:
                      type: string
                      enum:
                        - LAST_10_MINUTES
                        - LAST_HOUR
                        - LAST_24_HOURS
                        - LAST_WEEK
                        - LAST_MONTH
                        - CUSTOM
                      description: Query time range
                    customStart:
                      type: string
                      format: date-time
                      description: Custom start time
                    customEnd:
                      type: string
                      format: date-time
                      description: Custom end time
                    fields:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            description: Field name
                      description: Fields to return in results
                    filters:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Filter type
                          field:
                            type: object
                            properties:
                              name:
                                type: string
                          value:
                            type: string
                      description: Query filters
                    limit:
                      type: integer
                      description: Maximum number of results
                      default: 100
      responses:
        '200':
          description: Query initiated, result ID returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  resultID:
                    type: integer
                    description: Result ID for fetching query results
        '400':
          description: Invalid query
        '401':
          description: Not authenticated
  /v2/qryGetResults:
    post:
      operationId: getQueryResults
      summary: McAfee Get query results
      description: >-
        Retrieve the results of a previously executed query using the
        result ID. May need to be called multiple times as results become available.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - resultID
              properties:
                resultID:
                  type: integer
                  description: Result ID from executeQuery
                startPos:
                  type: integer
                  description: Starting position for pagination
                  default: 0
                numRows:
                  type: integer
                  description: Number of rows to return
                  default: 50
      responses:
        '200':
          description: Query results
          content:
            application/json:
              schema:
                type: object
                properties:
                  columns:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                    description: Column definitions
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        values:
                          type: array
                          items:
                            type: string
                    description: Result rows
                  totalRows:
                    type: integer
                    description: Total number of matching rows
                  complete:
                    type: boolean
                    description: Whether the query has completed
        '401':
          description: Not authenticated
        '404':
          description: Result ID not found
  /v2/sysGetWatchlists:
    post:
      operationId: getWatchlists
      summary: McAfee List watchlists
      description: >-
        Retrieve all configured watchlists, which are collections of
        values (IPs, hostnames, etc.) used for correlation and alerting.
      tags:
        - Watchlists
      responses:
        '200':
          description: List of watchlists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Watchlist'
        '401':
          description: Not authenticated
  /v2/sysGetWatchlistValues:
    post:
      operationId: getWatchlistValues
      summary: McAfee Get watchlist values
      description: >-
        Retrieve the values (entries) contained in a specific watchlist.
      tags:
        - Watchlists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                  description: Watchlist ID
      responses:
        '200':
          description: Watchlist values
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                    description: List of watchlist values
        '401':
          description: Not authenticated
        '404':
          description: Watchlist not found
  /v2/sysAddWatchlistValues:
    post:
      operationId: addWatchlistValues
      summary: McAfee Add values to a watchlist
      description: >-
        Add one or more values to an existing watchlist for use in
        correlation rules and alarm triggers.
      tags:
        - Watchlists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - values
              properties:
                id:
                  type: integer
                  description: Watchlist ID
                values:
                  type: array
                  items:
                    type: string
                  description: Values to add
      responses:
        '200':
          description: Values added to watchlist
        '401':
          description: Not authenticated
        '404':
          description: Watchlist not found
  /v2/sysRemoveWatchlistValues:
    post:
      operationId: removeWatchlistValues
      summary: McAfee Remove values from a watchlist
      description: >-
        Remove one or more values from an existing watchlist.
      tags:
        - Watchlists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - values
              properties:
                id:
                  type: integer
                  description: Watchlist ID
                values:
                  type: array
                  items:
                    type: string
                  description: Values to remove
      responses:
        '200':
          description: Values removed from watchlist
        '401':
          description: Not authenticated
        '404':
          description: Watchlist not found
  /v2/dsGetDataSourceList:
    post:
      operationId: getDataSources
      summary: McAfee List data sources
      description: >-
        Retrieve all configured data sources that feed events into the
        ESM, including syslog sources, database connections, and agent-based sources.
      tags:
        - Data Sources
      responses:
        '200':
          description: List of data sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataSource'
        '401':
          description: Not authenticated
  /v2/caseGetCaseList:
    post:
      operationId: getCases
      summary: McAfee List incident cases
      description: >-
        Retrieve a list of incident response cases managed in the ESM,
        with optional filtering by status, assignee, or priority.
      tags:
        - Cases
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                since:
                  type: string
                  format: date-time
                  description: Return cases created since this time
      responses:
        '200':
          description: List of cases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Case'
        '401':
          description: Not authenticated
  /v2/caseAddCase:
    post:
      operationId: addCase
      summary: McAfee Create a new case
      description: >-
        Create a new incident response case for tracking investigation
        and remediation of a security incident.
      tags:
        - Cases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - summary
                - severity
              properties:
                summary:
                  type: string
                  description: Case summary
                assignee:
                  type: string
                  description: Assigned analyst
                severity:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: Case severity (1-100)
                notes:
                  type: string
                  description: Initial case notes
      responses:
        '200':
          description: Case created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
        '400':
          description: Invalid case data
        '401':
          description: Not authenticated
  /v2/devGetDeviceList:
    post:
      operationId: getDevices
      summary: McAfee List ESM devices
      description: >-
        Retrieve the list of devices in the ESM device hierarchy, including
        receivers, ELM, ACE, DEM, and ADM components.
      tags:
        - Devices
      responses:
        '200':
          description: List of ESM devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EsmDevice'
        '401':
          description: Not authenticated
components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: JWTToken
      description: Session token obtained from the login endpoint
  schemas:
    LoginResponse:
      type: object
      properties:
        session:
          type: string
          description: Session token for subsequent requests
        userId:
          type: integer
          description: Authenticated user ID
        roles:
          type: array
          items:
            type: string
          description: User roles
        locale:
          type: string
          description: Session locale
    TriggeredAlarm:
      type: object
      properties:
        id:
          type: integer
          description: Triggered alarm ID
        alarmName:
          type: string
          description: Name of the alarm definition
        triggeredDate:
          type: string
          format: date-time
          description: When the alarm was triggered
        acknowledgedDate:
          type: string
          format: date-time
          description: When the alarm was acknowledged
        acknowledgedUsername:
          type: string
          description: User who acknowledged the alarm
        severity:
          type: integer
          description: Alarm severity
        summary:
          type: string
          description: Alarm summary text
        assignee:
          type: string
          description: Assigned analyst
        caseId:
          type: integer
          description: Associated case ID
        events:
          type: array
          items:
            type: object
            properties:
              eventId:
                type: string
              sourceIp:
                type: string
              destIp:
                type: string
          description: Associated events
    Watchlist:
      type: object
      properties:
        id:
          type: integer
          description: Watchlist ID
        name:
          type: string
          description: Watchlist name
        type:
          type: string
          description: Watchlist value type (e.g., IPAddress, Hash, String)
        valueCount:
          type: integer
          description: Number of values in the watchlist
        dynamic:
          type: boolean
          description: Whether the watchlist is dynamically populated
    DataSource:
      type: object
      properties:
        id:
          type: integer
          description: Data source ID
        name:
          type: string
          description: Data source name
        ipAddress:
          type: string
          description: IP address of the data source
        type:
          type: string
          description: Data source type
        enabled:
          type: boolean
          description: Whether the data source is enabled
        childType:
          type: string
          description: Child data source type
        zoneId:
          type: integer
          description: Zone ID
    Case:
      type: object
      properties:
        id:
          type: integer
          description: Case ID
        summary:
          type: string
          description: Case summary
        status:
          type: string
          enum:
            - Open
            - Closed
            - Other
          description: Case status
        severity:
          type: integer
          description: Case severity (1-100)
        assignee:
          type: string
          description: Assigned analyst
        notes:
          type: array
          items:
            type: object
            properties:
              timestamp:
                type: string
                format: date-time
              author:
                type: string
              content:
                type: string
          description: Case notes
        openTime:
          type: string
          format: date-time
          description: When the case was opened
        closeTime:
          type: string
          format: date-time
          description: When the case was closed
    EsmDevice:
      type: object
      properties:
        id:
          type: integer
          description: Device ID
        name:
          type: string
          description: Device name
        ipAddress:
          type: string
          description: Device IP address
        type:
          type: string
          enum:
            - ESM
            - Receiver
            - ELM
            - ACE
            - DEM
            - ADM
          description: Device type in the ESM hierarchy
        status:
          type: string
          description: Device operational status
        model:
          type: string
          description: Hardware or virtual model