Skip to main content

​
Overview

This endpoint retrieves alerts from UTMStack’s Elasticsearch index. It supports advanced filtering, pagination, and sorting, allowing analysts to query alerts within specific time ranges or by defined conditions.
Authorization Required: All requests must include a valid Bearer Token obtained from the authentication endpoint.

​
Endpoint Details

POST /api/elasticsearch/search

Method: POST
Content-Type: application/json
Authentication: Bearer Token required
Response: Array of alert objects

​
Query Parameters

​
page
integer
required
Current page number (starts at 1)
​
size
integer
required
Number of results per page (e.g., 25)
​
top
integer
required
Maximum number of records to retrieve (e.g., 100000000)
​
indexPattern
string
required
Elasticsearch index pattern (e.g., alert-*)
​
sort
string
Sorting field and direction (e.g., @timestamp,desc)

​
Request Body

The request body is a JSON array of filter definitions used to refine the search.

​
Filter Structure

​
field
string
required
Name of the alert field to filter (e.g., “status”, “tags”, “@timestamp”)
​
operator
string
required
Filter operator: IS, IS_NOT, IS_BETWEEN, CONTAINS, etc.
​
value
any
required
Filter value (string, number, or array for range operations)

​
Example Filter Payload

[
  { 
    "field": "status", 
    "operator": "IS_NOT", 
    "value": 1 
  },
  { 
    "field": "tags", 
    "operator": "IS_NOT", 
    "value": "False positive" 
  },
  { 
    "field": "@timestamp", 
    "operator": "IS_BETWEEN", 
    "value": ["now-7d", "now"] 
  }
]

​
Request & Response Examples

curl -X POST "https://demo.utmstack.com/api/elasticsearch/search?page=1&size=25&top=100000000&indexPattern=alert-*&sort=@timestamp,desc" \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {"field": "status", "operator": "IS_NOT", "value": 1},
    {"field": "tags", "operator": "IS_NOT", "value": "False positive"},
    {"field": "@timestamp", "operator": "IS_BETWEEN", "value": ["now-7d", "now"]}
  ]'

[
  {
    "severity": 3,
    "severityLabel": "High",
    "status": 2,
    "statusLabel": "Open",
    "name": "Windows: Multiple Windows logon failures",
    "description": "Adversaries may use brute force techniques to gain access to accounts when passwords are unknown or when password hashes are obtained.",
    "tactic": "Brute Force",
    "category": "Potentially Malicious Activity",
    "dataSource": "dev-wsrv-2016",
    "@timestamp": "2024-10-15T10:30:00.000Z",
    "source": {
      "ip": "192.168.1.100",
      "hostname": "workstation-01"
    },
    "destination": {
      "ip": "192.168.1.10",
      "hostname": "domain-controller"
    }
  }
]

​
Additional Code Examples

import axios from 'axios';

const searchAlerts = async () => {
  const url = 'https://demo.utmstack.com/api/elasticsearch/search';
  const params = {
    page: 1,
    size: 25,
    top: 100000000,
    indexPattern: 'alert-*',
    sort: '@timestamp,desc'
  };
  
  const filters = [
    { field: 'status', operator: 'IS_NOT', value: 1 },
    { field: 'tags', operator: 'IS_NOT', value: 'False positive' },
    { field: '@timestamp', operator: 'IS_BETWEEN', value: ['now-7d', 'now'] }
  ];

  try {
    const response = await axios.post(url, filters, {
      params,
      headers: {
        'Authorization': 'Bearer <your_access_token>',
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error fetching alerts:', error);
  }
};

​
Response Details

Returns a JSON array of alert objects. Each alert includes metadata, source/destination information, and contextual details.

​
Complete Response Structure

  • Success Response
  • Empty Response
  • Error Response
[
  {
    "severity": 2,
    "severityLabel": "Medium",
    "status": 2,
    "statusLabel": "Open",
    "TagRulesApplied": null,
    "notes": "",
    "dataType": "wineventlog",
    "name": "Windows: Multiple Windows logon failures",
    "description": "Adversaries may use brute force techniques to gain access to accounts when passwords are unknown or when password hashes are obtained.",
    "solution": "Set account lockout policies after a certain number of failed login attempts to prevent passwords from being guessed. Use multi-factor authentication.",
    "statusObservation": "This alert has been evaluated by the tag rules engine",
    "tactic": "Brute Force",
    "category": "Potentially Malicious Activity",
    "dataSource": "dev-wsrv-2016",
    "tags": null,
    "@timestamp": "2024-10-15T10:30:00.000Z",
    "source": {
      "ip": "192.168.1.100",
      "hostname": "workstation-01"
    },
    "destination": {
      "ip": "192.168.1.10",
      "hostname": "domain-controller"
    }
  }
]

​
Response Fields

​
severity
integer
Alert severity level (1-5, where 5 is highest)
​
severityLabel
string
Human-readable severity label (Low, Medium, High, Critical)
​
status
integer
Alert status code (1=Ignored, 2=Open, 3=In Review, 5=Completed)
​
statusLabel
string
Human-readable status label
​
name
string
Alert rule name or title
​
description
string
Detailed description of the security event
​
solution
string
Recommended remediation steps
​
tactic
string
MITRE ATT&CK tactic classification
​
category
string
Alert category classification
​
dataSource
string
Source system that generated the alert
​
@timestamp
string
ISO 8601 timestamp when the alert was created

​
Filter Operators

  • IS: Exact match
  • IS_NOT: Not equal to
  • CONTAINS: Contains substring
  • STARTS_WITH: Begins with value
  • ENDS_WITH: Ends with value
  • GREATER_THAN: Greater than value
  • LESS_THAN: Less than value
  • GREATER_EQUAL: Greater than or equal to
  • LESS_EQUAL: Less than or equal to
  • IS_BETWEEN: Between two values (requires array)
  • IS_IN: Value in list (requires array)
  • IS_NOT_IN: Value not in list (requires array)

​
Common Filter Examples

​
Filter by Severity

[
  { "field": "severity", "operator": "GREATER_EQUAL", "value": 3 }
]

​
Filter by Time Range (Last 24 hours)

[
  { "field": "@timestamp", "operator": "IS_BETWEEN", "value": ["now-24h", "now"] }
]

​
Filter by Multiple Statuses

[
  { "field": "status", "operator": "IS_IN", "value": [2, 3] }
]

​
Filter by Data Source

[
  { "field": "dataSource", "operator": "CONTAINS", "value": "windows" }
]

​
Status Codes

​
200
OK
Search completed successfully. Returns array of alerts.
​
400
Bad Request
Invalid request parameters or malformed filter syntax.
​
401
Unauthorized
Missing or invalid Bearer token.
​
403
Forbidden
Insufficient permissions to access alerts.
​
500
Internal Server Error
Elasticsearch service error or internal server issue.

​
Pagination

The API supports pagination through the page and size parameters:
  • page: Current page number (1-based)
  • size: Number of results per page
  • top: Maximum total results to consider
For optimal performance, use reasonable size values (25-100) and implement client-side pagination for large result sets.

​
Performance Considerations

Performance Tips:
  • Use specific time ranges to limit search scope
  • Apply filters to reduce the result set size
  • Avoid very large top values unless necessary
  • Consider using field-specific filters for better query performance
⌘I