yara-rule-authoring

Files (22)

• SKILL.md
• openai.yaml · agents/
• trail-of-bits-mark.svg · assets/
• MAL_Mac_ProtonRAT_Jan25.yar · examples/
• MAL_NPM_SupplyChain_Jan25.yar · examples/
• MAL_Win_Remcos_Jan25.yar · examples/
• SUSP_CRX_SuspiciousPermissions.yar · examples/
• SUSP_JS_Obfuscation_Jan25.yar · examples/
• crx-module.md · references/
• dex-module.md · references/
• performance.md · references/
• strings.md · references/
• style-guide.md · references/
• testing.md · references/
• atom_analyzer.py · scripts/
• pyproject.toml · scripts/
• review.sh · scripts/
• test_yara_rules.py · scripts/
• uv.lock · scripts/
• yara_lint.py · scripts/
• yara_rules.py · scripts/
• rule-development.md · workflows/

SKILL.md (first lines)

# 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`

```yara
// 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 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:

| Test | Why it fails | Do instead |
|---|---|---|
| Under 4 bytes | No atom | Find a longer string |
| Repeated bytes (`0000`, `9090`) | Weak atom | Add surrounding context |
| API name (`VirtualAlloc`, `CreateRemoteThread`) | Every packer and installer calls it | Hex pattern of the call site plus a unique marker |
| Appears in Windows system files | Guaranteed FPs | Find something family-specific |
| Common path (`C:\Windows\`, `cmd.exe`) | Ubiquitous | Find malware-specific paths |
| Appears in other malware families | Not identifying *this* family | Combine with a family-specific marker |

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

### Choosing a String Type

| Need | Use |
|---|---|

From trailofbits/skills, CC-BY-SA-4.0.

More from trailofbits/skills