Syntax & synopsis

strixd — the scanning backend

One binary, several subcommands. With no command it defaults to serve. Run strixd <command> -h for that command's own flags.

strixd <command> [flags]

  serve        run the HTTP backend (/scan, /metrics, /health) — the default
  scan         scan files/dirs/stdin against the rules in-process
  fetch-rules  download an updated compiled rule bundle into the cache
  check-rules  compile the rules, print the count, exit non-zero on failure
  extract      dump what the container extractor carves from a file (no scan)
  info         print build, libyara, and loaded-rules-bundle identity
  health       probe the local /health endpoint (container HEALTHCHECK)
  version      print the version

extract is the debugging window into the moat: it shows every layer Mailstrix carves out of a file — OLE/OOXML parts, decompressed VBA, archive members, carved PE/ELF — without running YARA, so you can see exactly what the matcher will be handed.

strixd serve — flags

Each flag mirrors an environment variable (shown in parentheses); the flag overrides it.

strix-scan — the CGO-free client

A tiny client with no libyara dependency, for the Sieve/LDA path and for boxes that can't link a C library. It reads a file argument (or stdin), POSTs it to a running strixd, and signals the verdict through its exit code — 0 = clean/no-match (and on a transport error when -fail-open), non-zero = match or hard error.

strix-scan [flags] [file|-]

Environment variables

Every MAILSTRIX_* knob, grouped. Booleans accept any non-empty value as true. Durations like the refresh/TTL/timeout values are seconds unless a serve flag accepts Go duration syntax (500ms, 2s). All values are clamped to safe ranges at startup, so a non-positive value cannot disable a guard.

Server & admission

Effort

Authentication

Rules & cache

Verdict cache

Threat-intel feeds (abuse.ch)

All feeds are optional and refresh in the background. Refresh values are seconds.

Logging

The strix-scan client reads MAILSTRIX_URL and MAILSTRIX_TOKEN from the environment too.

HTTP API

The serve backend exposes five routes. Only /scan (and optionally /metrics) require the token; the health probes are always open so orchestrators can probe without a secret.

# scan a file, token in a Bearer header
curl -sS -X POST http://127.0.0.1:8079/scan \
  -H "Authorization: Bearer $MAILSTRIX_TOKEN" \
  -H "X-MAILSTRIX-Filename: invoice.docm" \
  --data-binary @invoice.docm

Request headers

JSON verdict

A 200 with a matches array. The array is empty, never null, on a clean message, so a caller can branch on length alone. Each match names the rule and the source ruleset namespace, plus any tags and metadata.

{
  "matches": [
    {
      "rule": "SUSP_VBA_Shell_Exec",
      "namespace": "sigbase-gen_office.yar",
      "tags": ["macro", "exec"],
      "meta": { "author": "Florian Roth", "score": "75" }
    }
  ]
}

A scan error, timeout or libyara panic returns an empty matches array — Mailstrix fails open by design, so the scanner can never become a mail-delivery outage. The error is still counted in /metrics.

Rules & bundles

Mailstrix doesn't author rules — it packages roughly 10,000 public rules from eight curated upstreams, precompiled to a .yac bundle and rebuilt daily. The full list and per-set licenses are on the front page FAQ.

• Each rule file compiles into its own libyara namespace named after the file, so the verdict's namespace tells you which ruleset fired.
• A writable CACHE_DIR holds the live bundle and self-heals from SEED_RULES on a fresh deploy; fetch-rules pulls the daily rules-current release into it.
• Any upstream can be pinned or disabled at build time with a per-source build arg (e.g. DIDIER=0).
• Allowlist/denylist narrow the active set without recompiling; the denylist reloads on SIGHUP with no downtime.

Deploy quickstarts

Docker

docker run -d --name mailstrix \
  -p 127.0.0.1:8079:8079 \
  -e MAILSTRIX_TOKEN_FILE=/run/secrets/mailstrix \
  eilandert/mailstrix:latest

strix-scan from a Sieve/LDA pipe

strix-scan -url http://127.0.0.1:8079 \
  -token-file /etc/mailstrix/token \
  -filename "$ATTACHMENT_NAME" message.eml
# exit 0 = clean, non-zero = match

The five integration paths (rspamd, SpamAssassin, Sieve, ICAP, standalone) each have a ready-made config under contrib/; a Debian package, a Helm chart and full deployment docs live in the GitHub repository.