Initial commit

2026-04-21 22:42:34 +07:00 · 2026-04-21 22:42:34 +07:00 · 9cae9b693c
commit 9cae9b693c
19 changed files with 2311 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,100 @@
+# checker-sip
+
+SIP / VoIP server checker for [happyDomain](https://www.happydomain.org/).
+
+Probes a domain's SIP deployment end-to-end from its DNS records:
+
+- **RFC 3263 resolution.** NAPTR → SRV (`_sip._udp`, `_sip._tcp`,
+  `_sips._tcp`) → A/AAAA.
+- **Reachability** on every resolved `target:port` over UDP, TCP and TLS.
+- **SIP `OPTIONS` ping.** Raw RFC 3261 request; parses status line,
+  `Server` / `User-Agent`, `Allow` methods, round-trip time.
+- **Discovery entries.** Every `_sips._tcp` target is published as a
+  `tls.endpoint.v1` `DiscoveryEntry` (via
+  [`checker-tls/contract`](../checker-tls/README.md)) so the TLS checker
+  can verify chain, SAN, expiry and cipher posture without re-doing the
+  SRV lookup. TLS issues reported by the TLS checker are folded back
+  into this report via `GetRelated("tls_probes")`.
+
+Attaches to the `abstract.SIP` service (SRV records for `_sip._udp`,
+`_sip._tcp`, `_sips._tcp`). The happyDomain core registers the abstract
+service automatically; no extra configuration is required.
+
+## Why a raw SIP OPTIONS request rather than `emiago/sipgo`?
+
+`emiago/sipgo` is a full SIP user-agent stack. Its lifecycle expects a
+stable bidirectional transport with a local listener, which is overkill
+for a one-shot outbound OPTIONS probe — and problematic in a containerised
+checker that may be behind NAT. This checker sends a minimal RFC 3261
+OPTIONS message (~50 lines of text handling in `checker/sip_probe.go`)
+over `net.Conn` / `*tls.Conn`. The same wire format works for UDP, TCP
+and TLS. Swap in `sipgo` later if richer interactions (REGISTER, media,
+dialogs) are ever needed.
+
+## Usage
+
+### Standalone HTTP server
+
+```bash
+make
+./checker-sip -listen :8080
+```
+
+Exposes the standard happyDomain external checker endpoints (`/health`,
+`/definition`, `/collect`, `/evaluate`, `/report`).
+
+### Docker
+
+```bash
+make docker
+docker run -p 8080:8080 happydomain/checker-sip
+```
+
+### happyDomain plugin
+
+```bash
+make plugin
+# produces checker-sip.so, loadable as a Go plugin by happyDomain.
+```
+
+## Options
+
+| Scope | Id          | Description                                                            |
+| ----- | ----------- | ---------------------------------------------------------------------- |
+| Run   | `domain`    | SIP domain to test (auto-filled from the service domain).              |
+| Run   | `timeout`   | Per-endpoint probe timeout in seconds (default: `5`).                  |
+| Admin | `probeUDP`  | Probe `_sip._udp` (default: `true`). Disable if UDP is firewalled.    |
+| Admin | `probeTCP`  | Probe `_sip._tcp` (default: `true`).                                   |
+| Admin | `probeTLS`  | Probe `_sips._tcp` (default: `true`).                                  |
+
+## Tests performed
+
+1. NAPTR lookup (`SIP+D2U`, `SIP+D2T`, `SIPS+D2T`).
+2. SRV lookup for the three transports.
+3. Fallback to `<domain>:5060` / `<domain>:5061` when no SRV is
+   published, with a visible info marker in the report.
+4. A/AAAA resolution of every SRV target.
+5. TCP connect / UDP send / TLS handshake (with
+   `InsecureSkipVerify: true` — cert posture is the TLS checker's job).
+6. SIP `OPTIONS` request with status, headers and `Allow` parsed.
+
+## Common failure scenarios addressed directly in the report
+
+- Missing SRV records (zone not publishing any `_sip.*` SRV).
+- Only `_sip._udp` published — modern trunks (Twilio, OVH, Orange)
+  require TCP/TLS.
+- SRV target that doesn't resolve.
+- Port closed / firewalled on the SRV target.
+- Server drops `OPTIONS` silently (common with default Asterisk /
+  Kamailio configs).
+- `OPTIONS` answered with a non-2xx status (ACL, routing, overload).
+- TLS issues surfaced through the TLS checker (expired cert, SAN
+  mismatch, chain invalid) rendered per-endpoint.
+
+The HTML report's header banner ranks these top-down with concrete fix
+hints so the user can go straight to the change they need to make.
+
+## License
+
+Licensed under the **MIT License** (see `LICENSE`). Third-party
+attributions for `checker-sdk-go` (Apache-2.0) are recorded in `NOTICE`.