openapi: 3.1.0
info:
  title: McAfee ePO Alarms Threats API
  description: McAfee ePolicy Orchestrator (ePO) REST API for centralized security management, including system management, policy assignment, task scheduling, query execution, and threat event retrieval across managed endpoints.
  version: '5.10'
  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
servers:
- url: https://{epo-server}:8443/remote
  description: McAfee ePO Server
  variables:
    epo-server:
      default: your-epo-server
      description: Hostname or IP of the ePO server
security:
- basicAuth: []
tags:
- name: Threats
  description: Retrieve and manage detected threats
paths:
  /edr/v2/threats:
    get:
      operationId: listThreats
      summary: McAfee List threats
      description: Retrieve a paginated list of detected threats across all managed endpoints, with optional filtering by severity, status, and time range.
      tags:
      - Threats
      parameters:
      - name: filter[severity]
        in: query
        required: false
        description: Filter threats by severity level
        schema:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
      - name: filter[status]
        in: query
        required: false
        description: Filter threats by current status
        schema:
          type: string
          enum:
          - new
          - investigating
          - resolved
          - dismissed
      - name: filter[detectedAfter]
        in: query
        required: false
        description: Filter threats detected after this ISO 8601 timestamp
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/pageLimit'
      - $ref: '#/components/parameters/pageOffset'
      responses:
        '200':
          description: Paginated list of threats
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ThreatListResponse'
        '401':
          description: Unauthorized
  /edr/v2/threats/{threatId}:
    get:
      operationId: getThreat
      summary: McAfee Get a specific threat
      description: Retrieve detailed information about a specific threat by its unique ID, including affected hosts, threat indicators, and remediation status.
      tags:
      - Threats
      parameters:
      - $ref: '#/components/parameters/threatId'
      responses:
        '200':
          description: Threat details
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ThreatResponse'
        '401':
          description: Unauthorized
        '404':
          description: Threat not found
    patch:
      operationId: updateThreat
      summary: McAfee Update threat status
      description: Update the status or assignment of a specific threat, such as marking it as investigating, resolved, or dismissed.
      tags:
      - Threats
      parameters:
      - $ref: '#/components/parameters/threatId'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - threats
                    id:
                      type: string
                    attributes:
                      type: object
                      properties:
                        status:
                          type: string
                          enum:
                          - new
                          - investigating
                          - resolved
                          - dismissed
      responses:
        '200':
          description: Threat updated successfully
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ThreatResponse'
        '401':
          description: Unauthorized
        '404':
          description: Threat not found
components:
  parameters:
    pageLimit:
      name: page[limit]
      in: query
      required: false
      description: Maximum number of results to return per page
      schema:
        type: integer
        default: 20
        maximum: 100
    threatId:
      name: threatId
      in: path
      required: true
      description: Unique threat identifier
      schema:
        type: string
    pageOffset:
      name: page[offset]
      in: query
      required: false
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
  schemas:
    ThreatListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Threat'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaginationMeta:
      type: object
      properties:
        totalCount:
          type: integer
          description: Total number of matching records
        pageLimit:
          type: integer
          description: Current page size limit
        pageOffset:
          type: integer
          description: Current offset
    Threat:
      type: object
      properties:
        id:
          type: string
          description: Unique threat ID
        type:
          type: string
          enum:
          - threats
        attributes:
          type: object
          properties:
            name:
              type: string
              description: Threat name
            severity:
              type: string
              enum:
              - low
              - medium
              - high
              - critical
              description: Threat severity level
            status:
              type: string
              enum:
              - new
              - investigating
              - resolved
              - dismissed
              description: Current threat status
            detectedAt:
              type: string
              format: date-time
              description: Detection timestamp
            hostName:
              type: string
              description: Affected hostname
            processName:
              type: string
              description: Associated process name
            filePath:
              type: string
              description: Associated file path
            sha256:
              type: string
              description: SHA-256 hash of the associated file
            mitreAttackTechnique:
              type: string
              description: MITRE ATT&CK technique ID
    ThreatResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Threat'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using ePO administrator credentials. Credentials are transmitted as a Base64-encoded username:password pair.
externalDocs:
  description: McAfee ePO Web API Reference Guide
  url: https://docs.mcafee.com/bundle/epolicy-orchestrator-web-api-reference-guide