Custom YARA signatures

YARA is a rule-based language for identifying malware and other threats by the patterns they contain. Custom YARA signatures let you add your own YARA rules to Elastic Defend, so that it can detect threats that are specific to your environment, such as malware that targets your organization or indicators from a threat report that you're tracking.

Elastic Endpoint evaluates your YARA rules against the memory of running processes on protected hosts. When a rule matches, Elastic Defend generates an alert. To see these alerts on the Alerts page, the Endpoint Security (Elastic Defend) rule, or the Memory Threat - Detected - Elastic Defend rule, must be turned on. Refer to Investigate alerts from custom YARA signatures for details.

A custom YARA signature has a name, one or more operating systems, and a definition. The definition is YARA code that can contain one or more rules, like the contents of a .yar file. By default, a custom YARA signature applies globally to all hosts running Elastic Defend. You can also assign it to specific Elastic Defend integration policies, so that it only applies to the hosts assigned to those policies.

1. Go to the Artifacts page using the navigation menu or the global search field, then select the Custom YARA signatures tab.
2. Click Add YARA signature. The Add YARA signature flyout opens.
3. In the Details section, do the following:
   • Enter a Name for your signature.
   • In the Operating system field, select one or more operating systems: Windows, Linux, or macOS. Elastic Defend only applies the signature to hosts running the selected operating systems.
   • Optionally, enter a Description.
4. In the Definition section, write or paste your YARA code. The editor suggests YARA keywords as you type, and checks your code as you work, showing errors and warnings with their line numbers. Refer to YARA rule requirements and Meta fields that Elastic Defend uses for details on what is allowed.
5. Select an option in the Assignment section:
   • Global: Assign the signature to all Elastic Defend integration policies.
   • Per Policy: Assign the signature to one or more specific Elastic Defend integration policies.
6. Click one of the following:
   • Create & enable signature: Saves the signature and starts applying it to hosts.
   • Create signature without enabling: Saves the signature, but doesn't apply it to hosts until you turn it on.

After you add a signature, make sure the policies that it's assigned to apply custom YARA signatures.

For a signature to take effect on a host, all the following must be true:

• The signature is enabled.
• The signature is global, or it's assigned to the Elastic Defend integration policy that the host uses.
• In that policy, memory threat protection is turned on, and the Apply custom YARA signatures in detection mode setting is turned on.

To check or change the policy setting:

1. Go to Assets → Endpoints → Policies, then select the policy.
2. On the Policy settings tab, find the Memory threat section.
3. Turn Apply custom YARA signatures in detection mode on or off. This setting is only available when memory threat protection is turned on.
4. Click Save.

To see which custom YARA signatures are assigned to a policy, assign more signatures, or remove them, open the policy and select its Custom YARA signatures tab.

Elastic Endpoint scans each running process with your signatures about 5 minutes after the process starts, and then again every 24 hours by default. Processes that are already running when the policy takes effect are scanned too. To change how often processes are re-scanned, refer to the user_yara_rescan_interval_seconds settings in Elastic Defend advanced settings.

Trusted applications and Elastic Endpoint exceptions apply to these scans: Elastic Endpoint skips processes that are trusted, and doesn't generate alerts that match an exception.

The Custom YARA signatures tab on the Artifacts page lists all custom YARA signatures. To refine the list, use the search bar to search by name, description, or YARA code. To view the YARA code and other details of a signature, click its name.

Use the Enabled toggle in the list to turn a signature on or off. A signature that is turned off stays in your list, but Elastic Defend doesn't apply it to hosts.

You can import and export custom YARA signatures as NDJSON files:

• When the list is empty: Click Import YARA signatures.
• When the list has entries: Click the actions menu , then select Import YARA signatures or Export YARA signatures.

When you import an NDJSON file, the imported signatures are appended to your existing entries — existing entries are not removed or overwritten. If a signature that you import already exists, Elastic Defend keeps the existing version and skips the imported one.

Items are processed individually on import — items that fail validation, and per-policy items that are not visible in the current space, are skipped, while the remaining items are imported. Imported YARA code must meet the same requirements as code that you enter in the editor.

If an imported per-policy item is assigned to a policy that doesn't exist in the current environment, the item is imported with the policy assignment removed.

You can individually modify each custom YARA signature.

To edit a custom YARA signature:

1. Click the actions menu (…) on the signature you want to edit, then select Edit YARA signature.
2. Modify details as needed.
3. Click Save.

You can delete a custom YARA signature, which removes it entirely from all Elastic Defend integration policies.

To delete a custom YARA signature:

1. Click the actions menu (…) on the signature you want to delete, then select Remove from YARA signatures list.
2. On the dialog that opens, verify that you are removing the correct signature, then click Delete.

When a custom YARA signature matches the memory of a running process, Elastic Defend generates a memory threat detection alert. It appears on the Alerts page only if one of the following endpoint protection rules is turned on:

• The Endpoint Security (Elastic Defend) rule, which is turned on by default when you install Elastic prebuilt rules.
• If you use the feature-specific protection rules instead, Memory Threat - Detected - Elastic Defend.

The Memory Threat - Prevented - Elastic Defend rule doesn't create alerts for custom YARA signatures, because they only detect threats.

The alert includes the following fields:

• rule.custom_yara_signature.entry_name: The name of the custom YARA signature that contains the matching rule.
• rule.custom_yara_signature.rule_identifier: The name of the YARA rule that matched.

These fields appear in the Highlighted fields section of the alert details flyout. If you have the Custom YARA Signatures: Read privilege, the value links to the signature.

Elastic Defend checks the definition of each custom YARA signature when you save it. Your definition must meet the following requirements:

• It must contain at least one valid YARA rule, and can contain up to 256 rules.
• It must not exceed 32,766 bytes. This limit applies to the whole definition, not to each rule.
• Rule names can be up to 128 characters long.
• It can't use the include directive. Each signature must be self-contained.
• It can only import the following YARA modules: pe, elf, math, time, string, and console. Importing any other module, such as hash, macho, dotnet, dex, magic, or cuckoo, causes an error.

Syntax errors and other YARA compiler errors prevent you from saving the signature. YARA compiler warnings appear in the editor, but don't prevent you from saving the signature.

In YARA, the meta section of a rule is optional, and you can add any metadata to it that you want. Elastic Defend reads three meta fields, os, arch, and scan_type, and uses them to limit where a rule applies. Elastic Defend validates their values when you save the signature, but it doesn't validate any other meta fields that you add.

The following rules apply to these meta fields:

• Values are case-sensitive. For example, use MacOS, not macos, and Memory, not memory.
• Separate multiple values with a comma, optionally followed by a space (for example, "Windows, Linux" or "x86,arm64"). Don't repeat a value in the same list.
• Each field can appear only once in each rule.
• The os value must list exactly the same operating systems as the Operating system field of the signature, in any order. If they differ, Elastic Defend rejects the signature. If you don't want to keep them in sync, omit os from your rules.
• When a signature contains more than one rule, arch and scan_type must be consistent across all its rules. Either omit the field from every rule, or use the same value in every rule.