# checker-smtp

Deep SMTP checker for the MX-based inbound mail service of a
[happyDomain](https://www.happydomain.org/) domain.

For every MX target of the zone, it performs the live probes a human
operator would run with `swaks` or `telnet … 25`: TCP connect, ESMTP
banner & EHLO, STARTTLS negotiation, mail-transaction (null sender,
postmaster, open-relay) probes, reverse DNS / FCrDNS, extension
inventory, and IPv4/IPv6 coverage. The result is an actionable HTML
report whose "What to fix" panel foregrounds the most common real-world
failures rather than burying them in endpoint tabs.

## Scope

This checker probes the **inbound** side of the domain's mail service:
it connects to each MX target and exercises the SMTP server's
protocol-level posture (banner, EHLO, STARTTLS handshake, mail
transactions stopped at RCPT, reverse DNS, IPv4/IPv6 coverage…).

It does **not** test outbound deliverability: SPF/DKIM/DMARC alignment,
ARC, BIMI, spam scoring (SpamAssassin/rspamd), blacklist status, header
hygiene or message content are not evaluated here. Those require
actually emitting a message from the domain and analysing what arrives;
that is the job of `checker-happydeliver`, which drives a
[happyDeliver](https://git.nemunai.re/happyDomain/happyDeliver) instance.

In short: **`checker-smtp` answers "can this domain *receive* mail
correctly?"**, while **`checker-happydeliver` answers "does mail this
domain *sends* land in the inbox?"**.

TLS certificate chain / SAN / expiry / cipher posture is also **out of scope**:
a dedicated TLS checker handles that. This checker only confirms STARTTLS
completes and records the negotiated TLS version/cipher for context.

We publish each MX target as a `DiscoveryEntry` of type
`tls.endpoint.v1` (contract: `git.happydns.org/checker-tls/contract`)
with `STARTTLS="smtp"` and `RequireSTARTTLS=false` (opportunistic for
port 25; make it required by publishing MTA-STS or DANE in dedicated
checkers). `checker-tls` picks up those entries and runs certificate
posture on the same connection our probe just validated; the resulting
`tls_probes` observations are folded back into our rule aggregation and
HTML report via `ObservationGetter.GetRelated` / `ReportContext.Related`,
so a bad certificate on an MX shows up on the SMTP service page, not
only in a separate TLS view.

## Rules

| Code                       | Description                                                                                       | Severity   |
|----------------------------|---------------------------------------------------------------------------------------------------|------------|
| `smtp.null_mx`             | Reports whether the domain publishes a null MX (RFC 7505), declaring it does not accept mail.     | INFO       |
| `smtp.mx_present`          | Verifies the domain publishes at least one MX record (or a null MX).                              | CRITICAL   |
| `smtp.mx_sanity`           | Flags MX targets that violate RFC 5321 § 5.1 (IP literals, CNAME chains, unresolved names).       | CRITICAL   |
| `smtp.endpoint_reachable`  | Verifies every MX endpoint accepts a TCP connection on port 25.                                   | CRITICAL   |
| `smtp.banner_sanity`       | Verifies every reachable endpoint emits a 220 SMTP greeting.                                      | CRITICAL   |
| `smtp.ehlo_supported`      | Verifies every endpoint accepts EHLO (required for STARTTLS, PIPELINING, SIZE, …).                | CRITICAL   |
| `smtp.starttls_offered`    | Verifies every endpoint advertises the STARTTLS extension.                                        | CRITICAL   |
| `smtp.starttls_handshake`  | Verifies the STARTTLS handshake succeeds wherever STARTTLS is advertised.                         | CRITICAL   |
| `smtp.auth_posture`        | Flags endpoints that advertise SMTP AUTH before STARTTLS (cleartext credentials).                 | CRITICAL   |
| `smtp.reverse_dns`         | Verifies every endpoint has a matching PTR record (FCrDNS).                                       | WARNING    |
| `smtp.null_sender`         | Verifies endpoints accept the null sender MAIL FROM:<> (required for DSNs).                       | CRITICAL   |
| `smtp.postmaster`          | Verifies endpoints accept RCPT TO:<postmaster@domain> (RFC 5321 § 4.5.1).                         | CRITICAL   |
| `smtp.open_relay`          | Flags endpoints that relay mail for recipients outside the tested domain.                         | CRITICAL   |
| `smtp.extension_posture`   | Reports ESMTP extension posture (PIPELINING, 8BITMIME).                                           | INFO       |
| `smtp.ipv6_reachable`      | Verifies at least one MX endpoint is reachable over IPv6.                                         | INFO       |
| `smtp.tls_quality`         | Folds downstream TLS checker findings (certificate chain, hostname match, expiry) onto SMTP.      | CRITICAL   |

## Most common failures and how the report addresses them

| Symptom                                   | Issue code                  | Report message |
|-------------------------------------------|-----------------------------|----------------|
| MX target is a CNAME                      | `smtp.mx.cname`             | CRIT, fix suggests replacing CNAME with A/AAAA |
| No STARTTLS on any endpoint               | `smtp.all_no_starttls`      | CRIT, fix mentions Postfix/Exim settings and MTA-STS/DANE next steps |
| `AUTH` advertised over plaintext port 25  | `smtp.auth.plaintext`       | CRIT, fix suggests `smtpd_tls_auth_only=yes` / moving auth to 587 |
| `postmaster@` rejected                    | `smtp.postmaster.rejected`  | CRIT, cites RFC 5321 § 4.5.1 |
| Bounces (`MAIL FROM:<>`) rejected         | `smtp.null_sender.rejected` | CRIT |
| Missing PTR or FCrDNS mismatch            | `smtp.ptr.missing`, `smtp.fcrdns.mismatch` | WARN, names Gmail/Outlook/Yahoo impact |
| Open relay                                | `smtp.open_relay`           | CRIT (the endpoint panel also shows a red "OPEN RELAY" badge in the summary) |

## Usage

### Standalone HTTP server

```bash
make
./checker-smtp -listen :8080
```

The standalone binary also exposes a browser-friendly `GET /check` page
(via the SDK's `CheckerInteractive` interface): enter a domain, submit,
and the same `Collect` → `Evaluate` → HTML-report pipeline runs without
needing a happyDomain instance in front. MX records are looked up live;
no zone payload is required.

### Docker

```bash
make docker
docker run -p 8080:8080 happydomain/checker-smtp
```

### happyDomain plugin

```bash
make plugin
```

## Options

| Scope | Id                    | Default                        | Description |
|-------|-----------------------|--------------------------------|-------------|
| Run   | `domain`              | (none)                         | Domain to test (auto-filled from the service). |
| Run   | `timeout`             | `12`                           | Per-endpoint timeout, in seconds. |
| Run   | `helo_name`           | `mx-checker.happydomain.org`   | Hostname announced in EHLO/HELO. Pick a name with valid A/AAAA and PTR. |
| Run   | `test_null_sender`    | `true`                         | Probe `MAIL FROM:<>` (RFC 5321 DSN acceptance). |
| Run   | `test_postmaster`     | `true`                         | Probe `RCPT TO:<postmaster@domain>` (RFC 5321 § 4.5.1). |
| Run   | `test_open_relay`     | `true`                         | Probe `RCPT TO:<recipient-outside-domain>` to detect open relays. |
| Run   | `test_probe_address`  | `postmaster@example.com`       | Recipient used for the open-relay probe. Automatically overridden when equal to the tested domain. |

Applies to services of type `svcs.MXs` (the DNS-level MX record set).

## Safety / hosted deployment

The checker connects out to arbitrary SMTP servers on port 25 with the
host's IP, and concatenates user-supplied values (`domain`, `helo_name`,
`test_probe_address`) into SMTP commands. Two consequences worth
considering before exposing the standalone server (or its `GET /check`
form) to untrusted users:

- **CRLF / SMTP-command injection** is mitigated: `domain` and
  `helo_name` are validated as hostnames, and `test_probe_address` is
  validated as an addr-spec. Inputs containing CR, LF, `<`, `>` or other
  SMTP metacharacters are rejected before any command is written to the
  wire.
- **Probe-from-our-IP abuse vector** remains: anyone who can reach the
  service can have it open SMTP connections to any host:25, optionally
  with an attacker-chosen RCPT (the open-relay probe). This is
  functionally similar to an SSRF: outbound traffic appears to come
  from the checker's address and may trigger blocklisting or abuse
  reports against the operator. When deploying publicly, gate access
  behind authentication, add per-IP rate limiting, and consider
  restricting target domains (e.g. only domains owned by the requester)
  before exposing the form. The happyDomain plugin path is unaffected:
  targets there are always the MXs of the zone the user already
  controls.

## Design notes

- **Why not `net/smtp`?** The standard library's client hides the banner
  text, muxes multiline responses into a single string, and does not
  expose the pre- vs post-TLS extension set separately. A bespoke
  ~200-line SMTP client (see `checker/smtp.go`) gives us verbatim
  responses for every step, which is what operators want to see in a
  diagnostic report.
- **Why stop at RCPT?** The open-relay, null-sender and postmaster
  probes all end at RCPT and emit RSET before the next transaction. We
  never send `DATA`, so no mail is actually delivered and no bounces are
  generated. A receiving server that accepts a spoofed RCPT but would
  have rejected the message at DATA is still reported as open relay (a
  sensible choice for a posture check).
- **Certificate posture via `checker-tls`.** MX SMTP on port 25 is
  opportunistic, so we do not verify the certificate ourselves. Each
  probed MX target is published as a `tls.endpoint.v1` discovery entry
  with `STARTTLS="smtp"`. `checker-tls`'s resulting observations are
  folded back into the rule aggregation and the HTML report via the
  SDK's `GetRelated` / `ReportContext.Related` path (same pattern as
  `checker-xmpp`).
- **No DANE / MTA-STS checks here.** These are policy surfaces, not
  connection-time behaviours, and deserve their own checkers
  (`checker-dane` on TLSA records, `checker-mta-sts` on the TXT/HTTPS
  policy artefact). This checker answers the question "does the MX
  actually work?"; policy enforcement layers on top.

## License

MIT (see `LICENSE`). Third-party attributions in `NOTICE`.