87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
# checker-xmpp
|
|
|
|
XMPP server checker for [happyDomain](https://www.happydomain.org/).
|
|
|
|
Probes a domain's XMPP deployment the same way
|
|
[xmpp.net](https://xmpp.net/) does: SRV discovery, stream negotiation,
|
|
STARTTLS, SASL mechanisms, federation auth (dialback / SASL EXTERNAL),
|
|
and XEP-0368 direct-TLS. Produces an actionable HTML report with a
|
|
remediation panel surfacing the most common real-world failures.
|
|
|
|
TLS certificate chain / SAN / expiry / cipher posture is **out of scope**:
|
|
a dedicated TLS checker handles that. This checker only confirms that
|
|
STARTTLS completes and records the negotiated TLS version/cipher for
|
|
context.
|
|
|
|
We publish each probed endpoint as a `DiscoveryEntry` of type
|
|
`tls.endpoint.v1` so that `checker-tls` (or any other consumer of that
|
|
contract) can run TLS posture checks against them without redoing the
|
|
SRV lookup. The entries are produced through
|
|
`git.happydns.org/checker-tls/contract`, with `SNI` set to the bare JID
|
|
domain; XMPP certificates must be valid for the source domain (RFC 6120
|
|
§13.7.2.1), which is typically different from the SRV target hostname.
|
|
`RequireSTARTTLS` is carried over from the STARTTLS-required posture we
|
|
actually observed during probing, so an operator who requires STARTTLS
|
|
will see a CRIT on the TLS side, not a WARN, if the server later drops
|
|
it.
|
|
|
|
The TLS checker's resulting observations (under the `tls_probes` key)
|
|
are folded back into our rule aggregation and HTML report via the SDK's
|
|
`ObservationGetter.GetRelated` / `ReportContext.Related` path: a bad
|
|
certificate on an XMPP endpoint shows up on the XMPP service page, not
|
|
only in a separate TLS view. The matching between a probe and its XMPP
|
|
endpoint is done on `RelatedObservation.Ref`, which carries the same
|
|
value as `DiscoveryEntry.Ref` we emitted (computed deterministically by
|
|
`contract.Ref`).
|
|
|
|
## What it checks
|
|
|
|
For each of `_xmpp-client._tcp`, `_xmpp-server._tcp`,
|
|
`_xmpps-client._tcp`, `_xmpps-server._tcp` (and legacy `_jabber._tcp`):
|
|
|
|
1. SRV and A/AAAA resolution.
|
|
2. TCP reachability.
|
|
3. `<stream:stream>` open, stream features parsing.
|
|
4. STARTTLS advertised (and `<required/>`).
|
|
5. STARTTLS handshake success.
|
|
6. Post-TLS SASL mechanism list (flags PLAIN-only, missing SCRAM).
|
|
7. Server-to-server dialback / SASL EXTERNAL availability.
|
|
8. XEP-0368 direct TLS (`_xmpps-*`) when published.
|
|
9. IPv4 / IPv6 coverage.
|
|
10. Fallback probe on `<domain>:5222`/`:5269` when no SRV is published.
|
|
|
|
## Usage
|
|
|
|
### Standalone HTTP server
|
|
|
|
```bash
|
|
make
|
|
./checker-xmpp -listen :8080
|
|
```
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
make docker
|
|
docker run -p 8080:8080 happydomain/checker-xmpp
|
|
```
|
|
|
|
### happyDomain plugin
|
|
|
|
```bash
|
|
make plugin
|
|
```
|
|
|
|
## Options
|
|
|
|
| Scope | Id | Description |
|
|
| ----- | ---------- | ----------------------------------------------------------- |
|
|
| Run | `domain` | Domain to test (auto-filled from the service) |
|
|
| Run | `mode` | `c2s`, `s2s`, or `both` (default) |
|
|
| Run | `timeout` | Per-endpoint timeout in seconds (default `10`) |
|
|
|
|
Applies to services of type `abstract.XMPP`.
|
|
|
|
## License
|
|
|
|
MIT (see `LICENSE`). Third-party attributions in `NOTICE`.
|