New terms rules

New terms rules detect the first appearance of a field value (or combination of field values) within a configurable history window. The rule compares each value it finds during its current execution against a historical baseline, and generates an alert only when the value has never appeared in that baseline period.

New terms rules are the right fit when:

• You want to detect first-seen activity, such as a user logging in from a new country, a process executing for the first time on a host, or a new domain appearing in DNS logs.
• The threat signal is novelty, not a specific pattern or count.
• You want to combine up to three fields to detect novel combinations, such as a host.ip and user.name pair that has never been observed together before.

New terms rules are not the best fit when:

• You are looking for a known bad value. Use a indicator match rule instead.
• You need to detect spikes in volume. Use a threshold rule instead.
• You want statistical anomaly detection without defining explicit fields. Use a machine learning rule instead.

New terms rules require at least one Elasticsearch index pattern or data view with a sufficient history of events. The history window must contain enough data to establish a reliable baseline. A window that is too short leads to excessive false positives as many values appear new.

The following examples use the detections API request format to show how new terms rules are defined. Each example is followed by a field-by-field breakdown.

This rule detects a process executable that has never appeared during the past 30 days.

{
  "type": "new_terms",
  "language": "kuery",
  "name": "First time seen process executable",
  "description": "Detects a process executable that has not appeared in the last 30 days.",
  "query": "event.category: \"process\" and event.type: \"start\"",
  "new_terms_fields": ["process.executable"],
  "history_window_start": "now-30d",
  "index": ["logs-endpoint.events.*"],
  "severity": "medium",
  "risk_score": 47,
  "interval": "5m",
  "from": "now-6m"
}
		

This rule detects a user logging in to a host they have never accessed during the past 14 days.

{
  "type": "new_terms",
  "language": "kuery",
  "name": "First time user login to host",
  "description": "Detects a user and host combination that has not appeared together in the last 14 days.",
  "query": "event.category: \"authentication\" and event.outcome: \"success\"",
  "new_terms_fields": ["user.name", "host.name"],
  "history_window_start": "now-14d",
  "index": ["filebeat-*", "logs-system.*", "winlogbeat-*"],
  "severity": "medium",
  "risk_score": 47,
  "interval": "5m",
  "from": "now-6m"
}
		

The following settings are specific to new terms rules. For settings shared across all rule types, refer to Rule settings reference.

Index patterns or data view

The Elasticsearch indices or data view the rule searches.

Query

The KQL or Lucene query used to filter events before evaluating new terms. Only matching documents are checked for new field values.

Fields

The field (or up to three fields) to check for new terms. When multiple fields are selected, the rule detects novel combinations of their values.

History Window Size

The time range (in minutes, hours, or days) to search for historical occurrences of a term. A term is considered new only if it does not appear in the history window outside of the current rule interval and additional look-back time.

Suppress alerts by (optional)

Reduce repeated or duplicate alerts by grouping them on one or more fields. For details, refer to Alert suppression.

Required fields (optional)

An informational list of fields the rule needs to function. This does not affect rule execution.

Related integrations (optional)

Associate the rule with one or more Elastic integrations to indicate data dependencies and allow users to verify each integration's installation status.