<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# YARA Rule Development — API Reference

## YARA CLI

### Commands

```bash
yara [options] rule_file target
yara -r rules.yar directory/       # Recursive scan
yara -s rules.yar sample.exe       # Show matching strings
yara -c rules.yar directory/       # Count matches only
yara -t tag rules.yar directory/   # Only rules with tag
yara -p 4 rules.yar directory/     # Parallel threads
yara --print-stats rules.yar dir/  # Performance stats
```

### Compiler

```bash
yarac rules.yar compiled.yarc      # Compile to binary
yara compiled.yarc sample.exe      # Scan with compiled rules
```

## yara-python

### Installation

```bash
pip install yara-python
```

### Key API

```python
import yara

# Compile from file
rules = yara.compile(filepath="rules.yar")

# Compile from string
rules = yara.compile(source='rule test { condition: true }')

# Compile from multiple sources
rules = yara.compile(filepaths={
    "namespace1": "rules1.yar",
    "namespace2": "rules2.yar",
})

# Scan file
matches = rules.match("sample.exe")
matches = rules.match("sample.exe", timeout=60)

# Scan data
matches = rules.match(data=file_bytes)

# Match object
match.rule          # Rule name
match.tags          # Rule tags
match.meta          # Rule metadata dict
match.strings       # Matched strings: (offset, identifier, data)
match.namespace     # Rule namespace
```

## YARA String Types

### Text Strings

```yara
$s1 = "plain text"
$s2 = "case insensitive" nocase
$s3 = "wide string" wide        # UTF-16LE
$s4 = "both" ascii wide
$s5 = "full word" fullword      # Word boundary
$s6 = "xor encoded" xor         # All XOR keys 0x01-0xFF
$s7 = "base64" base64           # Match B64-encoded form
```

### Hex Strings

```yara
$h1 = { 4D 5A 90 00 }           # Exact bytes
$h2 = { 4D 5A ?? 00 }           # Wildcard byte
$h3 = { 4D 5A [2-4] 00 }       # Jump 2-4 bytes
$h4 = { 4D 5A (90 | 91) 00 }   # Alternative bytes
$h5 = { 4D ~5A 90 00 }         # Not 5A (negation)
```

### Regular Expressions

```yara
$r1 = /https?:\/\/[a-zA-Z0-9.-]+/
$r2 = /[A-Za-z0-9+\/]{20,}={0,2}/   # Base64 pattern
```

## Condition Operators

| Operator | Example | Description |
|----------|---------|-------------|
| `and`, `or`, `not` | `$a and $b` | Boolean logic |
| `any of` | `any of ($s*)` | Any string matches |
| `all of` | `all of ($s*)` | All strings match |
| `N of` | `2 of ($s*)` | At least N match |
| `filesize` | `filesize < 1MB` | File size check |
| `uint16(0)` | `uint16(0) == 0x5A4D` | Read bytes at offset |
| `for` | `for any i in (1..#s): (@s[i] < 100)` | Iteration |
| `at` | `$s at 0` | String at exact offset |
| `in` | `$s in (0..100)` | String in range |

## yarGen

```bash
# Generate rules from malware samples
python3 yarGen.py -m malware_dir/ -o output.yar

# Exclude goodware strings
python3 yarGen.py -m malware_dir/ -o output.yar --excludegood

# Update goodware databases
python3 yarGen.py --update
```

## Performance Tips

1. Put `filesize` and magic checks first in condition
2. Use `private` for helper strings not needed in output
3. Avoid unbounded regex like `.*`
4. Prefer hex patterns over complex regex
5. Use `fullword` to reduce partial matches
6. Pre-compile rules (`yarac`) for production scanning
