Investigator API

The Investigator API provides read-only access to alerts and detections, enabling integration with security platforms such as SOAR systems for case creation, status synchronization, and third-party data enrichment.

Key features

The Investigator API includes the following features:

• GraphQL-based queries: Provides flexible and precise data retrieval.

• API key authentication: Secure access with API keys fully managed from the Investigator UI.

• Efficient data retrieval: Supports pagination and filtering to manage large datasets.

• SOAR/SIEM integration: Connects with security automation platforms to streamline workflows.

Before you begin

To get started with the Investigator API, you will need the following:

• API Endpoint: The API is accessible at https://api.investigator.corelight.com/graphql.

• Schema: It uses a GraphQL schema to structure queries.

• Authentication: You need an API key for all requests (see the next section).

• Permissions: Your account must have Admin privileges to manage API keys.

• Limit: Be aware that Investigator supports only one active API key. Creating or rotating a key revokes the previous one.

Authentication and API key management

To use the Investigator API, you must authenticate each HTTP request with an API key. You manage this key in the Investigator General Settings and it must be included in the request header.

Note

API key creation, rotation, and revocation are performed in the Investigator UI. Tools like curl, Postman, or GraphQL clients are used only to send authenticated GraphQL queries to the API.

Managing your API key

API keys are managed under General Settings | API Keys in the Investigator UI. You must have admin privileges.

You can:

• Create a new API key to initiate access.

• Rotate an existing key to enhance security or replace an exposed key.

• Revoke a key that’s no longer needed or may have been compromised.

Important

Only one API key can exist at a time. Creating or rotating a key will revoke the previous key. Be sure to update any systems using the old key.

Create an API key

To generate a new API key:

1. Go to System Settings | General Settings.

2. Under API Keys, click New Key.

3. Enter a name or description for the key.

   Read-only permissions for Detections and Alerts are enabled by default in v1.0.0.

4. Click Create Key and save it immediately.

Note

The API key is shown only once. Copy and store it securely.

Rotate an API key

Rotate a key to replace it, such as when it has been exposed or is due for renewal:

1. Go to General Settings | API Keys.

2. Locate your existing key and click the Rotate icon.

3. Click Generate New Key.

Note

The old key is immediately revoked. Systems using it must be updated with the new key. This action cannot be undone.

Revoke an API key

Revoke a key to permanently disable it, especially if it is no longer in use:

1. Go to General Settings | API Keys.

2. Locate the key to revoke.

3. Click the Delete icon and confirm by clicking Revoke Key.

Note

Once revoked, the key is permanently invalid. All requests using it will fail.

Quickstart guide

This Quickstart guide will walk you through making your first successful API call using the provided Python script.

Prerequisites

• You must have Python 3.x installed on your system.

• You need an active API key.

Step 1: Get your API key

Before you begin, you must have an API key. Follow the instructions in the Authentication and API Key Management to create and securely store your key.

Step 2: Save the script

The following Python script queries for alerts, detections, and alert metadata. Copy the following code and save it in a file named quickstart.py.

import requests
import json

# The official endpoint for the Investigator API
GRAPHQL_ENDPOINT = "https://api.investigator.corelight.com/graphql"

# IMPORTANT: Replace "your-api-key" with your actual key below
API_KEY = "your-api-key"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

def run_query(query, variables=None, query_name=""):
    """Sends a GraphQL query and prints the response."""
    print(f"--- Running Query: {query_name} ---")
    payload = {"query": query}
    if variables:
        payload["variables"] = variables

    try:
        response = requests.post(GRAPHQL_ENDPOINT, headers=headers, json=payload, timeout=30)
        response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
        print(json.dumps(response.json(), indent=2))
    except requests.exceptions.HTTPError as http_err:
        print(f"HTTP error occurred: {http_err}")
        print(f"Response Text: {response.text}")
    except Exception as err:
        print(f"An error occurred: {err}")
    finally:
        print("-" * (len(query_name) + 20) + "\n")


# 1. Query: alerts
alerts_query = """
query Alerts($alert_filter: AlertFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  alerts(alert_filter: $alert_filter, offset: $offset, size: $size, sort: $sort) {
    alerts {
      alert_id
      alert_info { alert_name alert_type content_id }
      alert_timestamp { start end observed ttl }
      score
      false_positive
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}
"""
alerts_variables = {
    "alert_filter": {
        "score": {"gte": 5},
        "alert_info_list": [{"alert_name": "Suspicious Login"}]
    },
    "offset": 0,
    "size": 5,
    "sort": [{"sort_by": "score", "sort_dir": "desc"}]
}
run_query(alerts_query, alerts_variables, query_name="Alerts")

# 2. Query: detections
detections_query = """
query Detections($detection_filter: DetectionFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  detections(detection_filter: $detection_filter, offset: $offset, size: $size, sort: $sort) {
    detections {
      detection_id
      alert_info { alert_name alert_type content_id }
      alert_entity { entity_id entity_name entity_type entity_category }
      detection_status
      detection_timestamp { start end }
      rank { severity }
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}
"""
detections_variables = {
    "detection_filter": {
        "severity": {"gte": 3},
        "detection_statuses": ["open"]
    },
    "offset": 0,
    "size": 5,
    "sort": [{"sort_by": "detection_id", "sort_dir": "asc"}]
}
run_query(detections_query, detections_variables, query_name="Detections")

# 3. Query: alertMetadataList
alert_metadata_query = """
query AlertMetadataList($alert_metadata_filter: AlertMetadataFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  alertMetadataList(alert_metadata_filter: $alert_metadata_filter, offset: $offset, size: $size, sort: $sort) {
    alert_metadata_list {
      id
      title
      content_id
      severity
      active
      category
      updated_timestamp
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}
"""
alert_metadata_variables = {
    "alert_metadata_filter": {
        "active_statuses": [True],
        "severity": {"gte": 2}
    },
    "offset": 0,
    "size": 5,
    "sort": [{"sort_by": "updated_timestamp", "sort_dir": "desc"}]
}
run_query(alert_metadata_query, alert_metadata_variables, query_name="Alert Metadata")

Step 3: Configure your API key

Open quickstart.py in an editor and replace the placeholder your-api-key with the key you generated.

Step 4: Run the script

Open your terminal, navigate to the directory where you saved the file, and run:

python quickstart.py

Step 5: Review the results

The script prints three JSON objects to your console for Alerts, Detections, and Alert Metadata. This confirms you have successfully connected to the Investigator API. You can now adapt this script for your own use cases.

Common use cases and workflows

This section provides examples of how the Investigator API can integrate into common security workflows.

SOAR integration for case management

Goal: Automatically create and update cases in a SOAR platform like Splunk SOAR, Palo Alto XSOAR, or Torq.

Target Audience: SOAR Engineer, Automation Specialist.

Workflow:

1. Periodically poll the detections query for new items where detection_status is open. You can use the earliest_start_timestamp filter to avoid re-fetching old data.

2. For each new detection, use its detection_id, alert_info, alert_entity, and rank.severity to create a new case in your SOAR.

3. Store the mapping between the detection_id and your SOAR case ID. This allows you to synchronize status updates or add new alerts to existing cases later.

SIEM data enrichment

Goal: Add deeper context to events in your SIEM (for example, Splunk, Elastic, Microsoft Sentinel).

Target Audience: Security Analyst, SIEM Engineer.

Workflow:

1. When a notable event involving a specific IP address or hostname appears in your SIEM, trigger an enrichment script.

2. The script calls the alerts query, using the alert_entity_list filter to find all other Investigator alerts involving that same entity.

3. The results can be added back to the original SIEM event as comments or appended data, giving your analysts immediate access to related Corelight findings without leaving their primary tool.

Custom triage with dashboards or notifications

Goal: Build a custom dashboard or notification system to highlight the most critical threats first.

Target Audience: Detection Engineer, Security Operations Lead.

Workflow:

1. Regularly query the detections endpoint, sorting the results by rank.severity in descending order ("sort_dir": "desc").

2. In your application, you can apply additional business logic. For example, you could increase the priority of a high-severity detection if the alert_entity involved is tagged as a high-value asset in your environment.

3. Send a high-priority notification (for exaple, to Slack or PagerDuty) with key details and a link back to the detection in the Investigator UI.

Making API requests

You can call the Investigator API by sending a POST request to the GraphQL endpoint using any HTTP client that supports JSON.

Required headers

• Authorization: Bearer YOUR_API_KEY

• Content-Type: application/json

Sample curl request

This example sends a simple query to fetch the alert_id and score for the 10 most recent alerts.

curl -X POST https://api.investigator.corelight.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { alerts(offset: 0, size: 10) { alerts { alert_id score } } }"
  }'

Common tools

The following tools are commonly used to send GraphQL requests to the Investigator API:

• Command line: curl

• GUI-based: Postman (use the GraphQL tab)

• GraphQL clients: Altair, Insomnia

Rate limits

To ensure fair usage and API stability, the Investigator API enforces the following rate limits:

• Per minute: 100 requests

• Per hour: 1500 requests

• Per day: 36,000 requests

Exceeding these returns a 429 Too Many Requests with a Retry-After header.

Note

Only successful requests count against the rate limit.

Error handling

The API uses standard HTTP status codes to indicate success or failure. Common responses include:

• 400 Bad Request: Malformed syntax

• 401 Unauthorized: Missing/invalid key

• 403 Forbidden: Insufficient permissions

• 429 Too Many Requests: Rate limit hit

API reference

This reference provides detailed information on all available queries, the objects they return, and the data structures. The Investigator API provides queries for retrieving alerts, detections, and alert metadata with filtering, pagination, and sorting capabilities.

The system supports multiple alert types including:

• SuricataAlert: Alerts from the Suricata network security tool.

• MlAlert: Alerts from supervised machine learning models.

• CustomSearchRuleAlert: Alerts generated from user-defined search rules.

• YaraAlert: Alerts from Yara for malware detection.

• AnomalyAlert: Alerts from unsupervised machine learning for anomaly detection.

• NoticeAlert: Alerts from Zeek Notices.

Alerts query

Retrieves a list of alerts. An Alert is an interface that represents a single security event. Specific alert types (like SuricataAlert, NoticeAlert, AnomalyAlert, CustomSearchRuleAlert, MlAlert, and YaraAlert) implement this interface and may have additional fields.

Parameters

The following table describes the available parameters for filtering, paginating, and sorting alert results.

Parameter	Type	Description
alert_filter	AlertFilterInput	An object containing filters for the query, such as by alert info, entities, timestamp, or score.
offset	Integer	The number of items to skip for pagination. Defaults to 0.
size	Integer	The number of items to return per page. Max 100, defaults to 10.
sort	[SortParameterInput]	An array of objects to define sorting. Defaults to timestamp descending.

Request

The following GraphQL query example retrieves the first five alerts with a score greater than or equal to 5, filtered by a specific alert name, and sorted by score.

query Alerts($alert_filter: AlertFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  alerts(alert_filter: $alert_filter, offset: $offset, size: $size, sort: $sort) {
    alerts {
      alert_id
      alert_info { alert_name alert_type content_id }
      alert_timestamp { start end observed ttl }
      score
      false_positive
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}

Variables

This object defines the parameters used in the GraphQL query above, allowing for dynamic filtering, pagination, and sorting of alerts.

{
  "alert_filter": {
    "score": {
      "gte": 5
    },
    "alert_info_list": [
      {
        "alert_name": "ETPRO JA3 Hash - Possible Ligolo Server/Golang Binary Response"
      }
    ]
  },
  "offset": 0,
  "size": 5,
  "sort": [
    {
      "sort_by": "score",
      "sort_dir": "desc"
    }
  ]
}

Response

Example response showing a subset of the alert objects to illustrate structure and key fields.

{
  "data": {
    "alerts": {
      "alerts": [
        {
          "alert_id": "cff115c9-1354-4995-bbaa-c248ecd36b36",
          "alert_info": {
            "alert_name": "ETPRO JA3 Hash - Possible Ligolo Server/Golang Binary Response",
            "alert_type": "suricata_corelight",
            "content_id": "SURI-2850023"
          },
          "alert_timestamp": {
            "start": 1742770313,
            "end": 1742770313,
            "observed": 1742770313,
            "ttl": 1750546313
          },
          "score": 6,
          "false_positive": false
        }
      ],
      "page_info": {
        "offset": 0,
        "size": 5,
        "total_items": 9999,
        "sort": [
          {
            "sort_by": "score",
            "sort_dir": "desc"
          }
        ]
      }
    }
  }
}

Detections query

Retrieves a list of detection objects, which are higher-level correlated security incidents.

Parameters

The following table describes the available parameters for filtering, paginating, and sorting detection results.

Parameter	Type	Description
detection_filter	DetectionFilterInput	An object containing filters for the query, such as status, severity, timestamps, assignees, or associated alert info.
offset	Integer	The number of items to skip for pagination. Defaults to 0.
size	Integer	The number of items to return per page. Max 100, defaults to 10.
sort	[SortParameterInput]	An array of objects to define sorting.

Request

The following query example retrieves open detections with a severity of 3 or higher, sorted by their ID.

query Detections($detection_filter: DetectionFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  detections(detection_filter: $detection_filter, offset: $offset, size: $size, sort: $sort) {
    detections {
      detection_id
      alert_info { alert_name alert_type content_id }
      alert_entity { entity_id entity_name entity_type entity_category }
      detection_status
      detection_timestamp { start end }
      rank { severity }
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}

Variables

This object specifies the parameters for the detection query, including filters for severity and status, as well as pagination and sorting options.

{
  "detection_filter": {
    "severity": {
      "gte": 3
    },
    "detection_statuses": [
      "open"
    ]
  },
  "offset": 0,
  "size": 5,
  "sort": [
    {
      "sort_by": "detection_id",
      "sort_dir": "asc"
    }
  ]
}

Response

Example response showing a subset of the detection objects to illustrate structure and key fields.

{
  "data": {
    "detections": {
      "detections": [
        {
          "detection_id": "1ca01fd03b64be883b707b39383f1d80",
          "alert_info": {
            "alert_name": "SSL::Invalid_Server_Cert",
            "alert_type": "notice",
            "content_id": "SSL::Invalid_Server_Cert"
          },
          "alert_entity": {
            "entity_id": "IP10.2.128.138",
            "entity_name": "10.2.128.138",
            "entity_type": "IP",
            "entity_category": "source"
          },
          "detection_status": "open",
          "detection_timestamp": {
            "start": 1749881040,
            "end": 9223372036854776000
          },
          "rank": {
            "severity": 4
          }
        }
      ],
      "page_info": {
        "offset": 0,
        "size": 5,
        "total_items": 7,
        "sort": [
          {
            "sort_by": "detection_id",
            "sort_dir": "asc"
          }
        ]
      }
    }
  }
}

AlertMetadataList query

Retrieves a list of alert metadata definitions, which describe the nature of different alert types.

Parameters

The following table describes the available parameters for filtering, paginating, and sorting Alert Metadata definitions.

Parameter	Type	Description
alert_metadata_filter	AlertMetadataFilterInput	An object containing filters for the query, including titles, content IDs, status, category, and severity.
offset	Integer	The number of items to skip for pagination. Defaults to 0.
size	Integer	The number of items to return per page. Max 100, defaults to 10.
sort	[SortParameterInput]	An array of objects to define sorting.

Request

The following query example retrieves active AlertMetadataList definitions with a severity of 2 or higher, sorted by the most recently updated.

query AlertMetadataList($alert_metadata_filter: AlertMetadataFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  alertMetadataList(alert_metadata_filter: $alert_metadata_filter, offset: $offset, size: $size, sort: $sort) {
    alert_metadata_list {
      id
      title
      content_id
      severity
      active
      category
      updated_timestamp
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}

Variables

This object provides the parameters for the AlertMetadataList query, allowing for filtering by active status and severity, alongside pagination and sorting.

{
  "alert_metadata_filter": {
    "active_statuses": [
      true
    ],
    "severity": {
      "gte": 2
    }
  },
  "offset": 0,
  "size": 5,
  "sort": [
    {
      "sort_by": "updated_timestamp",
      "sort_dir": "desc"
    }
  ]
}

Response

Example response showing a subset of the metadata objects to illustrate structure and key fields.

{
  "data": {
    "alertMetadataList": {
      "alert_metadata_list": [
        {
          "id": "847f532b-ad34-4c1f-b40f-e6c2fc260f35",
          "title": "MOVEit Authentication bypass SSH",
          "content_id": "847f532b-ad34-4c1f-b40f-e6c2fc260f35",
          "severity": 10,
          "active": true,
          "category": null,
          "updated_timestamp": 1749578764
        }
      ],
      "page_info": {
        "offset": 0,
        "size": 5,
        "total_items": 51016,
        "sort": [
          {
            "sort_by": "updated_timestamp",
            "sort_dir": "desc"
          }
        ]
      }
    }
  }
}

Response type reference

This section uses clear tables to show each API object’s fields, types, and descriptions.

Top-level objects

This table shows the main data returned by the alerts, detections, and alertMetadataList queries.

Object	Attribute	Type	Description
Alerts	alerts	[Alert]	An array of alert objects.
	page_info	PageInfo	Pagination information for the result set.
Detections	detections	[Detection]	An array of detection objects.
	page_info	PageInfo	Pagination information for the result set.
AlertMetadataList	alert_metadata_list	[AlertMetadata]	An array of alert metadata objects.
	page_info	PageInfo	Pagination information for the result set.

Alert object

The following table describes the fields returned for the Alert object.

Attribute	Type	Description
alert_entity	AlertEntity	The primary entity (e.g., IP, Host) associated with the alert.
alert_id	String!	Unique identifier for the alert. A ! indicates this field is non-nullable.
alert_info	AlertInfo	An object containing the alert name, type, and content ID.
alert_timestamp	AlertTimestamp	An object containing start, end, observed, and TTL timestamps.
destination_entities	[AlertEntity]	A list of entities that were the destination in the alert.
event_ids	[String]	A list of event identifiers associated with the alert.
false_positive	Boolean	Indicates if the alert has been marked as a false positive.
mitre_tactics	[String]	A list of MITRE ATT&CK tactic IDs associated with the alert.
mitre_techniques	[String]	A list of MITRE ATT&CK technique IDs associated with the alert.
related_entities	[AlertEntity]	A list of other entities related to this alert.
score	Float	The calculated severity score of the alert.
source_entities	[AlertEntity]	A list of entities that were the source in the alert.

Detection object

The following table describes the fields returned for the Detection object.

Attribute	Type	Description
alert_entity	AlertEntity!	The primary entity associated with the detection.
alert_info	AlertInfo!	The primary alert information that defines the detection.
assignment_info	DetectionAssignmentInfo	Information on which user is assigned to this detection.
created_timestamp	Float!	The Unix timestamp when the detection was first created.
detection_id	String!	Unique identifier for the detection.
detection_status	DetectionStatus!	The workflow status of the detection (e.g., open, closed).
detection_timestamp	DetectionTimestamp!	The start and end time of the detection window.
earliest_start_timestamp	Float	The earliest start time among all alerts within the detection.
escalation_data	DetectionEscalationData	Information related to the escalation of the detection.
latest_start_timestamp	Float	The latest start time among all alerts within the detection.
mitre_mappings	MitreMappings	MITRE ATT&CK tactic and technique information for the detection.
mitre_tactics	[String]	A list of MITRE ATT&CK tactic IDs associated with the detection.
mitre_techniques	[String]	A list of MITRE ATT&CK technique IDs associated with the detection.
rank	DetectionRank!	An object containing the detection’s severity level.
total_alert_count	Int!	The total number of alerts grouped within this detection.
update_info	DetectionUpdateInfo	Information about when the detection was last updated and by whom.

AlertMetadata object

The following table describes the fields returned for the AlertMetadata object.

Attribute	Type	Description
active	Boolean	Whether this alert rule is currently active and generating alerts.
author	String	Author of the alert definition.
category	String	The category of the alert (e.g., suricata_corelight).
content_doc	AlertDocumentation	An object containing guidance for alert handling.
content_id	String	A unique content identifier for the alert type.
cve_reference	String	CVE reference if applicable.
date	String	Creation date of the metadata.
description	String	A detailed description of what the alert signifies.
id	String	Unique identifier for the metadata entry.
mitre_mappings	MitreMappings	MITRE ATT&CK tactic and technique information.
references	[String]	A list of reference links.
rule	String	The underlying alert rule definition.
severity	Int	The default severity level of the alert, from 1-10.
severity_info	SeverityInfo	An object containing detailed severity settings.
status	String	The status of the metadata entry.
title	String	The human-readable name of the alert rule.
updated_by	String	User who last updated the metadata.
updated_timestamp	Float	The Unix timestamp of the last update to this definition.

Common and supporting types

The following table lists shared types and enums used across multiple responses (e.g. PageInfo, AlertStatus).

Object	Attribute	Type	Description
AlertEntity	entity_id	String	A unique system ID for the entity.
	entity_name	String	The value of the entity (e.g., "192.168.1.100").
	entity_type	String	The type of entity (e.g., IP, HOST, DOMAIN).
	entity_category	EntityCategory	Whether the entity was the source or destination.
AlertInfo	alert_name	String	The display name of the alert.
	alert_type	String	The source of the alert (e.g., suricata_corelight).
	content_id	String	A unique content identifier for the alert type.
DetectionRank	is_custom_severity	Boolean	Indicates if a custom severity is being used.
	severity	Int!	The severity level of the detection.
PageInfo	offset	Int	The current offset in the result set.
	size	Int	The number of items returned in the current page.
	total_items	Int	The total number of items available for the query.
	sort	[SortParameter]	The sorting parameters applied to the query.

API schema

This schema defines the public APIs for Investigator. It provides queries for retrieving alerts, detections, and alert metadata with filtering, pagination, and sorting capabilities.

The system supports multiple alert types including:

• Suricata alerts: Suricata network security alerts.

• ML-based alerts: Alerts generated by supervised machine learning models.

• Custom search rule alerts: Alerts from custom search rules.

• Yara alerts: Malware detection alerts using Yara rules.

• Anomaly alerts: Alerts from unsupervised anomaly detection systems.

• Notice alerts: Alerts from Zeek notices.

Root queries

This section defines the top-level GraphQL queries available in the Investigator API, serving as the entry points for data retrieval.

"""
Root query type containing all available queries
All queries require API key authentication
"""
type Query {
  """
  Retrieve alerts with optional filtering, pagination, and sorting
  Args:
    alert_filter: Optional filter criteria for alerts
    offset: Number of items to skip (for pagination)
    size: Number of items to return (for pagination)
    sort: Array of sort parameters
  Returns:
    Alerts object containing alert list and pagination info
  """
  alerts(alert_filter: AlertFilterInput, offset: Int, size: Int, sort: [SortParameterInput]): Alerts @api_key

  """
  Retrieve detections with optional filtering, pagination, and sorting
  Args:
    detection_filter: Optional filter criteria for detections
    offset: Number of items to skip (for pagination)
    size: Number of items to return (for pagination)
    sort: Array of sort parameters
  Returns:
    Detections object containing detection list and pagination info
  """
  detections(detection_filter: DetectionFilterInput, offset: Int, size: Int, sort: [SortParameterInput]): Detections @api_key

  """
  Retrieve alert metadata with optional filtering, pagination, and sorting
  Args:
    alert_metadata_filter: Optional filter criteria for alert metadata
    offset: Number of items to skip (for pagination)
    size: Number of items to return (for pagination)
    sort: Array of sort parameters
  Returns:
    AlertMetadataList object containing metadata list and pagination info
  """
  alertMetadataList(alert_metadata_filter: AlertMetadataFilterInput, offset: Int, size: Int, sort: [SortParameterInput]): AlertMetadataList @api_key
}

Alert object types and related inputs

This section contains the Alert interface, all concrete alert types that implement it, and all related helper types, inputs, and enums.

Alert Interface and implementations

These are the primary objects that represent security alerts, including the base Alert interface and its various specialized implementations.

"""Container for alert list with pagination information"""
type Alerts {
  """Array of alert objects"""
  alerts: [Alert]
  """Pagination information for the result set"""
  page_info: PageInfo
}

"""Base interface for all alert types"""
interface Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  related_entities: [AlertEntity]
  score: Float
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Anomaly detection alert implementation"""
type AnomalyAlert implements Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  related_entities: [AlertEntity]
  score: Float
  source_ids: [String]
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
  path: String
  system_name: String
  uid: String
  orig_h: String
  source_ip: String
  destination_ip: String
  usecase: String
  usecase_description: String
  entity: String
  original_entity: String
  entity_training_items: [String]
  item: String
  item_score: Float
  item_assoc_entities: [String]
  item_assoc_entities_similarity: [Float]
  ignorable: Boolean
  anomaly_type: String
  baselining_start_timestamp: Float
  baselining_end_timestamp: Float
  nn1_entities: [String]
  nn1_entity_similarity: Float
  nn1_train_items: [String]
  nn1_pred_items: [String]
  nn2_entities: [String]
  nn2_entity_similarity: Float
  nn2_train_items: [String]
  nn2_pred_items: [String]
  nn3_entities: [String]
  nn3_entity_similarity: Float
  nn3_train_items: [String]
  nn3_pred_items: [String]
  nn4_entities: [String]
  nn4_entity_similarity: Float
  nn4_train_items: [String]
  nn4_pred_items: [String]
  nn5_entities: [String]
  nn5_entity_similarity: Float
  nn5_train_items: [String]
  nn5_pred_items: [String]
  nn6_entities: [String]
  nn6_entity_similarity: Float
  nn6_train_items: [String]
  nn6_pred_items: [String]
  nn7_entities: [String]
  nn7_entity_similarity: Float
  nn7_train_items: [String]
  nn7_pred_items: [String]
  nn8_entities: [String]
  nn8_entity_similarity: Float
  nn8_train_items: [String]
  nn8_pred_items: [String]
  nn9_entities: [String]
  nn9_entity_similarity: Float
  nn9_train_items: [String]
  nn9_pred_items: [String]
  nn10_entities: [String]
  nn10_entity_similarity: Float
  nn10_train_items: [String]
  nn10_pred_items: [String]
}

"""Custom search rule alert implementation"""
type CustomSearchRuleAlert implements Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  related_entities: [AlertEntity]
  score: Float
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Machine learning alert implementation"""
type MlAlert implements Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  average_technique_score_map: JSONSTRING
  description: String
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  mode: String
  models: [MLModels]
  pipeline: String
  related_entities: [AlertEntity]
  score: Float
  status: String
  tag_id: String
  user_tag: JSONSTRING
  whitelisted_info: [MLWhiteListEntry]
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Notice alert implementation"""
type NoticeAlert implements Alert {
  actions: [String]
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  destination_ip: String
  dropped: String
  dst: String
  event_ids: [String]
  false_positive: Boolean
  file_desc: String
  file_mime_type: String
  fuid: String
  mitre_tactics: [String]
  mitre_techniques: [String]
  msg: String
  n: String
  note: String
  orig_h: String
  orig_p: Int
  p: Int
  path: String
  peer_descr: String
  proto: String
  related_entities: [AlertEntity]
  remote_location: RemoteLocation
  resp_h: String
  resp_p: Int
  score: Float
  severity_info: Severity
  source_ids: [String]
  source_ip: String
  src: String
  sub: String
  suppress_for: Float
  system_name: String
  uid: String
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Suricata alert implementation"""
type SuricataAlert implements Alert {
  action: String
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  category: String
  community_id: String
  destination_ip: String
  destination_port: Int
  event_ids: [String]
  false_positive: Boolean
  flow_id: Float
  gid: Int
  metadata: [SuricataMetadata]
  mitre_tactics: [String]
  mitre_techniques: [String]
  pcap_cnt: Int
  payload: String
  related_entities: [AlertEntity]
  rev: Int
  score: Float
  service: String
  signature_id: String
  source_ids: [String]
  source_ip: String
  source_port: Int
  suri_id: String
  tx_id: Int
  uid: String
  xff: String
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Yara alert implementation"""
type YaraAlert implements Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  related_entities: [AlertEntity]
  score: Float
  source_ids: [String]
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
  path: String
  system_name: String
  uid: String
  orig_h: String
  orig_p: Int
  resp_h: String
  resp_p: Int
  fuid: String
  file_name: String
  source: String
  mime_type: String
  md5: String
  sha1: String
  sha256: String
  source_ip: String
  destination_ip: String
}

Alert helper object definitions

These types are used within the various Alert objects to provide structured information about entities, timestamps, and other alert-related details.

"""Entity information for alerts"""
type AlertEntity {
  entity_id: String
  entity_name: String
  entity_type: String
  entity_category: EntityCategory
}

"""Basic alert information"""
type AlertInfo {
  alert_name: String
  alert_type: String
  content_id: String
}

"""Timestamp information for alerts"""
type AlertTimestamp {
  end: Float
  observed: Float
  start: Float
  ttl: Float
}

"""Session summary for alert investigation"""
type AlertSessionSummary {
  ioc: [String]
  alert_summary: [String]
  alert_beacons: [String]
  unusual_findings: [String]
  attack_tactics: [String]
}

"""ML model information"""
type MLModels {
  features: [MLFeatures]
  model_alias: [String]
  model_name: String
  model_score: Float
  predicted_tag_id: String
}

"""ML feature information"""
type MLFeatures {
  actual: Float
  contribution: Float
  difference: Float
  feature_name: String
}

"""ML whitelist entry"""
type MLWhiteListEntry {
  entity_name: String
  whitelisted: Boolean
  whitelisted_for: String
}

"""Remote location information for Notice alerts"""
type RemoteLocation {
  city: String
  country_code: String
  lattitude: String
  longitude: String
  region: String
}

"""Severity information for Notice alerts"""
type Severity {
  level: Int
  name: String
}

"""Suricata metadata"""
type SuricataMetadata {
  key: String
  val: String
}

Alert query input parameters

Use these input types to define comprehensive filtering, pagination, and sorting criteria for alert queries.

"""Comprehensive filtering options for alert searches"""
input AlertFilterInput {
  alert_ids: [String]
  alert_info_list: [AlertInfoInput]
  alert_entity_list: [AlertEntityInput]
  alert_timestamp: AlertTimestampInput
  score: IntRangeInput
}

"""Input type for alert information filtering"""
input AlertInfoInput {
  alert_name: String
  alert_type: AlertType
  content_id: String
}

"""Input type for alert entity filtering"""
input AlertEntityInput {
  entity_id: String
  entity_name: String
  entity_type: String
  entity_category: EntityCategory
}

"""Input type for alert timestamp filtering"""
input AlertTimestampInput {
  start: FloatRangeInput
  end: FloatRangeInput
}

Alert-specific enumerations

Enumerations related to alert types and entities.

"""Enumeration of supported alert types"""
enum AlertType {
  suricata_corelight
  notice
  ml
  custom_search_rule
  yara_corelight
  anomaly
}

"""Enumeration of supported entity types"""
enum AlertEntityType {
  DOMAIN
  HOST
  IP
  IP_RANGE
  MAC
  USER
}

"""Enumeration of entity categories"""
enum EntityCategory {
  source
  destination
}

Detection object types and related inputs

This section covers the Detection object, which represents a collection of related alerts, and its associated types.

Detection object definitions

These objects define the structure of detections and their associated information, including assignment, escalation, and ranking.

"""Container for detection list with pagination information"""
type Detections {
  detections: [Detection]
  page_info: PageInfo
}

"""Detection object representing a collection of related alerts"""
type Detection {
  detection_id: String!
  alert_info: AlertInfo!
  alert_entity: AlertEntity!
  assignment_info: DetectionAssignmentInfo
  created_timestamp: Float!
  detection_status: DetectionStatus!
  detection_timestamp: DetectionTimestamp!
  earliest_start_timestamp: Float
  escalation_data: DetectionEscalationData
  latest_start_timestamp: Float
  mitre_mappings: MitreMappings
  mitre_tactics: [String]
  mitre_techniques: [String]
  rank: DetectionRank!
  total_alert_count: Int!
  update_info: DetectionUpdateInfo
}

"""Assignment information for detections"""
type DetectionAssignmentInfo {
  assigned_to_user_alias: String
  assigned_to_username: String
  assigned_at: Float
}

"""Escalation data for detections"""
type DetectionEscalationData {
  escalation_status: Boolean
  escalated_by_user_alias: String
  escalated_timestamp: Float
  escalation_service_name: EscalationServiceNameEnum
}

"""Detection rank information"""
type DetectionRank {
  is_custom_severity: Boolean
  severity: Int!
}

"""Timestamp information for detections"""
type DetectionTimestamp {
  start: Float!
  end: Float
}

"""Update information for detections"""
type DetectionUpdateInfo {
  last_updated_by: String
  last_updated_by_username: String
  last_updated_timestamp: Float
}

Detection query input parameters

These input types provide comprehensive options for filtering and managing detection searches, including by status, severity, and timestamps.

"""Comprehensive filtering options for detection searches"""
input DetectionFilterInput {
  detection_ids: [String]
  earliest_start_timestamp: FloatRangeInput
  latest_start_timestamp: FloatRangeInput
  detection_statuses: [DetectionStatus]
  severity: IntRangeInput
  assignees: DetectionAssigneesInput
  alert_info_list: [AlertInfoInput]
  sources: [String]
  destinations: [String]
}

"""Input type for detection assignee filtering"""
input DetectionAssigneesInput {
  unassigned: Boolean
  assigned_to_usernames: [String]
}

Detection-specific enumerations

Enumerations related to detection statuses and escalation services.

"""Enumeration of detection status values"""
enum DetectionStatus {
  OPEN
  CLOSED
}

"""Enumeration of supported escalation service names"""
enum EscalationServiceNameEnum {
  servicenow
}

AlertMetadataList object types and related inputs

This section details the metadata associated with alerts, such as documentation, MITRE ATT&CK mappings, and severity overrides.

AlertMetadataList object definitions

These objects define the structure of alert metadata entries, including rule definitions, documentation, and severity information.

"""Container for alert metadata list with pagination information"""
type AlertMetadataList {
  alert_metadata_list: [AlertMetadata]
  page_info: PageInfo
}

"""Comprehensive alert metadata"""
type AlertMetadata {
  active: Boolean
  author: String
  content_id: String
  category: String
  cve_reference: String
  data: String
  date: String
  description: String
  fields: [String]
  id: String
  level: String
  logsource: MetadataLogSource
  managed_by: String
  mitre_mappings: MitreMappings
  references: [String]
  related: [MetadataRelated]
  severity: Int
  severity_description: String
  status: String
  tags: [String]
  title: String
  rule: String
  updated_by: String
  updated_by_alias: String
  updated_timestamp: Float
  content_doc: AlertDocumentation
  severity_info: SeverityInfo
  alert_next_steps: String
  pivot_query: String
  match_meta: [String]
}

"""Documentation for alert investigation and response"""
type AlertDocumentation {
  significance: String
  validation: String
  nextsteps: String
  queries: String
}

"""Severity information with custom settings"""
type SeverityInfo {
  custom_severity: Int
  custom_severity_enabled: Boolean
  default_severity: Int
  last_updated_by_user_alias: String
  last_updated_by_username: String
  last_updated_timestamp: Float
}

"""Related metadata information"""
type MetadataRelated {
  id: String
  title: String
  type: String
}

"""Log source metadata"""
type MetadataLogSource {
  category: String
  product: String
  service: String
}

"""Event strategy metadata"""
type MetadataEventStrategy {
  attack_probability_threshold: Float
  method: String
  predicted_tag_id: String
  alert_sid: String
}

"""MITRE ATT&CK mappings"""
type MitreMappings {
  tactics: [MitreTactics]
}

"""MITRE ATT&CK tactics"""
type MitreTactics {
  link: String
  name: String
  tag: String
  techniques: [MitreTechniques]
}

"""MITRE ATT&CK techniques"""
type MitreTechniques {
  link: String
  name: String
  subtechniques: [MitreSubtechniques]
  tag: String
}

"""MITRE ATT&CK sub-techniques"""
type MitreSubtechniques {
  link: String
  name: String
  tag: String
}

AlertMetadataList query input parameters

Use these input types to define filtering criteria for retrieving alert metadata definitions.

"""Filter input for alert metadata queries"""
input AlertMetadataFilterInput {
  alert_metadata_ids: [String]
  titles: [String]
  content_ids: [String]
  active_statuses: [Boolean]
  categories: [SetAlertStatusType]
  severity: IntRangeInput
}

AlertMetadataList-specific enumerations

This section defines enumerations used for alert metadata, such as types for setting alert status.

"""Enumeration of alert status types for setting alert status"""
enum SetAlertStatusType {
  suricata_corelight
  notice
  ml_results
  custom_search_rule
  yara_corelight
  anomaly
}

Shared API components and utility types

These are general-purpose directives, scalars, and types used across the API.

API directives and scalar types

This section describes special GraphQL constructs that modify query behavior or represent custom data formats.

"""All queries require API key authentication"""
directive @api_key on FIELD_DEFINITION

"""Custom scalar for JSON data represented as a string"""
scalar JSONSTRING

Common object and input type definitions

These types are shared across API queries and responses, providing consistent structures for pagination, sorting, and range filtering.

"""Pagination information for query results"""
type PageInfo {
  offset: Int
  size: Int
  total_items: Int
  sort: [SortParameter]
}

"""Sort parameter information"""
type SortParameter {
  sort_by: String!
  sort_dir: String!
}

"""Input type for sort parameters"""
input SortParameterInput {
  sort_by: String!
  sort_dir: String!
}

"""Input type for integer range filtering"""
input IntRangeInput {
  gt: Int
  gte: Int
  lt: Int
  lte: Int
}

"""Input type for float range filtering"""
input FloatRangeInput {
  gt: Float
  gte: Float
  lt: Float
  lte: Float
}