Ryan Malloy
c73fa9d3d1
Major features: - Extension enumeration detection with 3 detection algorithms: - Max unique extensions threshold (default: 20 in 5 min) - Sequential pattern detection (e.g., 100,101,102...) - Rapid-fire detection (many extensions in short window) - Prometheus metrics for all SIP Guardian operations - SQLite persistent storage for bans and attack history - Webhook notifications for ban/unban/suspicious events - GeoIP-based country blocking with continent shortcuts - Per-method rate limiting with token bucket algorithm Bug fixes: - Fix whitelist count always reporting zero in stats - Fix whitelisted connections metric never incrementing - Fix Caddyfile config not being applied to shared guardian New files: - enumeration.go: Extension enumeration detector - enumeration_test.go: 14 comprehensive unit tests - metrics.go: Prometheus metrics handler - storage.go: SQLite persistence layer - webhooks.go: Webhook notification system - geoip.go: MaxMind GeoIP integration - ratelimit.go: Per-method rate limiting Testing: - sandbox/ contains complete Docker Compose test environment - All 14 enumeration tests pass
Caddy SIP Guardian
A custom Caddy module that provides SIP-aware rate limiting, IP banning, and attack detection at Layer 4.
Features
- Layer 4 SIP Proxying: Handle SIP traffic (UDP/TCP/TLS) before it reaches your PBX
- Intelligent Rate Limiting: Track failed attempts per IP with configurable windows
- Automatic Banning: Ban IPs that exceed failure thresholds
- Attack Detection: Detect common SIP scanning tools (sipvicious, friendly-scanner, etc.)
- CIDR Whitelisting: Whitelist trusted networks
- Admin API: RESTful API for managing bans and viewing stats
Architecture
Internet
│
▼
┌─────────────────────────────────────┐
│ Caddy SIP Guardian (Layer 4) │
│ ┌─────────────────────────────────┐│
│ │ SIP Matcher ││
│ │ - Detects SIP methods ││
│ │ - Matches REGISTER, INVITE, etc ││
│ └─────────────────────────────────┘│
│ ┌─────────────────────────────────┐│
│ │ SIP Handler ││
│ │ - Check banned IPs ││
│ │ - Check whitelists ││
│ │ - Detect attack patterns ││
│ │ - Record failures ││
│ └─────────────────────────────────┘│
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ FreePBX / Asterisk │
│ (Protected from scanners) │
└─────────────────────────────────────┘
Quick Start
# Build the custom Caddy image
make build
# Start the stack
make run
# View logs
make logs
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
SIP_UPSTREAM_HOST |
freepbx |
Upstream SIP server hostname |
SIP_UPSTREAM_PORT |
5060 |
Upstream SIP port |
SIP_UPSTREAM_TLS_PORT |
5061 |
Upstream SIP TLS port |
SIP_GUARDIAN_MAX_FAILURES |
5 |
Failures before ban |
SIP_GUARDIAN_FIND_TIME |
10m |
Time window for counting failures |
SIP_GUARDIAN_BAN_TIME |
1h |
Ban duration |
Caddyfile Directives
sip_guardian {
max_failures 5 # Ban after 5 failures
find_time 10m # Within 10 minute window
ban_time 1h # Ban for 1 hour
whitelist 10.0.0.0/8 192.168.0.0/16
}
Admin API
List Banned IPs
curl http://localhost:2020/api/sip-guardian/bans
View Stats
curl http://localhost:2020/api/sip-guardian/stats
Manually Ban IP
curl -X POST http://localhost:2020/api/sip-guardian/ban/192.168.1.100 \
-H "Content-Type: application/json" \
-d '{"reason": "manual_ban"}'
Unban IP
curl -X DELETE http://localhost:2020/api/sip-guardian/unban/192.168.1.100
Detected Attack Patterns
The module automatically detects and flags:
- sipvicious - Popular SIP scanning tool
- friendly-scanner - Another common scanner
- sipcli - SIP command line tool
- sip-scan - Generic SIP scanners
- Common test extensions (100, 1000)
Building from Source
# Using xcaddy
xcaddy build \
--with github.com/mholt/caddy-l4 \
--with github.com/mholt/caddy-ratelimit \
--with github.com/ryanmalloy/caddy-sip-guardian
Integration with FreePBX
This module is designed to sit in front of FreePBX/Asterisk:
- All SIP traffic hits Caddy first
- Malicious traffic is blocked at the edge
- Only legitimate traffic reaches your PBX
- FreePBX doesn't need its own fail2ban for SIP
License
MIT