> 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/detect-investigate-and-respond-to-threats/threat-management/yara-rule-management.md).

# YARA rule management

Scan Windows endpoints on demand with custom YARA rules.

YARA File Scanning runs custom YARA rules against files on the disks of Windows endpoints. You import YARA rules into Cortex XDR, select the rules and target endpoints, and optionally include or exclude specific paths. The Cortex XDR agent scans the file system on each target endpoint. Each file that matches a rule is listed in the Action Center and recorded as an event in the `xdr_yara_scan_data` dataset.

Common uses include:

* Scoping an incident: search endpoints for files that match known malware or indicators of compromise (IOCs) to find out which endpoints are affected.
* Finding dormant threats: find malicious files that are stored on disk but haven't run yet, so you can respond before they execute.
* Responding to new threat intelligence: when your threat intelligence team or a security advisory publishes YARA rules for a new threat, run them to check whether that threat is present in your environment.

Each match includes file details (name, paths, size, SHA-256 and MD5 hashes, and signer) and endpoint details (hostname, OS version, IP address, agent ID, and version).

YARA is an open-source pattern-matching language that security teams use to identify and classify files. A YARA rule describes what a file of interest looks like. Each rule has a name and three main sections:

| Section     | Purpose                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `meta`      | Descriptive information about the rule, such as the author, a description, and references. It doesn't affect matching.                |
| `strings`   | The patterns to look for: text strings, hexadecimal byte sequences, or regular expressions.                                           |
| `condition` | The logic that decides whether a file matches, for example "all of the strings are present and the file starts with the `MZ` header". |

{% hint style="info" %}
YARA File Scanning complements the agent's real-time malware protection. Real-time protection checks files when they are written or run. YARA File Scanning checks files already stored on disk, using your own rules, whenever you start a scan.
{% endhint %}

You can manage YARA rules and run scans in several ways.

| Method                               | Action                                                                                                                          | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cortex XDR console                   | Work interactively: review rules, start ad-hoc scans, and investigate results.                                                  | Import and view rules on the YARA Rules page, start scans with the scan wizard, and review results in the Action Center.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Public API                           | Integrate YARA File Scanning with external tools, such as a threat intelligence platform or a CI pipeline that publishes rules. | Add, list, and delete rules, and start or abort scans. For details see [API Yara Rules](https://cortex-docs.paloaltonetworks.com/xdr-api/yara-rules-and-scans/yara-rules)                                                                                                                                                                                                                                                                                                                                                                         |
| AgentiX Endpoint Investigation Agent | Run scans, work with rules, and review results in natural language during an investigation.                                     | <p>Ask the agent to:</p><ul><li>Run specific rules on specific endpoints.</li><li>Explain what a rule detects.</li><li>Validate that a rule's logic matches its intended purpose.</li><li>Generate new YARA rules.</li><li>Suggest optimizations to existing rules.</li><li>Summarize scan results.</li></ul><p>For information about correlation rules see the <a href="https://cortex-docs.paloaltonetworks.com/cortex-agentix/configure-cortex-agentix/cases-and-issues-configuration/whats-a-correlation-rule">AgentiX documentation</a>.</p> |
| Playbooks                            | Automate scans as part of a repeatable response, for example scanning affected endpoints when an incident is created.           | Use the YARA commands in playbook tasks to start scans and act on the results.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| XQL                                  | Hunt, correlate, and report on scan results.                                                                                    | Query the `xdr_yara_scan_data` dataset. See Query YARA scan results with XQL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### Prerequisites

| Requirement      | Details                                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operating system | Windows                                                                                                                                                   |
| Cortex XDR agent | Version 9.4 or later                                                                                                                                      |
| License          | Cortex XDR Pro                                                                                                                                            |
| Role permissions | <p>For full access to view, import, delete and run scans:</p><ul><li>Instance Administrator</li><li>Security Admin</li><li>Privileged Responder</li></ul> |

To scan Windows endpoints with custom YARA rules:

1. Import `.yar` files into the **YARA Rules** page.
2. Select the rules to run and the Windows endpoints to scan.
3. (Optional) Define include or exclude paths.
4. Run the scan.

   The Cortex XDR agent scans files on disk on each target endpoint.
5. Review results in the **Action Center.**
6. Query the `xdr_yara_scan_data` dataset with XQL.

### Import YARA rules

Import YARA rules by uploading `.yar` files.

**Before you begin**

* Make sure each rule uses valid YARA syntax and has a unique, descriptive name.
* Make sure you have the required permissions.

1. Navigate to **Threat Management → Detection Rules → YARA**.
2. Click Import Rules.
3. In the Import Rules dialog, upload one or more `.yar` files.
4. Click Import.

The imported rules appear on the YARA Rules page and can be selected for scans.

### Start a YARA scan <a href="#start" id="start"></a>

1. Navigate to **Threat Management → Detection Rules → YARA**
2. Select the rules to run, and then select Run this rule.
3. In the scan wizard, enter a scan name. Choose a name that is easy to recognize later, such as `Quarterly Malware Sweep`.
4. Select the target endpoints. Use the endpoint filter to narrow the list. Only eligible endpoints (Windows, agent 9.4 or later) can be scanned.
5. Optionally, define the scan scope by including or excluding paths.
6. Review the summary and start the scan.

Cortex XDR sends the scan to the selected endpoints. The scan action is summarized as this example:

Scan "Quarterly Malware Sweep" ran 3 YARA rules on 24 endpoints (for example, `DESKTOP-PRHKT0F`), scanning `C:\Users` and `C:\ProgramData`.

### Investigate YARA scan results <a href="#results" id="results"></a>

Each result is available in two places:

* YARA Scan Results table: a dedicated table in the console for reviewing and filtering hits.
* Query YARA scan results with XQL.

#### View YARA scan results <a href="#view-results" id="view-results"></a>

The YARA Scan Results table lists the hits from your scans.

1. Navigate to **Investigation & Response** → **Response** → **Action Center.**
2. Filter the table by scan, rule, endpoint, or file hash.
3. Review the file and endpoint details of each hit.

Use XQL to search, correlate, and aggregate YARA hits across your environment. Start every query with `dataset = xdr_yara_scan_data`.

### Limitations and considerations

The following apply to YARA file system scanning:

<table data-search="false"><thead><tr><th>Limit</th><th>Value</th></tr></thead><tbody><tr><td>Supported operating system</td><td>Windows only</td></tr><tr><td>Scan trigger</td><td>On demand only</td></tr><tr><td>Scan type</td><td>File system only</td></tr><tr><td>Rules per tenant</td><td>10,000</td></tr><tr><td>Rules per scan</td><td>1 through 500</td></tr><tr><td>Include or exclude paths per scan</td><td>Up to 50</td></tr><tr><td>Upload file size</td><td>500 KB per <code>.yar</code> or <code>.yara</code> file</td></tr><tr><td>File size scanned</td><td>Files up to 250 MB</td></tr><tr><td>Concurrent scans</td><td>One YARA scan per endpoint</td></tr><tr><td>Action delivery</td><td>Expires after 48 hours</td></tr><tr><td>Action details retention</td><td>30 days</td></tr></tbody></table>

The agent runs YARA scans at a lower priority than most endpoint scans. Scan duration can vary on busy endpoints.

### Best practices

* Test new rules on a small endpoint group before scanning the fleet.
* Limit scans to relevant paths, such as user profiles.
* Use efficient rules with file-type and file-size checks.
* Store rules in source control and use the API to synchronize updates.
* Narrow the rule or path scope if a scan reaches its match limit.
* Investigate matches with causality data, file search, and IOC rules.


---

# 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/detect-investigate-and-respond-to-threats/threat-management/yara-rule-management.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.
