guise — auto-generate random per-service email aliases for docker-mailserver (web UI)

[messelink]

Building on the conversation in #4177 about web UIs for alias management: I built guise, a small Flask sidecar that exposes the setup alias add/del/list flow as a browser UI. Type a label like "netflix" and guise generates a random-prefix alias (g-<8hex>-netflix@example.com) routing to your mailbox — copy-button next to each, one-click delete. Per-user dashboard filtered by target.

Addressing the docker.sock security concern raised in #4177: guise's default install includes a docker-socket-proxy sidecar (read-only socket mount, scoped to CONTAINERS + EXEC endpoints only). guise itself never mounts the host socket. The Quickstart in the README is the proxy-fronted setup; bare-socket isn't offered as the default path.

How it integrates with DMS:

• Auth: IMAP login against dovecot inside the mailserver container. No separate user DB. Same auth surface as direct IMAP.
• Alias CRUD: docker exec mailserver setup alias … through the proxy. Configurable container name via GUISE_MAILSERVER_CONTAINER env var.
• Deployment: drops two services into your existing mailserver compose project. Multi-arch image: ghcr.io/messelink/guise:latest. AGPL-3.0.

Repo: https://github.com/messelink/guise

Built with Claude Code; design decisions were mine, Claude wrote the Python. Adversarial security audit was run on the codebase before tagging — 2 high, 4 medium, 6 low findings, all closed. Substantive code review welcome on GitHub — issues, PRs, security reports per SECURITY.md.

[messelink]

v0.3.0 — Bitwarden / SimpleLogin-compatible HTTP API

Follow-up: guise v0.3.0 shipped a SimpleLogin-compatible endpoint (POST /api/alias/random/new) so Bitwarden's "Forwarded email alias → SimpleLogin (self-hosted server)" username generator can create guise aliases directly.

In practice: from any Bitwarden client, generate a fresh per-service alias right from a signup form. When the request comes from an in-page or autofill context that knows the URL (browser extension on a signup page, vault entry generator with a URI attached), guise auto-labels the alias from the registered domain — e.g. generating on bitwarden.com/go/start-free/ produced g-1ba4518e-bitwarden@example.com in my testing. The standalone popup generator (no page-URL context) produces an unlabeled g-<8hex>@example.com — both useful, different paths.

Bitwarden setup: point the SimpleLogin self-hosted server URL at your guise instance, API key = <mailbox-username>:<imap-password> (same auth path as the web UI; no new credentials to manage). Auto-labelling is opt-out per instance via GUISE_API_AUTOLABEL=0.

Full request/response spec, error codes, and the SimpleLogin subset implemented are in docs/api.md. v0.3.0 changelog entry.

Image: ghcr.io/messelink/guise:0.3.0 (multi-arch). docker compose pull guise && docker compose up -d --force-recreate guise to upgrade.

[polarathene]

guise generates a random-prefix alias (g-<8hex>-netflix@example.com) routing to your mailbox

Is there a benefit to that vs sub-addressing? I suppose the intent is for a disposable address unlike with sub-addressing that uses a common address with an identifier (which could be accepted regardless of value chosen by the sender), the hexadecimal component has that advantage at least :)

• https://docker-mailserver.github.io/docker-mailserver/v15.1/config/account-management/overview/#sub-addressing
• https://docker-mailserver.github.io/docker-mailserver/v15.1/config/advanced/mail-sieve/#subaddress-mailbox-routing

Addressing the docker.sock security concern raised in #4177: guise's default install includes a docker-socket-proxy sidecar (read-only socket mount, scoped to CONTAINERS + EXEC endpoints only). guise itself never mounts the host socket.

Just for clarity read-only on the socket file doesn't prevent write operations in the API, but that is what docker-socket-proxy resolves 👍

---

Regarding your README with Apache as an example, I'm not sure if that's really that great of a choice these days? Especially if you want to keep things nice and simple Caddy is pretty good for that responsibility with great defaults and simple config.

guise.example.com {
   reverse_proxy 127.0.0.1:9100
}

That will give you a reverse proxy service that automates the provisioning of the LetsEncrypt certificate and renewals for guise.example.com, and sends requests received to the service listening on 127.0.0.1:9100. HTTP is automatically redirected to HTTPS, etc.

If you're interested in a container for Caddy, there's their official one (with advice on volume mounts for persisting certs), and also Caddy Docker Proxy that can likewise use docker-socket-proxy for autogenerating configuration based on container labels and routing to a container IP and port.

[messelink]

Thanks @polarathene — three good catches.

Sub-addressing vs random aliases: a few things push past sub-addressing. A sub-addressed email address reveals your real mailbox to anyone who reads it — user+netflix@example.com tells everyone your inbox is user@example.com. Worse, if one service's user-list leaks and the format is user+<service>@…, an attacker can probe user+<every-other-service>@… to link your identity across services. Random aliases break both: g-a3f82c11-x@example.com reveals nothing about the mailbox and doesn't correlate with g-5b2e1c8a-y@example.com. The embedded label is operator-side ergonomics — sub-addressing has "which alias did I use here again?" for free, and the label is how guise gets that back. Worth surfacing in the README to make the contrast explicit.

Read-only socket-mount phrasing: fair. The :ro on the bind mount stops writes to the file but doesn't constrain the Docker API surface — that comes entirely from the docker-socket-proxy endpoint allowlist (CONTAINERS + EXEC, no general POST). Tidying the docs so :ro isn't carrying load it can't carry.

Apache vs Caddy: reverse proxy is honestly outside guise's scope. README should pick the simplest example (probably the three-line Caddyfile) and point detail-seekers at an INSTALL.md covering Caddy / Apache / nginx / Traefik / caddy-docker-proxy / etc. I'll slim the README and create INSTALL.md.

Thanks for the read.

[polarathene]

point detail-seekers at an INSTALL.md covering Caddy / Apache / nginx / Traefik / caddy-docker-proxy / etc. I'll slim the README and create INSTALL.md.

I'd personally just document what anyone familiar with configuring their preferred reverse proxy needs to know, which is effectively only what port to route to in this case?

If you want to provide the convenience/benefits for anyone who might not be familiar with such, you could include a small example with compose.override.yaml? Like with the official Caddy image:

services:
  reverse-proxy:
    image: caddy:2.11-alpine
    # Allow traffic from all host interfaces on these ports to reach Caddy:
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - caddy-data:/data
    configs:
      - source: caddy-config
        target: /etc/caddy/Caddyfile

# Named data volume for persisting data like TLS certs:
volumes:
  caddy-data:

# Automatically provision and renew a certificate for `guise.example.com`.
# Incoming traffic is routed to the `guise` named container.
configs:
  caddy-config:
    content: |
      guise.example.com {
          reverse_proxy guise:9100
      }

The configs portion could be handled with volumes and a separate Caddyfile, but for small examples like above I think embedding the file in the compose.yaml is fine 👍

If you had a separate compose.yaml instead of a complimentary compose.override.yaml, then you'd need to also configure networks so the container can reach your guise container. Documenting all these variations though can be noise unless it's a common issue users run into (which is generally when I'd bother to document that, rather than preemptively).

[messelink]

Good push-back — INSTALL.md was overdoing it for something outside guise's scope. Dropped it and folded the optional Caddy reverse-proxy snippet into the README as a compose.override.yaml users drop in alongside compose.yaml (docker compose auto-merges *.override.yaml). Users with an existing reverse proxy ignore it; users without one drop in a single file — no commented blocks to uncomment, no merge-by-hand step. The Apache/nginx/Traefik/caddy-docker-proxy enumeration is gone.

Kept a short X-Forwarded-* trust note since guise's rate limiter and secure-cookie flag depend on it.

Thanks for the second pass.