YARA-X detection rule authoring with expert judgment, linting, atom analysis, and best practices. Teaches how to think like an expert YARA author for malware detection, threat hunting, and indicator-of-compromise identification using YARA-X (the Rust-based successor to legacy YARA).
YARA-X detection rule authoring with expert judgment, linting, atom analysis, and best practices. Teaches how to think like an expert YARA author for malware detection, threat hunting, and indicator-of-compromise identification using YARA-X (the Rust-based successor to legacy YARA).
["Write rules targeting YARA-X syntax and features by default","Always include metadata fields (author, date, description, reference, hash)","Use atom analysis to verify rules have efficient matching atoms","Lint rules before deployment to catch common errors","Prefer specific byte patterns over broad wildcards to reduce false positives"]
error_handling
graceful
streaming
supported
verified
true
lastVerifiedAt
"2026-03-01T00:00:00.000Z"
source
builtin
trust_score
100
provenance_sha
4f99f4c1be688483
YARA Authoring Skill
Expert YARA-X detection rule authoring skill adapted from Trail of Bits security research methodology. Guides authoring of high-quality YARA-X rules for malware detection, threat hunting, and IOC identification. Emphasizes expert judgment, atom efficiency analysis, linting, and the YARA-X Rust-based toolchain.
- YARA-X rule authoring with expert-level patterns
- YARA-X syntax and feature usage (Rust-based successor to legacy YARA)
- Rule metadata standards (author, date, description, reference, hash)
- Atom analysis for matching efficiency verification
- Rule linting and validation
- String pattern design (hex, text, regex)
- Condition logic optimization
- False positive rate minimization
- Module usage (PE, ELF, Mach-O, dotnet, math, hash)
- Rule set organization and naming conventions
- Legacy YARA to YARA-X migration guidance
Overview
This skill implements Trail of Bits' YARA authoring methodology for the agent-studio framework. YARA-X is the Rust-based successor to legacy YARA, offering improved performance, safety, and new features. This skill teaches you to think and act like an expert YARA author, producing detection rules that are precise, efficient, and maintainable.
When building threat hunting rules for IOC identification
When converting legacy YARA rules to YARA-X format
When optimizing existing rules for performance and accuracy
When reviewing YARA rules for quality and false positive rates
When building rule sets for automated scanning pipelines
Iron Laws
EVERY RULE MUST HAVE EFFICIENT ATOMS AND PASS LINTING — a rule without efficient atoms degrades scanner performance across the entire rule set; always run yr check and yr debug atoms before deployment.
NEVER write rules without testing against both positive and negative samples — false positives on clean files are as harmful as missed detections; validate FP rate before deploying.
ALWAYS include complete metadata (author, date, description, reference, hash) — rules without metadata are unauditable and unmaintainable in enterprise rule sets.
NEVER use single-byte atoms or patterns starting with common bytes (0x00, 0xFF, 0x90) — these generate massive false positive rates and degrade the entire YARA scanning pipeline.
ALWAYS use YARA-X toolchain (yr) by default — legacy / tooling lacks memory safety, performance optimizations, and modern module support; use YARA-X unless backward compatibility is explicitly required.
yara
yarac
YARA-X vs Legacy YARA
Key Differences
Feature
Legacy YARA
YARA-X
Language
C
Rust
Safety
Manual memory management
Memory-safe
Performance
Good
Better (parallelism)
Modules
PE, ELF, math, etc.
Same + new modules
Syntax
YARA syntax
Compatible + extensions
Toolchain
yara, yarac
yr CLI
YARA-X CLI Commands
# Scan a file
yr scan rule.yar target_file
# Check rule syntax
yr check rule.yar
# View rule atoms (for efficiency analysis)
yr debug atoms rule.yar
# Format a rule
yr fmt rule.yar
Rule Structure
Standard Template
import "pe"
import "math"
rule MalwareFamily_Variant : tag1 tag2 {
meta:
author = "analyst-name"
date = "2026-02-21"
description = "Detects MalwareFamily variant based on [specific indicators]"
reference = "https://example.com/analysis-report"
hash = "sha256-of-sample"
tlp = "WHITE"
score = 75
strings:
// Unique byte sequences from the malware
$hex_pattern1 = { 48 8B 05 ?? ?? ?? ?? 48 89 45 F0 }
$hex_pattern2 = { E8 ?? ?? ?? ?? 85 C0 74 ?? }
// String indicators
$str_mutex = "Global\\MalwareMutex_v2" ascii wide
$str_c2 = "https://evil.example.com/gate.php" ascii
$str_useragent = "Mozilla/5.0 (compatible; MalBot/1.0)" ascii
// Encoded/obfuscated patterns
$b64_config = "aHR0cHM6Ly9ldmlsLmV4YW1wbGUuY29t" ascii // base64
condition:
uint16(0) == 0x5A4D and // MZ header (PE file)
filesize < 5MB and
(
2 of ($hex_*) or
($str_mutex and 1 of ($str_c2, $str_useragent)) or
$b64_config
)
}
// Use sparingly - regex is slower than literal strings
$re1 = /https?:\/\/[a-z0-9\-\.]+\.(xyz|top|club)\//
// Prefer hex patterns over regex for binary content
// WRONG: $re2 = /\x48\x8B\x05/
// RIGHT: $hex2 = { 48 8B 05 }
Atom Analysis
Atoms are the fixed byte sequences YARA uses to pre-filter which rules to evaluate. Efficient atoms = fast scanning.
How to Check Atoms
# View atoms for a rule
yr debug atoms rule.yar
# Good output: unique 4+ byte atoms# Atom: 48 8B 05 (from $hex_pattern1)# Atom: CreateRemoteThread (from $str1)# Bad output: short or common atoms# Atom: 00 00 (too common, will match everything)
Atom Quality Guidelines
Atom Length
Quality
Action
1-2 bytes
Poor
Rewrite pattern with more specific bytes
3 bytes
Acceptable
Consider extending if possible
4+ bytes
Good
Ideal for efficient scanning
Common bytes (00, FF, 90)
Poor
Avoid patterns starting with common bytes
Condition Logic
Performance-Ordered Conditions
Place cheap checks first to enable short-circuit evaluation:
condition:
// 1. File type check (instant)
uint16(0) == 0x5A4D and
// 2. File size check (instant)
filesize < 10MB and
// 3. Simple string matches (fast)
$str_mutex and
// 4. Complex conditions (slower)
2 of ($hex_*) and
// 5. Module calls (slowest)
pe.imports("kernel32.dll", "VirtualAllocEx")
Common Condition Patterns
// At least N of a set
2 of ($indicator_*)
// All of a set
all of ($required_*)
// Any of a set
any of ($optional_*)
// String at specific offset
$mz at 0
// String in specific range
$header in (0..1024)
// Count-based
#suspicious_call > 5
Rule Categories
Category 1: Malware Family Detection
Targets specific malware families with high-confidence indicators.
Expensive string matching runs on non-matching file types
Place uint16(0) == 0x5A4D (or equivalent) first in every condition
Using nocase on short strings
Short case-insensitive patterns match everywhere in arbitrary data
Reserve nocase for strings >= 8 bytes; use exact case for shorter patterns
Memory Protocol
Before starting: Check for existing YARA rules in the project for naming conventions and pattern reuse.
During authoring: Write rules incrementally, testing each against the target sample. Document atom analysis results.
After completion: Record effective patterns, atom quality metrics, and false positive rates to .claude/context/memory/learnings.md for improving future rule authoring.
