/yara-rule-authoring

name: yara-rule-authoring
description: >
  Guides authoring of high-quality YARA-X detection rules for malware identification.
  Use when writing, reviewing, or optimizing YARA rules. Covers naming conventions,
  string selection, performance optimization, migration from legacy YARA, and false
  positive reduction. Triggers on: YARA, YARA-X, malware detection, threat hunting,
  IOC, signature, crx module, dex module.

YARA-X Rule Authoring

Write detection rules that catch malware without drowning in false positives.

Resolve the [linter](scripts/yara_lint.py), [atom analyzer](scripts/atom_analyzer.py), and [review helper](scripts/review.sh) from this installed `SKILL.md`'s directory. In commands below, replace each `<resolved-...-path>` with that script's absolute path and keep the quotes. The rule file or directory is still relative to your working directory unless you pass an absolute input path.

**This skill targets YARA-X**, the Rust-based successor to legacy YARA — 5-10x faster regex, better errors, built-in formatter, stricter validation, new modules (crx, dex), 99% rule compatibility. It powers VirusTotal's production systems. Install with `brew install yara-x` or `cargo install yara-x`; the CLI is `yr`. See [Migrating from Legacy YARA](#migrating-from-legacy-yara) for existing rules.

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 verification on too many files.

2. **Target specific families, not categories** — "Detects ransomware" catches everything and nothing. "Detects LockBit 3.0 configuration extraction routine" catches what you want.

3. **Test against goodware before deployment** — A rule that fires on Windows system files is useless. Validate against VirusTotal's goodware corpus or your own clean file set.

4. **Short-circuit with cheap checks first** — `filesize` (instant), then magic bytes (nearly instant), then strings (cheap), then modules (expensive).

5. **Metadata is documentation** — Future you (and your team) need to know what this catches, why, and where the sample came from.

When to Use

• Writing new YARA-X rules for malware detection
• Reviewing existing rules for quality or performance issues
• Optimizing slow-running rulesets
• Converting IOCs or threat intel into detection signatures
• Debugging false positive issues
• Preparing rules for production deployment
• Migrating legacy YARA rules to YARA-X
• Analyzing Chrome extensions (crx module) or Android apps (dex module)

When NOT to Use

• Static analysis requiring disassembly → use Ghidra/IDA skills
• Dynamic malware analysis → use sandbox analysis skills
• Network-based detection → use Suricata/Snort skills
• Memory forensics with Volatility → use memory forensics skills
• Simple hash-based detection → just use hash lists

Platform Considerations

YARA works on any file type. Adapt patterns to your target:

| Platform | Magic Bytes | Bad Strings | Good Strings | |----------|-------------|-------------|--------------| | **Windows PE** | `uint16(0) == 0x5A4D` | API names, Windows paths | Mutex names, PDB paths | | **macOS Mach-O** | `uint32(0) == 0xFEEDFACE` (32-bit), `0xFEEDFACF` (64-bit), `uint32be(0) == 0xCAFEBABE` (universal) | Common Obj-C methods | Keylogger strings, persistence paths | | **JavaScript/Node** | (none needed) | `require`, `fetch`, `axios` | Obfuscator signatures, eval+decode chains | | **npm/pip packages** | (none needed) | `postinstall`, `dependencies` | Suspicious package names, exfil URLs | | **Office docs** | `uint32(0) == 0x04034B50` | VBA keywords | Macro auto-exec, encoded payloads | | **VS Code extensions** | (none needed) | `vscode.workspace` | Uncommon activationEvents, hidden file access | | **Chrome extensions** | Use `crx` module | Common Chrome APIs | Permission abuse, manifest anomalies | | **Android apps** | Use `dex` module | Standard DEX structure | Obfuscated classes, suspicious permissions |

> **`uintNN()` reads little-endian.** Write the constant as the bytes *reversed*, or use `uintNNbe()` and write them in file order. A ZIP/OOXML file starts with bytes `50 4B 03 04`, so it is `uint32(0) == 0x04034B50` — `uint32(0) == 0x504B0304` compiles cleanly and never matches anything. The same trap catches Mach-O universal binaries: on disk they are `CA FE BA BE`, so `uint32(0) == 0xCAFEBABE` is a dead branch; write `uint32be(0) == 0xCAFEBABE` or `uint32(0) == 0xBEBAFECA`. Verify with `yr scan` against one known-good sample before trusting any magic-byte check.

macOS Malware Detection

No dedicated Mach-O module exists yet — use magic bytes plus string patterns. Good indicators:

• Keylogger artifacts: `CGEventTapCreate`, `kCGEventKeyDown`
• SSH tunnel strings: `ssh -D`, `tunnel`, `socks`
• Persistence paths: `~/Library/LaunchAgents`, `/Library/LaunchDaemons`
• Credential theft: `security find-generic-password`, `keychain`

// Pattern from Airbnb BinaryAlert
rule SUSP_Mac_ProtonRAT
{
    strings:
        $lib1 = "SRWebSocket" ascii          // Library indicators
        $lib2 = "SocketRocket" ascii
        $behav1 = "SSH tunnel not launched" ascii   // Behavioral indicators
        $behav2 = "Keylogger" ascii
    condition:
        (uint32(0) == 0xFEEDFACF or uint32be(0) == 0xCAFEBABE) and
        any of ($lib*) and any of ($behav*)
}

JavaScript Detection

| Target | Approach | |---|---| | npm package | `package.json` patterns, postinstall/preinstall hooks, exfil combination: fetch + env access + credential paths | | Chrome extension | `crx` module | | Other extension | Manifest patterns, background script behaviors | | Standalone JS | Obfuscation markers (eval+atob, fromCharCode chains), unique function/variable names, packed payloads | | Minified/webpack bundle | Unique strings that survive bundling (URLs, magic values); **avoid function names** — they get mangled |

**Good JS s