YARA Rules Guide: Writing, Testing and Managing Detection Rules

YARA rules are the common language for describing what a malicious or sensitive file looks like, but a rule that is slow, vague or untested either misses what it should find or buries analysts in false positives. YARA matches text, hex and regular expression patterns in files or memory and evaluates a boolean condition over them. Since June 2025 the original C implementation has been in maintenance mode and YARA-X, the Rust rewrite, is the engine for new work. This guide covers how rules are built, how to write them for performance, how to test them against goodware before deployment, how to run a rule library as code, and where YARA fits beside a SIEM and EDR. It is written for detection engineers, incident responders and threat intelligence analysts. It does not cover writing rules for specific malware samples step by step; see the Malware Guide for background.

Key takeaways

• Start new work on YARA-X. VirusTotal declared YARA-X stable with version 1.0.0 in June 2025 and put the original YARA into maintenance mode, with only critical bug fixes and security patches. Rule syntax is largely compatible, but the APIs are not.
• Strings decide speed and accuracy. YARA searches for short atoms from each pattern first and only then evaluates conditions, so a weak pattern cannot be rescued by a clever condition.
• Test against goodware before production. Every rule should run clean over a representative set of legitimate files (operating system images, common software, your own builds) before it is allowed to alert.
• Manage rules like code. Use a repository with required metadata, automatic formatting and compile checks in CI, peer review, and versioned releases to scanners.
• YARA is not only for malware. Rules that find hard-coded credentials, private keys or web shells in files, artefacts and backups are a practical way to find exposed non-human identity secrets.

YARA and YARA-X in 2026

YARA was created by Victor M. Alvarez at VirusTotal and became the de facto format for sharing file detection logic among researchers, vendors and government agencies. Its successor, YARA-X, was written in Rust by the same project.

• Migration: compile your whole corpus with yr compile, fix errors, then use yr fix warnings for warnings it can fix automatically and yr fix encoding for files that are not valid UTF-8. Review the YARA-X "differences" documentation for behaviour changes before trusting results.
• Keep YARA where you need it: process memory scanning and tools embedding yara-python still need the original engine. Track those as technical debt with an owner.
• Scanning services moved first: VirusTotal announced in December 2024 that YARA-X powers its Livehunt and Retrohunt services.

Anatomy of a rule

A rule has a name, optional tags, and up to three sections: meta (descriptive key-value pairs), strings (patterns, also called strings) and condition (a required boolean expression). Rules can be declared private (used by other rules but not reported) or global (applied as a precondition to all rules in the namespace), and files can import modules such as pe, elf, macho, dotnet, lnk, math, hash and time.

• Hex patterns: written in braces with wildcards (??), jumps ([2-4]) and alternatives. Keep at least one long concrete run of bytes.
• Conditions: boolean operators, counts (#a > 2), offsets ($a at 0, @a[1]), sets (2 of ($s*), any of them), filesize with KB and MB suffixes, integer reads such as uint16(0) == 0x5A4D, and loops (for any i in (...)).
• External variables: values passed at scan time (--define in YARA-X) let one rule behave differently per file path or context, for example to suppress a match in a known vendor directory.

Writing rules that perform

The community YARA Performance Guidelines describe four scanning steps: extract atoms (up to four bytes) from each pattern at compile time, run an Aho-Corasick search for those atoms, verify full matches with the bytecode engine, then evaluate conditions. Most performance problems are pattern problems.

• Avoid short or common patterns: anything under four bytes, runs of the same byte (00 00 00 00) or common words gives poor atoms and floods the matcher.
• Anchor regular expressions: include a fixed substring of at least four bytes and bound every quantifier; .*, .+ and {x,} without an upper limit cause slow scans and "too many matches" errors.
• Cheap checks first: conditions short-circuit left to right, so put filesize and magic-byte checks such as uint16(0) == 0x5A4D before costly expressions.
• Use modules only when needed: modules such as pe parse the whole file; a header check is enough when you only need to know a file is a PE.
• Avoid loops over the file: for any i in (0..filesize-1) style loops are slow in both engines; YARA-X emits a potentially_slow_loop warning and a slow_pattern warning for costly patterns.
• Measure: YARA-X added rule profiling in 0.11.0 (yr scan --profiling, in a build with the rules-profiling feature) to list the slowest rules. Run it on a representative corpus before each release.

Example: finding hard-coded credentials in files

YARA is useful for finding exposed machine credentials in places secret scanners on Git do not reach: release archives, container image layers exported to disk, backups, file shares and decompiled mobile apps. The rule below is illustrative; it detects AWS access key IDs and private key blocks in text files under 2 MB.

rule SECRETS_Hardcoded_Cloud_Key_Or_Private_Key
{
  meta:
    author = "[Organisation] detection engineering"
    description = "AWS access key ID or PEM private key block in a small file"
    date = "2026-10-24"
    score = 60
    reference = "Internal standard: no credentials in artefacts"

  strings:
    $aws_key_id = /(AKIA|ASIA)[0-9A-Z]{16}/ fullword
    $pem_begin = "-----BEGIN "
    $pem_private = "PRIVATE KEY-----"

  condition:
    filesize < 2MB and
    ($aws_key_id or ($pem_begin and $pem_private))
}

• Why it is built this way: the regex starts with fixed four-byte prefixes, so it produces good atoms; the PEM check uses two plain strings rather than one long regex; the filesize check runs first.
• Expected false positives: documentation, test fixtures and AWS's own published example key (AKIAIOSFODNN7EXAMPLE). Exclude these with path-based external variables or an allowlist of hashes rather than weakening the pattern.
• What to do with a hit: treat it as a possible exposed secret: identify the owner, rotate the credential, then remove it from the artefact. See the Secrets Management Guide and the Git Secret Scanning Guide.

The Rabbit R1 hard-coded API keys case shows the problem this solves: working ElevenLabs, Azure, Yelp and Google Maps keys sat in a codebase that an insider copied out, so anyone holding the copy held the keys.

Testing against goodware and malware corpora

A rule is ready when it matches what it should, misses what it should, and runs fast enough. Build that into a repeatable test harness rather than a one-off scan.

• Keep samples safe: store malicious reference files in an isolated, access-controlled repository or reference them by hash; never commit live malware to the rules repository. Synthetic test files are enough for many content rules, such as the credential example above.
• Retest on change: run the full suite whenever a rule, a module or the engine version changes, because engine upgrades can change matching behaviour.
• Use the scanning service's tests: VirusTotal Livehunt lets rulesets be tested against specific hashes and rejects rules that trigger performance warnings; it also refuses include statements and rulesets over 1 MB of text, which is a useful discipline for any library.

Managing rules in a repository

1. Structure: one rule or one tight family per file, folders by purpose (malware families, tooling, web shells, secrets, hunting), and a naming convention. The community YARA Style Guide uses underscore-separated categories such as MAL_, HKTL_, SUSP_ and APT_ prefixes.
2. Required metadata: at minimum author, description, date, reference and a confidence or score value, plus an ID and ATT&CK technique where relevant. YARA-X's ~/.yara-x.toml [check] section can enforce a rule name regexp, required metadata fields with types and patterns, and allowed tags; the YARA language server can enforce the same in the editor.
3. CI pipeline: on every pull request run the formatter in check mode, compile all rules, run the true-positive, goodware and performance tests, and block merges on failure.
4. Review: a second analyst approves every rule and every exclusion; record why a rule exists and when it should be retired.
5. Release: tag versions, compile to a binary rules file with yr compile where scanners support it, and distribute signed or checksummed bundles to scanners.
6. Roll out in stages: deploy new rules in report-only mode to a pilot ring, review hits for a week or two, then enable alerting or automated actions. Roll back by redeploying the previous tagged bundle.
7. Third-party rules: pin public rule sets to a commit, review licences, and run them through the same goodware tests before importing.

See the Detection Engineering Guide for the wider detection-as-code lifecycle and the GitHub and GitHub Actions Security Guide for protecting the repository and its CI tokens.

Where YARA runs and how to choose

YARA versus other rule formats: YARA describes file and memory content; Sigma describes log events; Snort and Suricata rules describe network traffic; Google SecOps' YARA-L describes UDM events despite the similar name. Use YARA when the evidence is in bytes. See the SIEM Guide, the Google Security Operations (Chronicle) Guide and the Threat Hunting Guide.

Small versus large teams: a small team gets most value from a curated public rule set plus a handful of internal rules for its own secrets and web applications, scanned on a schedule. A large team needs the full repository pipeline, a goodware corpus maintained as an asset, and per-scanner compatibility testing across YARA and YARA-X.

Detection and measurement

• Log every scan: send matches with rule name, rule version, file path, hash, host and scanner engine version to the SIEM so hits can be correlated with process and network events.
• Alert on scanner health: scanners that stop reporting, or rule bundles older than the current release, are coverage gaps. Disabling security tools maps to ATT&CK T1685 Disable or Modify Tools.

Metrics:

• False positive rate per rule in the first 30 days in production.
• Percentage of rules with complete required metadata and an owner.
• Percentage of rules passing goodware and performance tests in CI (target 100 percent).
• Median time from new indicator or report to a tested rule in production.
• Scanner coverage: endpoints or stores scanned with the current bundle in the last 7 days.
• Rules with no hits in 12 months reviewed for retirement.

Common failure patterns

• Copying public rules unreviewed: imported rules with broad strings flag installers and admin tools, and teams then disable the whole rule set rather than tune it.
• Single-string rules: one generic string, often a common API name or a short path, matches thousands of legitimate files.
• Unbounded regex: a rule with .* passes testing on small files and then times out on large archives in production.
• Testing only against malware: rules prove they match samples but were never run over goodware.
• Scanning only source: teams scan Git but not release archives, test fixtures and binary files. The XZ Utils backdoor payload was in a build macro and binary test files in release tarballs, not in the Git source reviewers normally read, which is why content scanning should include what is actually shipped.
• Engine drift: the same rule behaves differently across scanners on different YARA or YARA-X versions, and nobody tracks which version each scanner runs.

Framework mapping

Practitioner checklist

• Choose YARA-X for new scanners and rule work; list any tools still tied to the original YARA and plan their migration.
• Compile the full corpus with yr compile and resolve errors and warnings before switching engines.
• Enforce naming, required metadata and tags with the YARA-X [check] configuration and CI.
• Maintain a goodware corpus and require every rule to pass it before production.
• Profile rules on a large mixed corpus each release and fix or justify the slowest.
• Deploy new rules report-only to a pilot ring, then enable alerting; keep the previous bundle for rollback.
• Add rules for hard-coded credentials and private keys and scan artefacts, backups and images, not just Git.
• Send all matches with rule version and engine version to the SIEM.
• Pin and review third-party rule sets before import.
• Review rules with no hits or high false positive rates at least twice a year.

Standards and references

• VirusTotal: YARA-X documentation
• VirusTotal: YARA-X is stable
• VirusTotal: Writing YARA rules
• VirusTotal: Livehunt
• MITRE D3FEND: File Content Rules
• MITRE ATT&CK: Credentials In Files
• YARA Performance Guidelines (community)
• YARA Style Guide (community)

Related NHI Mgmt Group resources: Detection Engineering Guide · Threat Hunting Guide · Malware Guide · Secrets Management Guide · Incident Response Guide