List Alerts API

Retrieve and filter alerts from UTMStack's Elasticsearch index with advanced search capabilities, pagination, and sorting options.

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.

Note: 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

paramintegerrequired

Current page number (starts at 1)

paramintegerrequired

Number of results per page (e.g., 25)

paramintegerrequired

Maximum number of records to retrieve (e.g., 100000000)

paramstringrequired

Elasticsearch index pattern (e.g., alert-*)

paramstring

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

paramstringrequired

Name of the alert field to filter (e.g., "status", "tags", "@timestamp")

paramstringrequired

Filter operator: IS, IS_NOT, IS_BETWEEN, CONTAINS, etc.

paramanyrequired

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

    [
      {
        "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"
        }
      }
    ]

Empty Response

[]

Error Response

    {
      "error": "Invalid filter syntax",
      "message": "Field 'invalid_field' is not recognized",
      "timestamp": "2024-10-16T10:30:00.000Z",
      "status": 400
    }

Response Fields

severityinteger

Alert severity level (1-5, where 5 is highest)

severityLabelstring

Human-readable severity label (Low, Medium, High, Critical)

statusinteger

Alert status code (1=Ignored, 2=Open, 3=In Review, 5=Completed)

statusLabelstring

Human-readable status label

namestring

Alert rule name or title

descriptionstring

Detailed description of the security event

solutionstring

Recommended remediation steps

tacticstring

MITRE ATT&CK tactic classification

categorystring

Alert category classification

dataSourcestring

Source system that generated the alert

@timestampstring

ISO 8601 timestamp when the alert was created

Filter Operators

[Unknown component: details]

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

200OK

Search completed successfully. Returns array of alerts.

400Bad Request

Invalid request parameters or malformed filter syntax.

401Unauthorized

Missing or invalid Bearer token.

403Forbidden

Insufficient permissions to access alerts.

500Internal 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

💡 Tip: For optimal performance, use reasonable size values (25-100) and implement client-side pagination for large result sets.

Performance Considerations

⚠️ Warning: 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