Ryan Malloy
1ba05e160c
Layer 4 SIP protection with: - SIP traffic matching (REGISTER, INVITE, etc.) - Rate limiting and automatic IP banning - Attack pattern detection (sipvicious, friendly-scanner) - CIDR whitelisting - Admin API for ban management
136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```caddyfile
|
|
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
|
|
```bash
|
|
curl http://localhost:2020/api/sip-guardian/bans
|
|
```
|
|
|
|
### View Stats
|
|
```bash
|
|
curl http://localhost:2020/api/sip-guardian/stats
|
|
```
|
|
|
|
### Manually Ban IP
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
1. All SIP traffic hits Caddy first
|
|
2. Malicious traffic is blocked at the edge
|
|
3. Only legitimate traffic reaches your PBX
|
|
4. FreePBX doesn't need its own fail2ban for SIP
|
|
|
|
## License
|
|
|
|
MIT
|