YARA-X Rule Authoring

Write detection rules that catch malware without drowning in false positives. Based on Trail of Bits methodology.

Core Principles

1. Strings must generate good atoms — YARA extracts 4-byte subsequences for fast matching. Strings with repeated bytes, common sequences, or under 4 bytes force slow bytecode scans.
2. Target specific families, not categories — "Detects ransomware" is useless. "Detects LockBit 3.0 config extraction routine" is useful.
3. Test against goodware — Validate against clean file sets before deployment.
4. Short-circuit with cheap checks first — filesize < 10MB and uint16(0) == 0x5A4D before expensive string searches.
5. Metadata is documentation — Future you needs to know what this catches and why.

YARA-X Basics

YARA-X is the Rust successor to legacy YARA: 5-10x faster, better errors, built-in formatter, stricter validation, new modules (crx, dex).

Install: brew install yara-x / cargo install yara-x

Commands: yr scan, yr check, yr fmt, yr dump

Rule Template

import "pe"

rule FamilyName_Variant_Technique : tag1 tag2 {
    meta:
        author      = "Your Name"
        date        = "2026-02-14"
        description = "Detects [specific behavior] in [malware family]"
        reference   = "https://..."
        tlp         = "TLP:WHITE"
        hash        = ""
        score       = 75  // 0-100 confidence

    strings:
        // Unique strings from the sample
        $api1 = "VirtualAllocEx" ascii
        $api2 = "WriteProcessMemory" ascii
        $str1 = { 48 8B 05 ?? ?? ?? ?? 48 85 C0 }  // hex with wildcards
        $pdb  = /[A-Z]:\\.*\\Release\\.*\.pdb/ nocase

    condition:
        uint16(0) == 0x5A4D and
        filesize < 5MB and
        (2 of ($api*) and $str1) or
        $pdb
}

Naming Convention

Family_Variant_Technique — examples:

• Emotet_Loader_DocumentMacro
• CobaltStrike_Beacon_x64
• Generic_Cryptominer_XMRig

String Selection

Good strings (unique, specific):

• Mutex names, PDB paths, C2 URLs
• Unique byte sequences from disassembly
• Custom encryption constants
• Uncommon API call sequences

Bad strings (too common, high FP):

• http://, https://, common API names alone
• Single common words, short strings (<4 bytes)
• Strings found in Windows system files

Condition Patterns

// Performance-ordered (cheap → expensive)
condition:
    uint16(0) == 0x5A4D and     // Magic bytes (instant)
    filesize < 10MB and          // Size filter (instant)
    2 of ($unique*) and          // String matching (fast)
    pe.imports("kernel32.dll")   // Module check (slower)

Common magic bytes:

Performance Rules

1. Put filesize and magic byte checks FIRST in condition
2. Never use unbounded regex like /.*/
3. Avoid for all with complex conditions on large files
4. Use ascii or wide, not both unless needed
5. Hex strings with specific bytes > wildcards > regex
6. Use at for fixed offsets instead of scanning entire file

Testing

# Validate syntax
yr check rules/

# Scan a sample
yr scan rules/my_rule.yar suspicious_file.exe

# Scan directory
yr scan rules/ samples/ --threads 4

# Format rules consistently
yr fmt rules/my_rule.yar

False Positive Reduction

• Add filesize constraints (malware has typical size ranges)
• Require multiple string matches (2 of ($str*) not any of)
• Exclude known good paths/publishers via not conditions
• Score-based approach: assign confidence scores in metadata, triage by threshold
• Test against goodware corpus before deployment

Reference

Full methodology, module docs (pe, elf, crx, dex), and migration guide from legacy YARA:

https://github.com/trailofbits/skills/tree/main/plugins/yara-authoring