---
name: yara-rule-development
description: >
  Create, test, and optimize YARA detection rules for malware identification. Use when
  developing signatures for known malware samples, building detection rules for malware
  families, or creating hunting rules for threat campaigns. Covers both YARA and YARA-X
  syntax, rule optimization, and false positive avoidance.
---

# YARA Rule Development

Create effective YARA rules to detect malware samples and families by identifying unique
byte patterns, strings, and structural characteristics.

## Prerequisites

- Python 3.10+ with `yara-python` package
- [YARA](https://virustotal.github.io/yara/) or [YARA-X](https://virustotal.github.io/yara-x/) installed
- Malware sample(s) for analysis
- Clean file corpus for false positive testing
- Optional: PE analysis tools (`pefile`), string extraction tools

Install dependencies:
```bash
pip install yara-python pefile
# Or for YARA-X:
pip install yara-x
```

## Steps

### 1. Identify Unique Byte Patterns

Extract candidate patterns from the malware sample that are distinctive enough for detection.

```bash
# Extract ASCII strings (minimum 6 characters)
strings -n 6 sample.exe > strings_ascii.txt

# Extract Unicode strings
strings -el sample.exe > strings_unicode.txt

# Extract hex patterns at specific offsets
xxd sample.exe | head -100

# Use the automated generator
python scripts/yara_generator.py --sample sample.exe --output rule.yar
```

**Good candidate patterns:**
- Unique strings not found in legitimate software
- Mutex names, registry key paths, C2 URLs
- Custom encryption/encoding routines (byte sequences)
- Error messages or debug strings specific to the malware
- Embedded configuration data markers
- Unique API call sequences in import table

### 2. Extract Meaningful Strings

Focus on strings that provide context and are unlikely to appear in benign software.

**High-value strings:**
- Command-and-control URLs or domains
- Campaign identifiers or version strings
- Custom protocol commands (e.g., `DOWNLOAD`, `EXEC`, `SHELL`)
- Unique mutex names (e.g., `Global\xRAT_mtx_2024`)
- PDB paths (e.g., `C:\Users\attacker\Desktop\malware\Release\payload.pdb`)
- Hardcoded credentials or API keys
- Unique error messages

**Avoid these strings (high false positive risk):**
- Common API names (`CreateFile`, `RegSetValue`)
- Generic error messages (`Error`, `Failed`)
- Common library strings
- Standard HTTP headers
- Single common words

### 3. Define Rule Conditions

Write conditions that balance detection accuracy with performance.

```yara
rule Example_Malware_Family {
    meta:
        author = "Analyst Name"
        date = "2025-01-15"
        description = "Detects Example malware family"
        hash = "a1b2c3d4e5f6..."
        reference = "https://example.com/analysis"
        tlp = "WHITE"

    strings:
        $mutex = "Global\\ExampleMutex" ascii wide
        $c2_1 = "malicious-domain.com" ascii
        $c2_2 = "backup-c2.net" ascii
        $pdb = "\\Release\\payload.pdb" ascii
        $cmd_1 = "CMD_DOWNLOAD" ascii
        $cmd_2 = "CMD_EXECUTE" ascii
        $cmd_3 = "CMD_UPLOAD" ascii
        $magic = { 4D 5A 90 00 03 00 00 00 }

    condition:
        uint16(0) == 0x5A4D and
        filesize < 5MB and
        (
            $mutex or
            any of ($c2_*) or
            ($pdb and 2 of ($cmd_*))
        )
}
```

### 4. Add Metadata

Include comprehensive metadata for rule management and attribution.

```yara
meta:
    author = "Analyst Name"
    date = "2025-01-15"
    modified = "2025-02-01"
    description = "Detects ExampleRAT v2.x payload"
    reference = "https://blog.example.com/examplerat-analysis"
    hash = "abc123def456..."
    tlp = "WHITE"
    mitre_attack = "T1059.001, T1547.001"
    malware_family = "ExampleRAT"
    malware_type = "RAT"
    severity = "high"
    confidence = "high"
    false_positives = "None known"
    version = "1.0"
```

### 5. Test Against Known Samples

Verify the rule matches all known samples of the malware family.

```bash
# Test against a single sample
yara rule.yar sample.exe

# Test against a directory of samples
yara -r rule.yar ./malware_samples/

# Test with the automated tester
python scripts/yara_tester.py --rules rule.yar \
    --malware-dir ./known_malware/ \
    --clean-dir ./clean_files/ \
    --output test_results.json
```

### 6. Optimize for Performance

Ensure rules run efficiently, especially when scanning large file sets.

**Performance tips:**
- Use `filesize` limits to skip irrelevant files early
- Place fast conditions (magic bytes, filesize) before slow ones (string searches)
- Avoid excessive use of regex (use fixed strings when possible)
- Limit wildcard patterns (`??` and `[X-Y]`) in hex strings
- Use `at` for strings at known offsets instead of scanning the entire file
- Minimize use of `for..of` loops with large iteration counts

```yara
condition:
    // Fast checks first
    uint16(0) == 0x5A4D and
    filesize < 2MB and
    // Then string matching
    3 of ($string_*) and
    // Complex conditions last
    for any section in pe.sections : (
        section.name == ".rsrc" and
        math.entropy(section.raw_data_offset, section.raw_data_size) > 7.0
    )
```

### 7. Avoid False Positives

Test against a clean file corpus and refine conditions.

```bash
# Test against clean files
yara -r rule.yar /usr/bin/
yara -r rule.yar "C:\Windows\System32\"
yara -r rule.yar ./clean_software_corpus/

# If false positives occur, add exclusions or tighten conditions
```

**Strategies to reduce false positives:**
- Require multiple strings to match (`2 of ($s_*)`)
- Add file type checks (`uint16(0) == 0x5A4D` for PE files)
- Add filesize bounds
- Use `pe` module for import/export checks
- Combine string matches with structural checks
- Exclude known-good signers with `pe.signatures`

### 8. Organize into Rule Sets

Structure rules for maintainability and deployment.

```
rules/
  apt/
    apt29_wellmess.yar
    apt41_shadowpad.yar
  ransomware/
    lockbit3.yar
    blackcat.yar
  rat/
    cobaltstrike.yar
    asyncrat.yar
  index.yar              # Includes all rule files
```

```yara
// index.yar
include "apt/apt29_wellmess.yar"
include "apt/apt41_shadowpad.yar"
include "ransomware/lockbit3.yar"
```

### 9. YARA-X Considerations

YARA-X is the next generation of YARA with improved performance and new features.

**Key differences from classic YARA:**
- Written in Rust for better performance and safety
- Stricter syntax validation
- New `console` module for debugging
- Improved regex engine
- Breaking changes in some module APIs

```bash
# YARA-X CLI usage
yr scan rule.yar sample.exe

# Python API
import yara_x
rules = yara_x.compile("rule test { condition: true }")
results = rules.scan(open("sample.exe", "rb").read())
```

## Offline vs Online Mode

**Offline mode (default):** All rule development and testing is performed locally.
String extraction, pattern analysis, and rule compilation require no internet access.

**Online mode:** Enhance rule development with external resources:
- Submit sample hashes to VirusTotal for existing detection names
- Search for related YARA rules in public repositories
- Cross-reference strings with known malware databases
- Check rule performance against VirusTotal Livehunt

## Tips

- Start with loose rules and tighten them based on false positive testing
- One rule per malware family or variant, not per sample
- Keep rules readable with comments explaining string choices
- Version your rules with dates and changelogs in metadata
- Test on both 32-bit and 64-bit versions of samples when applicable
- Consider both packed and unpacked versions of samples
- Use the `pe` module for PE-specific checks rather than raw hex offsets
- Share rules with the community when possible (respecting TLP markings)
- Regularly review and update rules as malware evolves