> 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/xdr-api/yara-rules-and-scans/yara-rules-and-scans-overview.md).

# YARA Rules and Scans overview

Manage YARA custom detection rules and run on-demand YARA scans on your endpoints.

YARA rules describe patterns, such as strings or byte sequences, that identify a specific malware family or threat. With these APIs you can upload your own YARA rules to Cortex, keep them up to date, and scan selected endpoints with them whenever an investigation requires it.

## What you can do

The APIs cover two related workflows:

* **YARA Rules.** Add rules to your tenant, retrieve them with filtering and sorting, and delete the rules you no longer need. Every rule is compiled and validated before it is stored.
* **YARA Scans.** Start an on-demand scan that runs selected rules against selected endpoints, and abort a scan that is still running.

## Typical workflow

1. Add your rules with the Add YARA rules endpoint.
2. Retrieve the rule IDs with the Get YARA rules endpoint.
3. Start a scan with the Start a YARA scan endpoint, passing the rule IDs and the endpoint IDs you want to scan. The response returns an action ID.
4. Review the scan results in the Cortex XDR console, under **Threat Management** > **Detection Rules** > **YARA** > **Scan Results**.
5. If you need to stop the scan before it finishes, pass the action ID to the Abort a YARA scan endpoint.

## Rule origin

Rules added through these APIs are stored with the origin `public_api`. Rules uploaded through the Cortex XDR console are stored with the origin `user_upload`. You can filter on the `origin` field to work with one group at a time. Use the API values in filters, for example `origin` `eq` `public_api`.

## Partial success

The Add YARA rules and Delete YARA rules endpoints both process each item independently, so a request can succeed partially:

* Add YARA rules returns the rules that were stored in `added_rules` and the rules that failed to compile in `dropped_rules`.
* Delete YARA rules returns a `status` of `SUCCESS`, `PARTIAL`, or `FAILED`, together with the rule IDs it could not find in `failed_deletions`.

Always inspect these fields rather than relying on the HTTP status code alone.

Partial success applies only to rules that fail to compile. Add YARA rules rejects the whole request with a `400` error, and saves none of the rules, when:

* The request contains two or more rules with the same name.
* A rule name in the request already exists in your tenant.
* Saving the rules would take your tenant over 10,000 rules.
* Another import of YARA rules is already in progress.
* None of the rules in the request compile.
* The combined size of all rules in the request exceeds 500 KB.

## Errors

In addition to the standard `400`, `401`, `403`, and `500` errors, every YARA endpoint returns `402` when your tenant does not have the required license or the YARA rules and scans feature is not enabled.

## Limits

| Limit                                                    | Value          |
| -------------------------------------------------------- | -------------- |
| Rules per Add YARA rules request                         | 1000           |
| Combined size of all rules in one Add YARA rules request | 500 KB         |
| Rule IDs per Delete YARA rules request                   | 1000           |
| Rules stored per tenant                                  | 10,000         |
| Rules per scan                                           | 500            |
| Endpoints per scan                                       | 2000           |
| Scope paths per scan                                     | 50             |
| Scan name length                                         | 100 characters |
| Results per Get YARA rules page                          | 100            |

## Endpoint requirements

YARA scans run on Windows endpoints with agent version 9.4.0 or later. Scope paths must use Windows format with backslashes, and can be a drive path (`C:\Windows\System32`), an environment variable (`%WINDIR%\System32`), a UNC path (`\\server\share`), or a wildcard pattern (`*.exe`).

## Required permissions

| Endpoint          | Required permission                  |
| ----------------- | ------------------------------------ |
| Add YARA rules    | Detections > Rules > View/Edit       |
| Get YARA rules    | Detections > Rules > View            |
| Delete YARA rules | Detections > Rules > View/Edit       |
| Start a YARA scan | Response > Action Center > View/Edit |
| Abort a YARA scan | Response > Action Center > View/Edit |

## Required licenses

This feature requires a Cortex XDR license that includes endpoints.


---

# 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/xdr-api/yara-rules-and-scans/yara-rules-and-scans-overview.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.
