checker-smtp/README.md

# 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.

## What it checks

### DNS posture

1. MX records published? (RFC 7505 null-MX is recognised and reported as INFO)
2. MX target is a hostname, **not** an IP literal (RFC 5321 § 5.1).
3. MX target is **not** a CNAME (RFC 5321 § 5.1).
4. MX target resolves (A and/or AAAA).
5. Implicit-MX fallback warned about.

### Per-endpoint (port 25, for each A/AAAA of each MX)

6. TCP reachability.
7. SMTP 220 banner, captured verbatim; announced hostname parsed.
8. ESMTP EHLO (fallback to HELO detected and flagged).
9. Extension inventory: STARTTLS, PIPELINING, 8BITMIME, SMTPUTF8,
   CHUNKING, DSN, ENHANCEDSTATUSCODES, SIZE, AUTH.
10. `AUTH` advertised *before* STARTTLS (credentials-over-plaintext risk).
11. STARTTLS negotiation and TLS version/cipher recorded (no cert checks; handed off to `checker-tls`).
12. Post-TLS EHLO: extensions may expand after the upgrade; we union them.
13. Reverse DNS (PTR) present for each IP.
14. Forward-confirmed reverse DNS (FCrDNS): PTR's forward resolution must include our IP (Gmail / Outlook / Yahoo reject without this).
15. Null sender acceptance (`MAIL FROM:<>`; RFC 5321 mandates this for bounces).
16. Postmaster mailbox acceptance (`RCPT TO:<postmaster@domain>`; RFC 5321 § 4.5.1).
17. **Open-relay probe** (`MAIL FROM:<checker@…>` then `RCPT TO:<postmaster@example.com>`; a 2xx indicates an open relay). The probe stops at RCPT; `DATA` is never sent.
18. IPv4 / IPv6 coverage.

The rule emits one `CheckState` per derived issue, with `Subject` set
to the offending endpoint (`ip:25`) or MX target so the host can
correlate findings across runs. When nothing is wrong the rule emits a
single OK state; an RFC 7505 null MX collapses to a single INFO state.
The HTML report renders a domain-level "What to fix" panel (sorted
crit → warn → info) plus one collapsible section per probed endpoint,
open by default when something is wrong.

## 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`.