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

# YARA rules

## What is YARA rules scanning?

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:

* **meta**: Descriptive information about the rule, such as the author, a description, and references. It does not affect matching.
* **strings**: Patterns to look for; text strings, hexadecimal byte sequences, or regular expressions.
* **condition**: Logic that decides whether a file matches, for example, all strings are present and the file starts with the `MZ` header.

YARA File Scanning runs custom YARA rules against files on Windows endpoint disks. Import your YARA rules into Cortex XSIAM, select the rules and target endpoints, and optionally include or exclude 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 is 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 identify affected endpoints.
* Finding dormant threats: Find malicious files stored on disk that have not run, then respond before they execute.
* Responding to new threat intelligence: Run rules published for a new threat to check whether it exists in your environment.

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

{% 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 stored on disk, using your rules, whenever you start a scan.
{% endhint %}

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

| Method                                         | Action                                                                                                                                                   | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cortex XSIAM tenant                            | 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 application programming interface (API) | Integrate YARA File Scanning with external tools, such as a threat intelligence platform or a continuous integration (CI) pipeline that publishes rules. | Add, list, and delete rules, and start or abort scans. For more details see [YARA rules API](https://cortex-docs.paloaltonetworks.com/xsiam-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, scan affected endpoints when an incident is created.                                       | Use 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

To scan Windows endpoints with custom YARA rules:

1. Import `.yar` files on the **YARA Rules** page.
2. Select the rules to run and the Windows endpoints to scan.
3. Optionally define include or exclude paths.
4. Run the scan.

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

## Prerequisites

| Requirement      | Details                                                                                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operating system | Windows                                                                                                                                                    |
| Cortex XDR agent | Version 9.4 or later                                                                                                                                       |
| License          | Cortex XSIAM Enterprise license                                                                                                                            |
| 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> |

## Import YARA rules

Import YARA rules by uploading `.yar` files.

1. Navigate to **Threat Management** → **Detection Rules** → **YARA**.
2. Select **Import Rules**.
3. In the **Import Rules** dialog box, upload one or more `.yar` files.
4. Select **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, then select **Run this rule**.
3. Enter a scan name in the scan wizard. Use 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 can be scanned (Windows and agent version 9.4 or later).
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 selected endpoints. The scan action is summarized, for example as follows:

> 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:** see the Action Center 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 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 file and endpoint details for each hit.

### Query YARA scan results with XQL

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