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:

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