Ryan Malloy 1ba05e160c Initial commit: Caddy SIP Guardian module

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

2025-12-06 16:38:07 -07:00

4.1 KiB

Raw Blame History

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

4.1 KiB Raw Blame History