﻿---
title: New terms rules
description: Create detection rules that alert when a field value appears for the first time in a history window.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5539/solutions/security/detect-and-alert/new-terms
products:
  - Elastic Cloud Serverless
  - Elastic Security
applies_to:
  - Serverless Security projects: Generally available
  - Elastic Stack: Generally available
---

# 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.

### When to use a new terms rule

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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5539/solutions/security/detect-and-alert/indicator-match) instead.
- You need to detect spikes in volume. Use a [threshold rule](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5539/solutions/security/detect-and-alert/threshold) instead.
- You want statistical anomaly detection without defining explicit fields. Use a [machine learning rule](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5539/solutions/security/detect-and-alert/machine-learning) instead.


### Data requirements

New terms rules require at least one Elasticsearch index pattern or [data view](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5539/solutions/security/get-started/data-views-elastic-security) 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.

## Annotated examples

The following examples use the [detections API](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5539/solutions/security/detect-and-alert/using-the-api) request format to show how new terms rules are defined. Each example is followed by a breakdown of the new terms-specific fields. For common fields like `name`, `severity`, and `interval`, refer to the [detections API documentation](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-detection-engine-rules-api).

### Single-field detection: first-seen process

This rule detects a process executable that has never appeared during the past 30 days.
```json
{
  "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"
}
```


| Field                  | Value                                               | Purpose                                                                                                                                                                                                                                                                  |
|------------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type`                 | `"new_terms"`                                       | Identifies this as a new terms rule.                                                                                                                                                                                                                                     |
| `query`                | `event.category: "process" and event.type: "start"` | A KQL filter applied before evaluating new terms. Only process-start events are checked for new values. Uses `"kuery"` or `"lucene"`, the same query languages available in custom query rules.                                                                          |
| `new_terms_fields`     | `["process.executable"]`                            | The field to monitor for new values. An alert fires when a `process.executable` value appears that was never seen in the history window. Accepts 1-3 fields.                                                                                                             |
| `history_window_start` | `"now-30d"`                                         | Looks back 30 days to build the baseline of known values. A term is considered new only if it does not appear anywhere in this window. Supports relative dates such as `now-7d` or `now-90d`. Avoid absolute dates because they cause the query range to grow over time. |


### Multi-field detection: new user-host pair

This rule detects a user logging in to a host they have never accessed during the past 14 days.
```json
{
  "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"
}
```


| Field                  | Value                        | Purpose                                                                                                                                                                                                                              |
|------------------------|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `new_terms_fields`     | `["user.name", "host.name"]` | Monitors the combination of user and host. An alert fires when a `user.name` + `host.name` pair appears that has never been seen together in the history window, even if both values are individually known. Accepts up to 3 fields. |
| `history_window_start` | `"now-14d"`                  | A 14-day window balances baseline coverage against resource usage. Shorter windows (1-7 days) may generate more false positives from infrequent but known combinations.                                                              |


## New terms rule field reference

The following settings appear in the **Define rule** section when creating a new terms rule. For settings shared across all rule types, refer to [Rule settings reference](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5539/solutions/security/detect-and-alert/common-rule-settings).
<definitions>
  <definition term="Index patterns or data view">
    The Elasticsearch indices or data view the rule searches.
  </definition>
  <definition term="Query">
    The KQL or Lucene query used to filter events before evaluating new terms. Only matching documents are checked for new field values.
  </definition>
  <definition term="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.
  </definition>
  <definition term="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.
  </definition>
  <definition term="Suppress alerts by (optional)">
    Reduce repeated or duplicate alerts by grouping them on one or more fields. For details, refer to [Alert suppression](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5539/solutions/security/detect-and-alert/alert-suppression).
  </definition>
</definitions>