> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xdr/insights-and-tips-cortex-xdr/detection-engineering-and-threat-intelligence/custom-detection-rules.md).

# Custom detection rules

Learn how to create and validate custom BIOC, correlation, and IOC detection rules in Cortex XDR.

In addition to the built-in detections that Palo Alto Networks maintains, you can add your own detection logic. All custom rules use XQL (Cortex Query Language).

| Need                                                                                                             | Use                  | Scope                                                           |
| ---------------------------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------- |
| Detect a specific behavior on endpoints, such as a process chain, command line, file, registry, or network event | **BIOC rule**        | Endpoint and supported cloud audit data, evaluated in real time |
| Correlate events across data sources or over a time window                                                       | **Correlation rule** | Any dataset, real time or scheduled                             |
| Detect a known artifact, such as a hash, IP address, domain, or file path                                        | **IOC rule**         | Endpoint data                                                   |
| Give analytics more context about a user or host                                                                 | **Asset roles**      | Adjusts how analytics detectors score activity                  |

### BIOC rules

Define a BIOC with XQL Search or the entity-based builder. The query must filter on `event_type`. Then set the severity and, optionally, map the rule to MITRE ATT\&CK tactics and techniques. See [Create a BIOC rule](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/threat-management/detection-rules/whats-a-bioc/create-a-bioc-rule).

### Correlation rules

Correlation rules can stitch together endpoint, firewall, identity, and cloud data, for example "a blocked malware execution, then a blocked outbound connection from the same host, then a failed login for the same user within 10 minutes". Choose **Real Time** or **Scheduled** (as frequently as every 10 minutes), and choose whether the rule raises an issue or saves results to a dataset. See [Create a correlation rule](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/threat-management/detection-rules/whats-a-correlation-rule/create-a-correlation-rule).

### Validate a rule before production

1. Run the rule's XQL in **XQL Search** over historical data to see how often it would have matched.
2. Use the editor's **Test** option.
3. To trial a correlation rule without raising issues, set its action to **Save data to a dataset**, review the results, then switch it to raise issues.
4. Create the rule disabled, and enable it after review.

A simple IOC or BIOC rule can typically be created and validated quickly. Complex multi-source correlation rules take longer because of tuning.

### Reuse investigation artifacts

Artifacts that you find during an investigation can become permanent detections. For example, add a hash or domain as an IOC, turn a malicious command line into a BIOC, or turn an XQL hunting query into a correlation rule.

### YARA and Sigma

Detection rules in Cortex XDR are written in XQL. To reuse Sigma or YARA logic, translate it to an XQL-based BIOC or correlation rule. Marketplace content may provide conversion helpers. Check the Marketplace in your tenant.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cortex-docs.paloaltonetworks.com/cortex-xdr/insights-and-tips-cortex-xdr/detection-engineering-and-threat-intelligence/custom-detection-rules.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.