99 lines
4.4 KiB
Markdown
99 lines
4.4 KiB
Markdown
# checker-email-autoconfig
|
|
|
|
Email autoconfiguration checker for [happyDomain](https://www.happydomain.org/).
|
|
|
|
Verifies that a domain publishes discoverable email-client configuration
|
|
through the mechanisms used by real-world mail clients:
|
|
|
|
- **Thunderbird autoconfig** (Bucksch draft, `draft-bucksch-autoconfig-00`)
|
|
- `https://autoconfig.<domain>/mail/config-v1.1.xml` (primary)
|
|
- `https://<domain>/.well-known/autoconfig/mail/config-v1.1.xml` (apex fallback)
|
|
- `http://autoconfig.<domain>/...` (optional; surfaced as a warning)
|
|
- Mozilla ISPDB fallback (`autoconfig.thunderbird.net`)
|
|
- MX-parent fallbacks for hosted domains
|
|
- **Microsoft Autodiscover** POX (`https://autodiscover.<domain>/autodiscover/autodiscover.xml`)
|
|
- **RFC 6186 SRV records** (`_imaps`, `_imap`, `_pop3s`, `_pop3`,
|
|
`_submissions`, `_submission`, `_autodiscover`)
|
|
- MX resolution (for context and MX-based discovery)
|
|
|
|
The checker parses every response, cross-checks the servers advertised
|
|
by the different sources, and produces a rich HTML report with
|
|
**paste-ready remediation snippets** for the most common failure modes.
|
|
|
|
## Rules
|
|
|
|
| Code | Description | Severity |
|
|
|-----------------------------------|--------------------------------------------------------------------------------------------------------------|---------------------|
|
|
| `autoconfig_presence` | Checks that at least one email-autoconfiguration discovery method answers for the domain. | CRITICAL |
|
|
| `autoconfig_preferred_endpoint` | Checks that `https://autoconfig.<domain>/mail/config-v1.1.xml` is reachable and serves a valid clientConfig. | WARNING |
|
|
| `autoconfig_tls` | Checks that autoconfig endpoints are served over HTTPS with a valid TLS certificate. | CRITICAL |
|
|
| `autoconfig_server_encryption` | Checks that servers advertised by autoconfig use SSL or STARTTLS and a non-cleartext auth method. | CRITICAL |
|
|
| `autoconfig_consistency` | Cross-checks hostnames and ports reported by autoconfig, Autodiscover and SRV records. | WARNING |
|
|
| `autoconfig_srv_records` | Checks that RFC 6186 SRV records (`_imaps._tcp`, `_submissions._tcp`, ...) complement the autoconfig XML. | WARNING |
|
|
| `autoconfig_autodiscover` | Reports whether Microsoft Autodiscover (POX) responds on the domain. | WARNING |
|
|
|
|
## Common failure modes the HTML report addresses
|
|
|
|
When a check fails, the report's "Fix this first" section provides
|
|
ready-to-copy snippets:
|
|
|
|
- **Nothing is published** → sample `config-v1.1.xml` for the domain and
|
|
the two canonical URLs to serve it from.
|
|
- **Only `.well-known` answers** → nudge to add the `autoconfig.`
|
|
subdomain (primary URL per the draft).
|
|
- **Plain HTTP fallback responds** → redirect to HTTPS.
|
|
- **TLS validation failed** → hint at covering `autoconfig.<domain>`
|
|
with a valid certificate.
|
|
- **Advertised servers are plaintext** → port cheat-sheet (SSL 993/465,
|
|
STARTTLS 143/587).
|
|
- **No RFC 6186 SRV records** → ready-to-paste zone excerpt.
|
|
|
|
## Usage
|
|
|
|
### Standalone
|
|
|
|
```bash
|
|
make
|
|
./checker-email-autoconfig -listen :8080
|
|
```
|
|
|
|
Exposes:
|
|
|
|
- `GET /health`, `GET /definition`
|
|
- `POST /collect`: run the full discovery probe.
|
|
- `POST /evaluate`: apply rules to a previously collected observation.
|
|
- `POST /report`: returns HTML when `Accept: text/html` is set,
|
|
otherwise JSON metrics.
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
make docker
|
|
docker run -p 8080:8080 happydomain/checker-email-autoconfig
|
|
```
|
|
|
|
### happyDomain plugin
|
|
|
|
```bash
|
|
make plugin
|
|
# produces checker-email-autoconfig.so, loadable by happyDomain.
|
|
```
|
|
|
|
## Options
|
|
|
|
### Per-user
|
|
- `probeEmail`: local-part used in the autoconfig URL query string
|
|
(default `test`).
|
|
- `httpTimeout`: per-request timeout in seconds (default 8).
|
|
- `tryISPDB`: query Mozilla's Thunderbird ISPDB as a fallback (default `true`).
|
|
- `tryHTTPAutoconfig`: also probe the plain-HTTP variant (default `false`).
|
|
- `tryAutodiscoverPost`: probe the Microsoft Autodiscover POX
|
|
endpoints (default `true`).
|
|
|
|
### Admin
|
|
- `ispdbURL`: override the ISPDB base URL.
|
|
- `userAgent`: User-Agent announced in every probe.
|
|
|
|
## License
|
|
|
|
MIT. See `LICENSE` and `NOTICE`.
|