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