﻿---
title: Machine learning rules
description: Create detection rules that trigger on machine learning anomaly detection job results.
url: https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/detect-and-alert/machine-learning
products:
  - Elastic Cloud Serverless
  - Elastic Security
applies_to:
  - Serverless Security projects: Generally available
  - Elastic Stack: Generally available
---

# Machine learning rules
Machine learning rules generate alerts when a machine learning anomaly detection job discovers an anomaly that exceeds a defined score threshold. Unlike other rule types, machine learning rules do not require you to write a query. Instead, they rely on machine learning jobs that continuously model normal behavior and flag deviations.

### When to use a machine learning rule

Machine learning rules are the right fit when:
- You want to detect **behavioral anomalies** that are difficult to express as static queries, such as unusual login times, atypical data transfer volumes, or rare process executions for a given user or host.
- A machine learning job is already active (or you plan to enable one) that models the relevant behavior.
- You want **adaptive detection** that automatically adjusts to changing baselines without manual threshold tuning.

Machine learning rules are **not** the best fit when:
- You can define the exact pattern you're looking for. Use a [custom query rule](https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/detect-and-alert/custom-query) or [EQL rule](https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/detect-and-alert/eql) instead.
- You need a count-based threshold. Use a [threshold rule](https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/detect-and-alert/threshold) instead.
- You need to compare events against threat intelligence. Use an [indicator match rule](https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/detect-and-alert/indicator-match) instead.


## Requirements

Machine learning rules require the appropriate [Elastic Stack subscription](https://www.elastic.co/pricing) or [Serverless project feature tier](https://www.elastic.co/elastic/docs-builder/docs/3002/deploy-manage/deploy/elastic-cloud/project-settings), and you must have the [`machine_learning_admin`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3002/reference/elasticsearch/roles#built-in-roles-ml-admin) role in Elastic Stack or the appropriate [user role](https://www.elastic.co/elastic/docs-builder/docs/3002/deploy-manage/users-roles/cloud-organization/user-roles) in Serverless. You also need at least one machine learning anomaly detection job active or configured to start.
For an overview of using machine learning with Elastic Security, refer to [Anomaly detection](https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/advanced-entity-analytics/anomaly-detection).

## Manage machine learning jobs for detection rules

Machine learning rules depend on their associated machine learning jobs running continuously. If a job stops, the rule cannot evaluate anomaly results and won't generate alerts. You can manage job status in two ways: from the machine learning jobs setting UI or the rule's details page.

### ML job settings interface

Machine learning jobs associated with Elastic Security prebuilt rules are managed in a dedicated interface:
1. Find **Detection rules (SIEM)** in the navigation menu or use the [global search field](https://www.elastic.co/elastic/docs-builder/docs/3002/explore-analyze/find-and-organize/find-apps-and-objects).
2. Select the settings menu in the upper-right corner of the page, then select **ML job settings**.

From there you can view, start, and stop all machine learning jobs associated with prebuilt detection rules.
<note>
  You can also create custom machine learning jobs in the Machine Learning app and reference them when creating custom machine learning rules. Custom jobs are managed in the Machine Learning app, not the Rules page settings menu.
</note>


### Rule's details page

You can also check and control job status for a specific rule:
1. Find **Detection rules (SIEM)** in the navigation menu or use the [global search field](https://www.elastic.co/elastic/docs-builder/docs/3002/explore-analyze/find-and-organize/find-apps-and-objects), and select the rule name in the Rules table.
2. In the **Definition** section of the rule's details page, check whether the required machine learning jobs are running.
3. Use the toggles to start or stop each job.

If a required machine learning job isn't running, an error indicator appears in the **Last response** column of the Rules table. Select the indicator to see which jobs are affected.

## Annotated examples

The following examples use the [detections API](https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/detect-and-alert/using-the-api) request format to show how machine learning rules are defined. Each example is followed by a breakdown of the machine learning-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 machine learning job

This rule monitors a rare-process machine learning job for anomalies on Linux hosts.
```json
{
  "type": "machine_learning",
  "name": "Anomalous process execution on Linux",
  "description": "Alerts when a machine learning job detects a rare process execution on a Linux host.",
  "machine_learning_job_id": "v3_linux_anomalous_process_all_hosts",
  "anomaly_threshold": 75,
  "severity": "low",
  "risk_score": 21,
  "interval": "15m",
  "from": "now-16m"
}
```


| Field                     | Value                                    | Purpose                                                                                                                                                                                                           |
|---------------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type`                    | `"machine_learning"`                     | Identifies this as a machine learning rule. No `query`, `language`, or `index` fields are used.                                                                                                                   |
| `machine_learning_job_id` | `"v3_linux_anomalous_process_all_hosts"` | The ID of the anomaly detection job to monitor. Accepts a single string or an array of strings for multiple jobs. If the job is not running, it starts automatically when the rule is enabled.                    |
| `anomaly_threshold`       | `75`                                     | Minimum anomaly score (0-100) required to trigger an alert. A score of 75 surfaces only strong deviations. Lower values (25-50) cast a wider net; higher values (75-100) produce fewer, higher-confidence alerts. |
| `interval` / `from`       | `"15m"` / `"now-16m"`                    | Machine learning rules often use a longer interval than query-based rules because anomaly results are produced on the job's bucket-span schedule rather than in real time.                                        |


### Multiple machine learning jobs with alert suppression

This rule monitors several login-related machine learning jobs and suppresses repeated alerts by user.
```json
{
  "type": "machine_learning",
  "name": "Unusual login activity detected",
  "description": "Alerts when any login-related ML job detects anomalous authentication behavior.",
  "machine_learning_job_id": [
    "auth_high_count_logon_events",
    "auth_rare_source_ip_for_a_user",
    "auth_high_count_logon_fails"
  ],
  "anomaly_threshold": 50,
  "severity": "medium",
  "risk_score": 47,
  "alert_suppression": {
    "group_by": ["user.name"],
    "duration": { "value": 1, "unit": "h" },
    "missing_fields_strategy": "suppress"
  },
  "interval": "15m",
  "from": "now-16m"
}
```


| Field                        | Value                                   | Purpose                                                                                                                                                                                                                                       |
|------------------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `machine_learning_job_id`    | `["auth_high_count_logon_events", ...]` | An array of job IDs. The rule monitors all three jobs and fires when any one produces an anomaly exceeding the threshold.                                                                                                                     |
| `alert_suppression.group_by` | `["user.name"]`                         | Groups anomaly alerts by user to reduce noise when the same user triggers multiple jobs or repeated anomalies. Only anomaly-result fields (including influencer fields configured in the machine learning job) are available for suppression. |
| `alert_suppression.duration` | `{ "value": 1, "unit": "h" }`           | Suppression window of 1 hour. Accepted units are `s` (seconds), `m` (minutes), and `h` (hours).                                                                                                                                               |


## Machine learning rule field reference

The following settings appear in the **Define rule** section when creating a machine learning rule. For settings shared across all rule types, refer to [Rule settings reference](https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/detect-and-alert/common-rule-settings).
<definitions>
  <definition term="Machine learning jobs">
    The anomaly detection jobs whose results the rule evaluates. Select one or more jobs. If a selected job is not active, it starts automatically when the rule is enabled.
  </definition>
  <definition term="Anomaly score threshold">
    The minimum anomaly score (0-100) above which the rule generates alerts. Only anomalies that meet or exceed this score trigger alerts.
  </definition>
  <definition term="Suppress alerts by (optional)">
    Reduce repeated or duplicate alerts by grouping them on one or more fields. Only anomaly fields are available for suppression because machine learning alerts do not contain source event fields. For details, refer to [Alert suppression](https://www.elastic.co/elastic/docs-builder/docs/3002/solutions/security/detect-and-alert/alert-suppression).
  </definition>
</definitions>