eilandert/mailstrix repository overview

⁠strixd — YARA malware scanning for rspamd

Mailstrix is the owl that finds malware hiding in your mail. It takes hostile attachments apart — unwrapping OLE2/OOXML, VBA, RTF objects, PDFs, archives and nested carriers — until YARA detection rules can finally see the dangerous bits. It runs out-of-process behind Rspamd (async HTTP), SpamAssassin, an ICAP server, Dovecot Sieve, or standalone.

strixd is a small HTTP service that scans email for malware with YARA⁠. You hand it a message (or one attachment) on POST /scan; it runs ~10,000 curated public YARA rules over it and tells you which ones matched. It ships as a ready-to-run Docker image with the rules already baked in — see Quick start⁠ below or pull it straight from Docker Hub⁠.

Why YARA, in one paragraph. YARA is the rule engine malware analysts use to recognise families of malicious files — booby-trapped Office docs, packed executables, phishing kits, script droppers. A plain string signature dies the moment the author edits one byte; a YARA rule matches the shape of a file (PE imports, section entropy, embedded magic) and survives the next variant. strixd compiles those rules — libyara modules and all — and runs them over your mail.

Four ways to plug it into a mail server, all shipped in this repo:

• rspamd — an async mailstrix.lua plugin (contrib/rspamd/⁠) POSTs each message/part to strixd at SMTP time and turns the hits into a spam-score symbol.
• SpamAssassin — the Mailstrix.pm⁠ plugin scans each message through the same central service and turns a YARA match into a spam-score hit (contrib/spamassassin/⁠).
• Dovecot / Sieve — the lean strix-scan⁠ client scans at delivery and a Sieve rule quarantines a match (contrib/sieve/⁠).
• ICAP — set MAILSTRIX_ICAP_ADDR and strixd also speaks ICAP (RFC 3507) so an ICAP-aware proxy or content-filter (Squid, c-icap) scans REQMOD/RESPMOD bodies through the same engine (ICAP mode⁠).

 ┌──────────────────────┐  POST /scan  ┌──────────────┐    ┌──────────────┐
 │ rspamd (mailstrix.lua)│ ───────────▶ │    strixd    │ ─▶ │   libyara    │
 │ SpamAssassin / Sieve  │ ◀─────────── │ (Go service) │    │compiled rules│
 │ (strix-scan) / ICAP   │   {matches}  └──────────────┘    └──────────────┘
 └──────────────────────┘

It runs out of process, never inside the MTA worker, because libyara is a C library (CGO): in an rspamd worker it would block the event loop and drag a heavy C dependency into the mail image. Separate, the caller stays async and strixd can be scaled, restarted, or reload its rules on its own. Same shape as the gozer⁠ DCC/Razor/Pyzor backend.

⁠Exactly what it does

• Scans mail with YARA — POST /scan raw message bytes (or one MIME part), get back the matched rules as JSON; the rspamd mailstrix.lua plugin (contrib/rspamd/⁠) wires the hits into the spam score, or the strix-scan client scans at delivery from Dovecot/Sieve (contrib/sieve/⁠).
• Ships ~10k public rules baked in — YARA-Forge, signature-base, ANY.RUN, Didier Stevens, bartblaze, InQuest, CAPEv2, YARAify; precompiled .yac, daily refresh.
• Decompresses Office macros before matching — MS-OVBA VBA out of .docm/.xlsm/.doc/.xls, scans the cleartext (sets the VBA rule var).
• Cracks open containers — pulls the hidden payload out of: OLE2/OOXML, RTF \objdata, OLE Package (Ole10Native), MSI, Outlook .msg, TNEF (winmail.dat), OneNote .one, PDF (FlateDecode streams), .lnk shortcuts, VBE/JSE encoded scripts, and nested archives (zip/7z/rar/gz/tar.gz/cab, recursive) — then scans each.
• Deobfuscates before matching — decodes long base64/hex runs, undoes StrReverse, and folds the olevba string set (Chr/ChrW concat, Replace(), Array() Xor k, Environ, Dridex DridexUrlDecode) to cleartext; a bounded recursive pass unwinds multi-stage (2+-layer) payloads, not just the first layer.
• Resolves Excel 4.0 (XLM) macros — detects hidden/very-hidden macrosheets (OOXML + legacy .xls BIFF), reassembles ptg-token formula strings (BIFF8/.xlsb/SLK), and runs a bounded XLM emulator (cell eval, GOTO, SET.VALUE) to resolve obfuscated cell references.
• Triages PDFs — surfaces /OpenAction, /JS, /Launch, /EmbeddedFile, /JBIG2Decode and hex-name obfuscation as scoreable markers.
• Catches macro-less & exploit attacks — Equation Editor (CVE-2017-11882), remote-template injection (CVE-2017-0199 / T1221), DDE/DDEAUTO fields, MHTML/x-usc (CVE-2021-40444), Shell.Explorer CLSID, and OLE structural indicators (ObjectPool, embedded Flash, digital-signature, doc-security).
• Decrypts default-password documents — VelvetSweatshop XOR, BIFF8 RC4, and OOXML agile/standard AES, so an "encrypted" but default-keyed payload is unlocked and re-scanned (other encryption is flagged, not cracked).
• Analyses carved executables — PE/ELF structural checks on embedded/decoded binaries (section entropy / packing, overlay, .NET, anomalies), plus base64-PE carving that re-aligns a padded MZ header so the pe rules fire.
• Ships its own heuristic rules — an mraptor-style autoexec∧write∧execute rule, olevba suspicious-keyword / VBA-shellcode-API heuristics, LOLBin / WMI / PowerShell / anti-analysis intent rules, HTML-smuggling (data: URI, embedded SVG) detection, and a position-independent-shellcode GetEIP prologue rule.
• Scales effort under load — a single 1–10 effort dial (MAILSTRIX_EFFORT) scales decode depth, XLM/PDF clamps, feeds and scan timeout; auto sheds a level at a time as the admission gate fills and climbs back as it drains.
• Speaks ICAP too (optional) — MAILSTRIX_ICAP_ADDR adds an RFC 3507 REQMOD/RESPMOD listener for ICAP-aware proxies, sharing the same scan engine, cache and concurrency gate as /scan.
• Uses the attachment name — filename/extension YARA vars from the plugin's X-MAILSTRIX-Filename, so name-keyed (THOR/Loki) rules fire.
• Checks abuse.ch feeds (optional) — URLhaus malware-URL/host lookup (with URL defanging), MalwareBazaar attachment-SHA256 lookup, ThreatFox URL/domain IOCs, and the Feodo Tracker C&C IP blocklist; all cached, fail-open.
• Drops/demotes noisy rules — MAILSTRIX_RULE_DENYLIST (suppress) and MAILSTRIX_RULE_ALLOWLIST (keep but score log-only) without patching upstream.
• Caches verdicts — SHA256(body) → matches (LRU+TTL), plus request coalescing and an optional shared Redis/Valkey L2, for a high-volume firehose.
• Fails open, always — a scan error, timeout, or libyara panic is reported as "no match"; a broken scanner never blocks mail. Bounded concurrency, per-scan timeout, body cap, graceful drain on SIGTERM.
• Updatable rules without a rebuild — strixd fetch-rules pulls a version-matched, sha256-verified compiled bundle into a cache; SIGHUP reloads.
• CLI tools — strixd scan (local triage), strixd extract (dump what a container carves), strixd check-rules, strixd info; and strix-scan, a tiny CGO-free client for a Dovecot/Sieve box (contrib/sieve/⁠).
• Observable — /health, /ready, /version, Prometheus /metrics (scans, matches, cache, per-extractor counters, rule staleness).

⁠Install

Three ways, pick one:

Debian/Ubuntu package (.deb, amd64 + arm64) — attached to every release⁠:

# Resolve the latest version + your arch (release assets are version-pinned,
# e.g. strixd_1.1.1_amd64.deb — the bare latest/download/ path is not).
VER=$(curl -fsSL https://api.github.com/repos/eilandert/mailstrix/releases/latest \
        | grep -oP '"tag_name":\s*"v\K[^"]+')
ARCH=$(dpkg --print-architecture)   # amd64 or arm64
BASE=https://github.com/eilandert/mailstrix/releases/download/v${VER}

# strixd — the daemon (systemd unit + /etc/mailstrix/strixd.env config)
curl -fsSLO "${BASE}/strixd_${VER}_${ARCH}.deb"
sudo apt install "./strixd_${VER}_${ARCH}.deb"

# fetch the rolling compiled rule bundle into the cache dir, then start it
sudo -u strixd strixd fetch-rules -cache-dir /var/cache/mailstrix   # or drop your own .yar in /var/lib/mailstrix/rules
sudoedit /etc/mailstrix/strixd.env                                 # set MAILSTRIX_TOKEN, feeds, …
sudo systemctl enable --now strixd

# strix-scan — the lean CGO-free Sieve/LDA client (no daemon)
curl -fsSLO "${BASE}/strix-scan_${VER}_${ARCH}.deb"
sudo apt install "./strix-scan_${VER}_${ARCH}.deb"

The daemon package installs a hardened systemd unit (unprivileged strixd user, ProtectSystem=strict, NoNewPrivileges) and a documented /etc/mailstrix/strixd.env. State (rules) lives in /var/lib/mailstrix.

Static binaries — strixd-linux-{amd64,arm64} and strix-scan-linux-{amd64,arm64} plus SHA256SUMS are on the same release page.

Docker — see Quick start⁠ below (rules baked in).

⁠Quick start

The image already bakes ~10k rules, so a token is all you need:

docker run -d --name strixd \
    -e MAILSTRIX_TOKEN=changeme \
    -p 8079:8079 \
    eilandert/mailstrix

# ask it something:
printf 'hello' | curl -s -H 'X-MAILSTRIX-Token: changeme' \
    --data-binary @- http://127.0.0.1:8079/scan
# -> {"matches":[]}

To use your own rules instead of the baked bundle:

docker run -d --name strixd \
    -e MAILSTRIX_TOKEN=changeme \
    -e MAILSTRIX_RULES= \
    -e MAILSTRIX_RULES_DIR=/rules \
    -v "$PWD/myrules:/rules:ro" \
    -p 8079:8079 \
    eilandert/mailstrix

Send an attachment name so name-keyed rules fire (base64 — the name is attacker-controlled, encoding it stops header injection):

printf 'MZ...' | curl -s -H 'X-MAILSTRIX-Token: changeme' \
    -H "X-MAILSTRIX-Filename: $(printf 'invoice.exe' | base64)" \
    --data-binary @- http://127.0.0.1:8079/scan

The /scan reply names the rule and its source ruleset file:

{"matches":[{"rule":"Suspicious_Macro","namespace":"sigbase-gen_maldoc.yar","tags":["office"],"meta":{"author":"…"}}]}

The list is [] (never null) when nothing matched. namespace is the file the rule was compiled from, so a generic rule like http is traceable to the set that shipped it. For the hardened container setup (read-only rootfs, dropped caps, Docker secret, static IPv4) see docker/docker-compose.yml⁠.

⁠Scanning without a server

The same binary scans locally — no HTTP, no token — by compiling the rules in-process. For one-off triage and pipelines:

strixd scan suspicious.doc            # one file
strixd scan /var/mail/cur             # a maildir, recursed
cat msg.eml | strixd scan             # stdin
strixd scan -json /tmp/quarantine     # machine-readable

Exit codes: 0 clean, 1 ≥1 match, 2 usage/load/read error. Other helpers share the binary (strixd help):

strixd check-rules            # compile rules, print the count, non-zero on failure (CI gate)
strixd extract suspicious.doc # show what the extractor carves (no scan)
strixd fetch-rules            # update the cached rule bundle from the release
strixd info                   # build / libyara / loaded-bundle identity

⁠Updating rules without rebuilding (fetch-rules)

Rules move faster than image rebuilds — and outside Docker you'd otherwise need yarac + a matching libyara to compile them. strixd fetch-rules downloads a prebuilt, version-matched bundle into the cache instead:

strixd fetch-rules -cache-dir /var/cache/mailstrix

It reads a small manifest first and updates only when the published version is newer; it refuses a bundle built against a different libyara, verifies the sha256, and swaps atomically (keeping one .bak). On any error the current bundle is untouched. Then SIGHUP (or restart) strixd to load it. The bundle is published by docker/generate-rules.sh (run from cron); point -url / MAILSTRIX_RULES_URL at a mirror if not fetching from GitHub.

⁠Thin client for Dovecot / Sieve (strix-scan)

strixd scan (above) compiles the rules in-process, so it needs libyara and the rule set on the host that runs it — fine on the scanner box, too heavy for a mail-delivery box that should stay thin. strix-scan is the answer: a separate, tiny client that links no CGO / libyara and embeds no rules — pure Go, a ~6 MB static binary you can drop on any mail host. It just reads the message (stdin or a file), POSTs it to a central strixd serve, and exits on the verdict — so all the CPU-heavy scanning stays on the central service.

# stdin or a file; exit code carries the verdict:
strix-scan -url http://strixd.internal:8079 -token-file /etc/strixd.token - < message
cat message | strix-scan -url http://strixd.internal:8079

• Fails open by default — any transport error, timeout, or non-200 is treated as clean (exit 0), so a scanner outage never blocks or bounces delivery. Pass -fail-open=false for interactive triage where a silent miss is worse.
• Token via -token-file or MAILSTRIX_TOKEN — never -token on a shared host (it shows in ps). Redirects are never followed, so the token can't leak to a 3xx target.
• Same wire format as the rspamd plugin: X-MAILSTRIX-Token for auth, base64 X-MAILSTRIX-Filename for the attachment name.

This is the delivery-time path from the opinion in the intro: let rspamd drop the obvious spam at SMTP, then scan the smaller, cleaner stream with YARA at delivery and quarantine a hit — off the connection's critical path.

A ready-to-use Dovecot Sieve example (the execute rule, an install wrapper, the dovecot config, and a setup/test walkthrough) lives in contrib/sieve/⁠. Because the client fails open, a delivery is never lost if the backend is down.

⁠Configuration

Every setting is an env var and a serve CLI flag (flag > env > default).

Reload rules: docker kill -s HUP strixd recompiles in place and flushes the cache. A reload that fails to compile keeps the previous (working) rules — a bad edit can't disarm a running scanner. On SIGTERM/SIGINT strixd drains (/ready → 503, in-flight scans finish) before exiting — safe for rolling updates.

⁠Sizing profiles

MAILSTRIX_MAX_CONCURRENT defaults to the CPU count (auto). On a many-core host (32+ CPUs) that reserves significant memory. The request-buffer ceiling is set by the admission gate, not the scan gate: up to MAX_INFLIGHT requests can each hold a full body plus its extracted streams, so the startup log estimates peak resident as roughly MAX_INFLIGHT × MAX_BODY + RSS (the loaded-rules resident set). Size mem_limit accordingly and pin MAX_CONCURRENT/MAX_INFLIGHT explicitly when the defaults are too aggressive.

MAILSTRIX_MAX_INFLIGHT (default 2×MAX_CONCURRENT) is the admission gate — excess requests receive a 503 immediately rather than queuing. Keep it above MAX_CONCURRENT so a slow body read or Redis round-trip can't starve scan slots.

Redis/Valkey L2 (MAILSTRIX_REDIS_URL) dramatically improves throughput for repeated attachments, which is common in mail (bulk campaigns, MTA retries, one body to N recipients). Without it each scanner instance maintains its own in-process LRU only.

Notes:

• MalwareBazaar full-dump mode (MAILSTRIX_MBAZAAR_KEY set) adds ~40 MiB resident plus a ~100–150 MiB transient spike on refresh — raise mem_limit to ~768m in that case.
• For the Large profile, run multiple replicas behind a load balancer rather than one container with a very high MAX_CONCURRENT: smaller per-container concurrency improves tail latency under burst load and avoids one libyara panic taking all capacity.
• MAILSTRIX_BACKEND_TIMEOUT (default 1s) caps how long a request waits for an admission slot. Under sustained overload this is the 503 fuse — keep it short so callers (rspamd) fail fast rather than stacking connections.

⁠Rules

The image bakes eight public rulesets at build time; a daily rebuild (--build-arg CACHEBUST=$(date +%s)) re-pulls the latest. Full credit to the authors — strixd only packages their work. Each set keeps its own license:

| Ruleset | Author / source | License | Notes |