rsp2k/caddy-sip-guardian
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add DNS-aware whitelisting feature

Browse source 
Support for whitelisting SIP trunks and providers by hostname or SRV
record with automatic IP resolution and periodic refresh.

Features:
- Hostname resolution via A/AAAA records
- SRV record resolution (e.g., _sip._udp.provider.com)
- Configurable refresh interval (default 5m)
- Stale entry handling when DNS fails
- Admin API endpoints for DNS whitelist management
- Caddyfile directives: whitelist_hosts, whitelist_srv, dns_refresh

This allows whitelisting by provider name rather than tracking
constantly-changing IP addresses.
This commit is contained in:
Ryan Malloy 2025-12-08 00:46:43 -07:00
parent 46a47ce2c6
commit 5cf34eb3c0
8 changed files with 2383 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

45
README.md
View file

@ -3,7 +3,7 @@
[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![Caddy](https://img.shields.io/badge/Caddy-2.10+-22b638?style=flat&logo=caddy)](https://caddyserver.com/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/Tests-60%20passing-success)](https://git.supported.systems/rsp2k/caddy-sip-guardian)
[![Tests](https://img.shields.io/badge/Tests-196%20passing-success)](https://git.supported.systems/rsp2k/caddy-sip-guardian)
> **A comprehensive Caddy module providing SIP-aware security at Layer 4.**
> Protects your VoIP infrastructure with intelligent rate limiting, attack detection, message validation, and topology hiding.
@ -31,7 +31,8 @@ Traditional SIP security (like fail2ban) parses logs *after* attacks reach your
- **Intelligent Rate Limiting** — Per-method token bucket rate limiting with burst support
- **Automatic Banning** — Ban IPs that exceed failure thresholds
- **Attack Detection** — Detect common SIP scanning tools (SIPVicious, friendly-scanner, etc.)
- **CIDR Whitelisting** — Whitelist trusted networks
- **CIDR Whitelisting** — Whitelist trusted networks by IP range
- **DNS-aware Whitelisting** — Whitelist SIP trunks by hostname or SRV record with auto-refresh
- **GeoIP Blocking** — Block traffic by country using MaxMind databases
### 🔍 Extension Enumeration Detection
@ -298,6 +299,46 @@ enumeration {
---
### DNS-aware Whitelisting
Whitelist SIP trunks and providers by hostname or SRV record. IPs are automatically resolved and refreshed:
```caddyfile
sip_guardian {
# Static CIDR whitelist (always available)
whitelist 10.0.0.0/8 192.168.0.0/16
# DNS-aware whitelist - resolved to IPs automatically
whitelist_hosts pbx.example.com trunk.sipcarrier.net
whitelist_srv _sip._udp.provider.com _sip._tcp.carrier.net
dns_refresh 5m # How often to refresh DNS lookups (default: 5m)
}
```
**Why DNS-aware whitelisting?**
| Static IP Whitelisting | DNS-aware Whitelisting |
|------------------------|------------------------|
| Breaks when provider changes IPs | Auto-updates when IPs change |
| Must manually track carrier IPs | Just use their SRV record |
| Fails silently on changes | Logs refresh events |
**SRV Record Support:**
SIP trunks commonly use SRV records for load balancing and failover. SIP Guardian resolves the full chain:
```
_sip._udp.carrier.com → sip1.carrier.com, sip2.carrier.com → 203.0.113.10, 203.0.113.11
```
**Admin API Endpoints:**
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/sip-guardian/dns-whitelist` | List all resolved DNS entries |
| `POST` | `/api/sip-guardian/dns-whitelist/refresh` | Force immediate DNS refresh |
---
### SIP Message Validation
Enforces RFC 3261 compliance and blocks malformed/malicious packets: