--- 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://www.elastic.co/elastic/docs-builder/docs/3028/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://www.elastic.co/elastic/docs-builder/docs/3028/solutions/security/detect-and-alert/indicator-match) instead. - You need to detect spikes in volume. Use a [threshold rule](https://www.elastic.co/elastic/docs-builder/docs/3028/solutions/security/detect-and-alert/threshold) instead. - You want statistical anomaly detection without defining explicit fields. Use a [machine learning rule](https://www.elastic.co/elastic/docs-builder/docs/3028/solutions/security/detect-and-alert/machine-learning) instead. ### Data requirements New terms rules require at least one Elasticsearch index pattern or [data view](https://www.elastic.co/elastic/docs-builder/docs/3028/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://www.elastic.co/elastic/docs-builder/docs/3028/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://www.elastic.co/elastic/docs-builder/docs/3028/solutions/security/detect-and-alert/common-rule-settings). The Elasticsearch indices or data view the rule searches. The KQL or Lucene query used to filter events before evaluating new terms. Only matching documents are checked for new field values. 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. 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. Reduce repeated or duplicate alerts by grouping them on one or more fields. For details, refer to [Alert suppression](https://www.elastic.co/elastic/docs-builder/docs/3028/solutions/security/detect-and-alert/alert-suppression).