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 · 2025-12-06 16:38:07 -07:00 · 1ba05e160c
commit 1ba05e160c
12 changed files with 1888 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,135 @@
+# 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