For MailRules v0.3.0View this page on GitHub

Security

MailRules' safe defaults, how sign-in works, how to delete your account in the hosted version, how to put it behind a reverse proxy with TLS, how mail server certificates are checked, which mail servers the hosted version connects to, what is never logged, and how to report a vulnerability.

Safe by default

  • Local only. MailRules listens on 127.0.0.1:8080, so nothing outside the machine can reach it. The Docker setups publish the port to 127.0.0.1 only.
  • Dry-run on. A new install changes nothing in your mailbox until you switch dry-run off. See Dry-run and going live.
  • Mail stays unread. Mail is fetched without marking it read.
  • Nothing is deleted. MailRules never permanently deletes mail. Where a server cannot move mail directly, it copies the email and then removes only that one message from the old folder.
  • Everything can be undone. Every change is logged before it is made, and can be undone for 30 days.

Signing in

MailRules has one admin account, created on first run. It protects the web UI and the HTTP API.

  • The password must be at least 12 characters. It is stored only as an Argon2id hash.
  • After 5 failed sign-ins within a minute from the same address, sign-in is refused for a minute (“Too many failed sign-ins. Wait a minute and try again.”). A second limit counts per email address, whatever address the tries come from: 10 failures in a minute refuse that email for a minute, even with the right password. It stops someone rotating addresses to guess the admin password, at the price that they can keep you out for a minute at a time. There is no permanent lockout.
  • Signing in sets a session cookie, mailrules_session, that lasts 30 days and is renewed as you use MailRules. It is HttpOnly and SameSite=Strict. Sign out, at the bottom of the sidebar, ends the session on the server too.
  • Every request that changes something must carry a CSRF token (the X-CSRF-Token header), which the web UI sends for you.
  • To change the password while signed in, or to reset it when you have lost it, see Changing or resetting the password.

Changing or resetting the password

Change it while signed in. Send the current and the new password to the HTTP API (the web UI has no screen for this yet). The new password must be at least 12 characters. A wrong current password is refused, and five wrong ones in a minute lock the change for a minute. A change ends every session, including one that someone else may have stolen; the browser that made it gets a new session and stays signed in. See POST /api/auth/password in the HTTP API.

Reset it when you have lost it. Run this on the machine that holds the data directory, with the same MAILRULES_DATA_DIR as the daemon:

mailrules users reset-password

It asks for the new password twice, without showing it, and ends every session; sign in again with the new one. There is no email reset: whoever can run the command on the host can already read the data directory, so the command asks for nothing more. It works while MailRules is running. It does not need the master key and never prints or logs the password.

  • To script it, give the password in a file (--password-file PATH) or in the environment variable MAILRULES_USER_PASSWORD, or pipe one line to it. It is never a flag, where other users of the machine could see it in the process list.
  • With Docker, run it inside the container, with a terminal: docker exec -it mailrules /mailrules users reset-password.

Whether the cookie is marked Secure (sent over HTTPS only) is set by MAILRULES_COOKIE_SECURE:

Value Cookie is HTTPS-only
auto (default) Yes, unless MailRules listens on a loopback address such as 127.0.0.1
true Always. Use this behind a TLS reverse proxy.
false Never. Use this only when you open MailRules over plain HTTP on the same machine, as the Docker setups do.

Never set it to false on a machine others can reach.

Deleting your account (hosted version)

In the hosted version you can delete your MailRules account yourself: Settings → Account → Delete my account. The free self-hosted build has no accounts to delete and shows none of this; to remove a self-hosted MailRules, stop it and delete its data directory.

MailRules asks you to type the email address you sign in with, and the button stays off until it matches. Then:

  • Right away, you are signed out on every device, every mailbox stops being sorted, and its app password or sign-in token is deleted. If you are the only person in your team, your saved model API keys and the addresses of your notification destinations are deleted too. Your email address is free at once.
  • Within 30 days, everything else MailRules kept is deleted: your rules, sender rules, activity, settings and usage. If you are part of a team, your mailboxes and what MailRules recorded of them go, and the team keeps its rules and settings.

It cannot be undone. Signing in again, with the same login or a new one, starts a new, empty account; your old one never comes back.

Your login at the hosted sign-in service is deleted with your account when the hosted service supports it. If the service then fails to delete it, MailRules says so and deletes nothing; try again a few minutes later. Where the service does not support it, your login stays and only your MailRules account is deleted.

Deleting your account does not touch your mail. Emails MailRules moved stay where they are, and nothing is deleted from your mailbox. To stop MailRules reading a mailbox while you keep your account, remove the mailbox instead.

Putting MailRules behind a reverse proxy

To use MailRules from other devices, put a reverse proxy that terminates TLS in front of it, such as Caddy, nginx or Traefik. Do not publish port 8080 to the internet or your network directly: your password and the session cookie would travel unencrypted.

  1. Keep MailRules on a private address. With the proxy on the same machine, leave MAILRULES_LISTEN=127.0.0.1:8080 (the default, and what the Docker setups publish). If you make MailRules listen on another address, it logs a warning at startup: web UI is reachable from other machines; put it behind a reverse proxy with TLS.
  2. Set MAILRULES_COOKIE_SECURE=true. This is needed even with auto, because MailRules itself still listens on 127.0.0.1 and cannot see that the browser uses HTTPS.
  3. Set MAILRULES_PUBLIC_URL to the proxy’s address, such as https://mailrules.example.com, so links in the summary email work.
  4. Set MAILRULES_TRUSTED_PROXIES to the proxy’s address, such as 127.0.0.1 (see Telling visitors apart).
  5. Restart MailRules.

The proxy must pass every path through to one port: the UI and the API are served together. Live updates use server-sent events on /api/events, which stay open; MailRules sends a keep-alive every 25 seconds and asks nginx not to buffer them, so a read timeout above 25 seconds is enough. There are no WebSockets.

MailRules sets Content-Security-Policy, X-Frame-Options, X-Content-Type-Options and Referrer-Policy on its responses; leave them as they are. It does not set Strict-Transport-Security; add it at the proxy if you want it.

Caddy (it gets a certificate by itself and passes events through without buffering):

mailrules.example.com {
	@metrics path /metrics
	respond @metrics 404
	reverse_proxy 127.0.0.1:8080
}

nginx:

server {
    listen 443 ssl;
    server_name mailrules.example.com;
    ssl_certificate     /etc/ssl/mailrules.example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/mailrules.example.com/privkey.pem;

    location = /metrics { return 404; }

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 1h;
    }
}

Telling visitors apart behind a proxy

The limit on failed sign-ins counts per address. Behind a proxy every request reaches MailRules from the proxy’s own address, so by default one person mistyping a password would block sign-in for everyone. To count the real visitor instead, list your proxy in MAILRULES_TRUSTED_PROXIES, as IP addresses or CIDR ranges separated by commas:

MAILRULES_TRUSTED_PROXIES=127.0.0.1
MAILRULES_TRUSTED_PROXIES=172.18.0.0/16,10.0.0.5
  • MailRules then reads X-Forwarded-For only on connections that come from one of those addresses, and takes the right-most address in it that is not itself a listed proxy. That is the address your proxy saw. Anything a visitor wrote into the header sits to its left and is ignored.
  • The header is never read on any other connection, and by default no proxy is trusted. Setting it too wide lets anyone who can reach MailRules directly forge their address and so get past the limit; list only your proxies, and a range such as 0.0.0.0/0 is refused.
  • Your proxy must add the header itself. Caddy and Traefik do by default; the nginx example above does.
  • If the proxy runs in Docker, list the address range of the Docker network it shares with MailRules, such as 172.18.0.0/16.
  • Without the setting, the per-email limit above still applies, so a shared address cannot be used to guess the password.

Endpoints without sign-in

/healthz and /readyz (for health checks) and /metrics (Prometheus metrics: request counts and timings, the version, and Go runtime figures, with no mail or account data) answer without sign-in. Keep /metrics off the public side of your proxy, as in the examples above.

Instead of having /metrics scraped, MailRules can send the same metrics, and its log, to an OpenTelemetry receiver: set OTEL_EXPORTER_OTLP_ENDPOINT (see Settings). Unset, it sends nothing anywhere.

Secrets and logs

  • Mailbox passwords and model keys entered in the browser, and the addresses and signing secrets of notification destinations (hosted version), are encrypted with AES-256-GCM before they are stored, each under a key of its own that is sealed with the data key of its account (its team, in the hosted version). The database holds each data key only wrapped by the master key, so a copy of the database alone opens nothing, and the secrets of one account do not open with another’s key. See Backup and the master key.
  • In the hosted version the data keys are wrapped by a key held in a key service (a cloud KMS whose keys live in hardware security modules) instead of the master key. That key never leaves the service: MailRules asks it to unwrap a team’s data key when it needs one, keeps the unwrapped key only in memory and only for a bounded time (MAILRULES_TENANT_KEY_CACHE, an hour by default), then asks again. Requests that need the same key at once share one call.
  • While the key service cannot be reached, keys already in memory keep working until their time is up. After that, nothing of that team is opened or stored: its mailboxes show Key service unreachable and retry by themselves, waiting longer each time, up to 5 minutes; requests that need a stored password or key answer 503 key_unavailable and change nothing; a new team cannot sign up. Nothing falls back to the master key for a team whose key the key service wrapped, and nothing is stored unwrapped.
  • They are write-only: no API response contains them. Settings only says whether a key is set, and where from, and shows a destination’s address cut short; a webhook’s signing secret is shown once, when it is added.
  • Logs never contain passwords, keys, tokens, notification addresses or the text of an email, at any LOG_LEVEL. A build that sends its errors to an error tracker (the hosted version) sends each exactly as the log line reads, and the log lines sent to an OpenTelemetry receiver (OTEL_EXPORTER_OTLP_ENDPOINT) are those the log writes, so the same holds there. The receiver’s key (OTEL_EXPORTER_OTLP_HEADERS) is never logged.
  • Logs keep the email addresses of mailboxes and senders by default when you host MailRules yourself, because they help you find a mailbox’s lines. To keep them out, set LOG_REDACT_ADDRESSES=true: every address in the log, and in the errors sent to an error tracker, is then written as a tag such as <email:3f9a2c1b> instead. The hosted version (MAILRULES_MODE=cloud) does this by default; LOG_REDACT_ADDRESSES=false turns it off there. One address always gets the same tag, whatever its capitals, so its lines can still be followed. To find them, mailrules log-tag [email protected] prints the tag (run it with the daemon’s MAILRULES_DATA_DIR; with Docker, inside the container). The tags are keyed by log.key, which MailRules writes to the data directory the first time it redacts. It opens nothing else; without it no tag can be turned back into its address, and deleting it only gives every address a new tag.
  • mailrules accounts add and mailrules users reset-password never take a password as a flag, where other users of the machine could see it in the process list.
  • Mail that a model needs to read is sent to the provider of that model. What is sent to a model lists exactly what, and Ollama keeps it on your own server.

Mail server certificates

MailRules only talks to mail servers over TLS (implicit, or STARTTLS), and checks the server’s certificate before it sends the password.

  • By default the certificate must chain to a root your system trusts and be made out to the host name you entered, as in any mail program. Such a server needs nothing accepted.
  • A certificate the system does not trust, such as the one Proton Mail Bridge makes for itself, is shown with its SHA-256 fingerprint, and connects only once you accept it. MailRules stores that fingerprint with the mailbox.
  • With an accepted certificate, the fingerprint is the whole check: the server must present exactly that certificate. The system’s roots, the host name and the dates are not checked, because a certificate a server made for itself may pass none of them (Bridge’s need not even be made out to 127.0.0.1). Someone who could put another server in its place cannot present that certificate without its private key, so the check still keeps them out.
  • If the server presents any other certificate, MailRules refuses it, does not send the password, stops retrying and shows Certificate changed until you check the new one and accept it. A server replaced on purpose, such as Bridge after a reinstall, needs this once; a change you did not expect is a reason to stop and find out why.
  • Accept a certificate only if you know it is your server’s. For Bridge, it is the one presented on 127.0.0.1 while Bridge runs on your own machine.

Mail servers in the hosted version

The hosted version of MailRules (MAILRULES_MODE=cloud) connects only to mail servers on the public internet. A server you name for a mailbox, in the add-mailbox wizard or in Edit, is refused when it is, or its name resolves to, an address that is not: the machine’s own (127.0.0.1, ::1), a private network (10.x, 172.16.x to 172.31.x, 192.168.x, IPv6 fc00::/7), link-local (169.254.x, fe80::/10), carrier-grade NAT (100.64.x to 100.127.x), unspecified, multicast, broadcast and other ranges reserved for special uses, in their IPv6 forms too. The wizard and Edit then say beside the Host field that the hosted version can only connect to mail servers on the public internet. The answer is the same whether anything runs at that address or not, because nothing is dialed.

Every connection the hosted version makes to such a server checks the address it is about to connect to, not only the name, so a name that changes to a private address after it was tested is refused too. A mailbox in that state stops with that sentence instead of connecting. Mailboxes the hosted version connects for you itself, such as a one-click Google Workspace or Outlook mailbox, are on servers it chose and are not checked.

A MailRules you run yourself connects to any server you name, your own network included.

Reporting a vulnerability

Do not open a public issue for a security problem. Report it privately through GitHub: on the repository’s Security tab, choose Report a vulnerability. Never include passwords, API keys or the contents of your email in a report.

Tell your inbox what to do. Then stop thinking about it.