From 4fb39e55bd276832aed4df51c54350d3be9f6f22 Mon Sep 17 00:00:00 2001 From: vince6e74 <49673819+vince6e74@users.noreply.github.com> Date: Sat, 16 May 2026 17:09:43 +0200 Subject: [PATCH] docs: add BIMI module documentation Add documentation for the BIMI plugin covering prerequisites, how the sync/async helper flow works, all configuration options, examples, Redis setup, DNS record format, and troubleshooting. Also registers the page in sidebars.js. --- docs/modules/bimi.md | 162 +++++++++++++++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 163 insertions(+) create mode 100644 docs/modules/bimi.md diff --git a/docs/modules/bimi.md b/docs/modules/bimi.md new file mode 100644 index 000000000..5784263d2 --- /dev/null +++ b/docs/modules/bimi.md @@ -0,0 +1,162 @@ +--- +title: BIMI module +--- + +# BIMI module + +The BIMI module implements [Brand Indicators for Message Identification (BIMI)](https://bimigroup.org/), a standard that allows domain owners to attach their brand logo to authenticated emails. When a message passes strict DMARC authentication, Rspamd looks up the sender's BIMI DNS record, validates the associated Verified Mark Certificate (VMC), and inserts a `BIMI-Indicator` header containing the base64-encoded SVG logo for display by supporting mail clients. + +## Prerequisites + +BIMI requires: + +1. **DMARC with a strict policy** — the sender's domain must have a DMARC record with `p=reject` or `p=quarantine`. Messages passing only with a `none` policy are not eligible. +2. **Redis** — used to cache BIMI validation results to avoid repeated DNS lookups and VMC verifications. +3. **BIMI helper service** — a sidecar HTTP service (e.g., [rspamd-bimi-helper](https://github.com/rspamd/bimi-helper)) that fetches and validates the SVG logo and VMC. The helper is not bundled with Rspamd and must be deployed separately. + +## How it works + +1. Rspamd checks whether the `DMARC_POLICY_ALLOW` symbol is present with a `reject` or `quarantine` policy. +2. It resolves the `default._bimi.` TXT DNS record and parses the BIMI record fields `l` (logo URL) and `a` (authority evidence / VMC URL). +3. When `vmc_only = true` (the default), records without the `a=` field are ignored. +4. Rspamd queries Redis for a cached validation result. On a cache hit, the result is used directly. +5. On a cache miss, Rspamd contacts the BIMI helper, which fetches and verifies the VMC and SVG logo. +6. In **synchronous mode** (`helper_sync = true`), the helper returns the validated logo directly; Rspamd inserts the `BIMI-Indicator` header and stores the result in Redis. +7. In **asynchronous mode** (`helper_sync = false`), the helper writes the result to Redis itself, so the logo is available for the *next* message from that domain. +8. On success, Rspamd adds the virtual symbol `BIMI_VALID` and the `BIMI-Indicator` header. + +## Symbols + +| Symbol | Score | Description | +|--------|-------|-------------| +| `BIMI_CHECK` | — | Normal symbol that drives the BIMI check (internal) | +| `BIMI_VALID` | 0.0 | BIMI record was found and the logo was successfully validated | + +## Enabling the module + +The module is **disabled by default**. Enable it by creating `local.d/bimi.conf`: + +~~~hcl +# local.d/bimi.conf +helper_url = "http://127.0.0.1:3030"; +enabled = true; +~~~ + +Redis must also be configured. See the [Redis configuration guide](/configuration/redis) for details. + +## Configuration + +Settings should be placed in `/etc/rspamd/local.d/bimi.conf`. + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `helper_url` | string | `http://127.0.0.1:3030` | Base URL of the BIMI helper service | +| `helper_timeout` | number/time | `5s` | Total timeout for helper requests | +| `helper_connect_timeout` | number/time | — | Optional separate connection timeout | +| `helper_ssl_timeout` | number/time | — | Optional separate SSL handshake timeout | +| `helper_write_timeout` | number/time | — | Optional separate write timeout | +| `helper_read_timeout` | number/time | — | Optional separate read timeout | +| `helper_sync` | boolean | `true` | Use synchronous mode (helper returns result directly) | +| `vmc_only` | boolean | `true` | Only accept records with a VMC (`a=` field) | +| `redis_prefix` | string | `rs_bimi` | Redis key prefix for cached results | +| `redis_min_expiry` | number/time | `24h` | Minimum TTL for cached Redis entries | +| `enabled` | boolean | `false` | Enable/disable the module | + +## Configuration examples + +### Minimal setup (sync mode) + +~~~hcl +# local.d/bimi.conf +helper_url = "http://127.0.0.1:3030"; +enabled = true; +~~~ + +### Asynchronous helper mode + +In async mode the helper writes validated logos directly to Redis. This allows Rspamd to skip waiting for the helper on each individual message — the logo is available on the next scan after initial validation. + +~~~hcl +# local.d/bimi.conf +helper_url = "http://127.0.0.1:3030"; +helper_sync = false; +enabled = true; +~~~ + +### Custom timeouts + +~~~hcl +# local.d/bimi.conf +helper_url = "http://127.0.0.1:3030"; +helper_timeout = 10s; +helper_connect_timeout = 2s; +helper_read_timeout = 8s; +redis_min_expiry = 48h; +enabled = true; +~~~ + +### Accept logos without VMC + +By default only BIMI records with a Verified Mark Certificate (`a=` field) are processed. To also accept self-asserted logos (the `l=` field only), set: + +~~~hcl +# local.d/bimi.conf +helper_url = "http://127.0.0.1:3030"; +vmc_only = false; +enabled = true; +~~~ + +:::note +Self-asserted `l=`-only BIMI is not yet fully implemented in Rspamd. Setting `vmc_only = false` will prevent the module from filtering such records, but no logo indicator will be inserted for them until support is added. +::: + +## Redis configuration + +Redis is used both for caching BIMI results (lookup key: ``) and, in async mode, as the channel through which the helper delivers validated logos to Rspamd. + +Configure Redis in the `bimi` section using the standard Rspamd Redis parameters: + +~~~hcl +# local.d/bimi.conf +helper_url = "http://127.0.0.1:3030"; +enabled = true; + +servers = "127.0.0.1:6379"; +# db = "1"; +# password = "secret"; +~~~ + +See the [Redis configuration guide](/configuration/redis) for all available options. + +## BIMI DNS record format + +A BIMI TXT record is published at `default._bimi.` and has the following format: + +~~~ +v=BIMI1; l=; a= +~~~ + +- `l=` — HTTPS URL pointing to a Tiny PS (SVG) logo file +- `a=` — HTTPS URL pointing to a PEM-encoded Verified Mark Certificate (VMC) + +Example: + +~~~ +default._bimi.example.com. IN TXT "v=BIMI1; l=https://example.com/logo.svg; a=https://example.com/vmc.pem" +~~~ + +## Troubleshooting + +Enable debug logging for the module to trace the decision process: + +~~~hcl +# local.d/logging.inc +debug_modules = ["bimi"]; +~~~ + +Common issues: + +- **No DMARC allow symbol** — the sender's domain does not pass DMARC or the policy is `none`. BIMI requires `reject` or `quarantine`. +- **BIMI for domain has no VMC** — with `vmc_only = true`, a record without `a=` is skipped. +- **Helper not reachable** — check that the BIMI helper service is running at the configured `helper_url`. +- **Logo not shown after enabling** — in async mode the logo is stored in Redis on the first helper call and displayed from the *second* message onward. diff --git a/sidebars.js b/sidebars.js index 6f8f64a8a..e15aeb767 100644 --- a/sidebars.js +++ b/sidebars.js @@ -103,6 +103,7 @@ const sidebars = { "modules/arc", "modules/asn", "modules/bayes_expiry", + "modules/bimi", "modules/chartable", "modules/clickhouse", "modules/dcc",