# 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