yara-rule-authoring

YARA-X Rule Authoring

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

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 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:

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

Good JS strings: Ethereum function selectors — { a9 05 9c bb } (transfer(address,uint256)), { 70 a0 82 31 } (balanceOf(address)); zero-width characters for steganography — { E2 80 8B E2 80 8C }; obfuscator signatures — _0x, var _0x; specific C2 domains and webhook URLs.

Bad JS strings: require, fetch, axios (too common); Buffer, crypto (legitimate uses everywhere); process.env alone (need specific env var names).

String Selection

Value ranking: mutex names are gold, C2 paths silver, error messages bronze. Stack strings are almost always unique. If you need more than 6 strings, you're over-fitting.

Reject a candidate string when any of these holds:

Everything left — unique to this family — is what the rule should rest on.

Choosing a String Type

Modifier discipline: never use nocase or wide speculatively — only with confirmed evidence that case or encoding varies across samples. nocase doubles atom generation; wide doubles string matching. "If you don't have a clear reason for using those modifiers, don't do it" — Kaspersky Applied YARA.

Condition Design

Order for short-circuit: filesize <, magic bytes, strings, modules. If the condition runs past 5 lines, split into multiple rules.

all of vs any of

Lesson from production: rules using any of ($network_*) where the strings included fetch, axios, and http matched virtually all web applications. Switching to require a credential path AND a network call AND an exfil destination eliminated the FPs.

Grouping by Confidence

Different indicator types carry different weight — a C2 domain might be definitive while library imports need corroboration. Grouping by prefix lets you express graduated requirements:

strings:
    $a1 = "SRWebSocket" ascii            // Category A: library indicators
    $a2 = "SocketRocket" ascii
    $b1 = "SSH tunnel" ascii             // Category B: behavioral
    $b2 = "keylogger" ascii nocase
    $c1 = /https:\/\/[a-z0-9]{8,16}\.onion/   // Category C: C2

condition:
    filesize < 10MB and
    any of ($a*) and any of ($b*)        // Evidence from BOTH categories

Modules vs Byte Checks

"Avoid the magic module — use explicit hex checks instead" — Neo23x0. Generalize it: if uint32() can do the job, don't load a module.

Performance

• Regex must be anchored to a 4+ byte literal. Without one it evaluates at every file offset — catastrophic. Write /mshta\.exe http:\/\/.../, not /http:\/\/.../. If you can't anchor, use a hex pattern with wildcards.
• Bound every regex quantifier — .{0,30}, never .*. Unbounded regex is both a performance disaster and a memory explosion.
• Bound loops with filesize — filesize < 100KB and for all i in (1..#a) : .... Unbounded #a can reach thousands in large files.
• Prefer hex over regex where the bytes are fixed.

Before Writing: Is the Sample Packed?

Don't write rules against packed layers. The packing changes; the payload doesn't.

When Strings Fail, Pivot to Structure

If extraction returns only API names and generic paths:

"One can try to use other file properties, such as metadata, entropy, import hashes or other data which stays constant." — Kaspersky Applied YARA Training

Debugging False Positives

1. Which string matched? — yr scan -s rule.yar false_positive.exe
2. In a legitimate library? — add a not $fp_vendor_string exclusion
3. A common development pattern? — replace the string with something more specific
4. Multiple generic strings matching together? — tighten to require all, plus a unique marker
5. Malware using a common technique? — target its specific implementation details, not the technique

When to Abandon the Approach

• Extraction returns only API names and paths → pivot to structure
• Can't find 3 unique strings → probably packed; target the unpacked version or detect the packer
• Rule matches goodware → 1-2 matches: investigate and tighten; 3-5: find different indicators; 6+: start over
• Performance is terrible after optimization → architecture problem; split into focused rules or add strict pre-filters
• The description is hard to write → the rule is too vague. If you can't explain what it catches, it catches too much

Rationalizations to Reject

When you catch yourself thinking these, stop and reconsider.

Toolkit

Master these five. Don't get distracted by tool catalogs.

Development cycle:

yr check rule.yar                                   # syntax, with precise line numbers
yr fmt -w rule.yar                                  # standardize formatting
yr dump -m pe sample.exe --output-format yaml       # inspect structure, no dummy rule needed
time yr scan -s rule.yar corpus/                    # scan with timing

Reach for yr dump when investigating which module fields are available, debugging why a module condition isn't matching, or exploring a new module (crx, lnk, dotnet) before writing against it. YARA-X error messages carry precise source locations — if yr check says line 15, the problem is on line 15.

Version-gated features: private $helper = "pattern" matches but stays out of output (v1.3.0+); // suppress: slow_pattern silences a specific warning inline (v1.4.0+); filesize < 10_000_000 numeric underscores (v1.5.0+). $_unused also suppresses unused-string warnings.

Chrome Extension Analysis (crx module)

Requires YARA-X v1.5.0+, or v1.11.0+ for permhash().

Key APIs: crx.is_crx, crx.permissions, crx.permhash() Red flags: nativeMessaging + downloads, debugger permission, content scripts on <all_urls>

import "crx"

rule SUSP_CRX_HighRiskPerms {
    condition:
        crx.is_crx and
        for any perm in crx.permissions : (perm == "debugger")
}

See crx-module.md for the full API, permission risk assessment, and example rules.

Android DEX Analysis (dex module)

Requires YARA-X v1.11.0+. Not compatible with legacy YARA's dex module — the API is completely different.

Key APIs: dex.is_dex, dex.contains_class(), dex.contains_method(), dex.contains_string() Red flags: single-letter class names (obfuscation), DexClassLoader reflection, encrypted assets

import "dex"

rule SUSP_DEX_DynamicLoading {
    condition:
        dex.is_dex and
        dex.contains_class("Ldalvik/system/DexClassLoader;")
}

See dex-module.md for the full API, obfuscation detection, and example rules.

Migrating from Legacy YARA

99% rule compatibility, but stricter validation:

yr check --relaxed-re-syntax rules/   # identify issues
# fix each one, then verify without relaxed mode:
yr check rules/

--relaxed-re-syntax is a diagnostic, not a destination. Fix the regex.

Naming and Metadata

{CATEGORY}_{PLATFORM}_{FAMILY}_{VARIANT}_{DATE}      e.g. MAL_Win_Emotet_Loader_Jan25

Categories: MAL_ (malware), HKTL_ (hacking tool), WEBSHELL_, EXPL_, SUSP_ (suspicious), GEN_ (generic). Platforms: Win_, Lnx_, Mac_, Android_, CRX_.

Every rule needs description (starting with "Detects"), author, reference, and date:

meta:
    description = "Detects Example malware via unique mutex and C2 path"
    author = "Your Name <[email protected]>"
    reference = "https://example.com/analysis"
    date = "2025-01-29"

See style-guide.md for full conventions.

Workflow

1. Gather samples — multiple; single-sample rules are brittle
2. Extract candidates — yarGen -m samples/ --excludegood
3. Validate quality — apply the string selection tests; expect to discard 80% of yarGen output
4. Write the rule — proper metadata, cheap checks first
5. Lint and test — yr check, yr fmt, the linter script
6. Goodware validation — VirusTotal corpus or local clean files
7. Deploy — full metadata, then monitor for FPs

Quality signals along the way: a rule matching under 50% of known variants is too narrow; one matching goodware is too broad.

Reviewing a rule someone else wrote — run both scripts before reading the rule by eye, and quote the codes they emit:

uv run {baseDir}/scripts/yara_lint.py suspect.yar      # style, metadata, YARA-X compatibility
uv run {baseDir}/scripts/atom_analyzer.py suspect.yar  # atom quality per string

They catch the mechanical faults — short strings, FP-prone substrings, unbounded quantifiers, expensive terms ahead of cheap ones — so your attention goes to the judgement calls they cannot make: whether the strings identify this family, and whether the condition can fire on generic strings alone. Report findings by code (E002, W009) so the author can look each one up in style-guide.md.

See testing.md for the validation workflow and rule-development.md for the full step-by-step guide.

Common Mistakes

Quality Checklist

Before deploying any rule:

• Name follows {CATEGORY}_{PLATFORM}_{FAMILY}_{VARIANT}_{DATE}
• Description starts with "Detects" and explains what/how
• All required metadata present (author, reference, date)
• Strings are unique — not API names, common paths, or format strings
• All strings 4+ bytes with good atom potential
• Base64 modifier only on strings with 3+ characters
• Regex bounded, anchored to a literal, with { escaped
• Condition starts with cheap checks (filesize, magic bytes)
• Magic-byte constants verified against a known-good sample
• Rule matches all target samples
• Rule produces zero matches on the goodware corpus
• yr check and yr fmt --check pass
• Linter passes with no errors
• Peer review completed

Scripts

uv run {baseDir}/scripts/yara_lint.py rule.yar      # validate style/metadata
uv run {baseDir}/scripts/atom_analyzer.py rule.yar  # check string quality

See README.md for detailed script documentation.

Further Reading

The examples/ directory holds real, attributed rules worth reading before writing your own:

Rule repositories to learn from: Neo23x0/signature-base (17,000+ production rules), elastic/protections-artifacts (endpoint-tested), imp0rtp3/js-yara-rules (JavaScript), InQuest/awesome-yara (curated index).

Guides: YARA Style Guide and YARA Performance Guidelines (Neo23x0), YARA-X documentation.

macOS specifics: Apple's own production rules ship at /System/Library/CoreServices/XProtect.bundle/; objective-see publishes macOS malware research and samples.