towerops/docs/PANGOLIN_SECURITY.md

# Pangolin Security Rules for Towerops

This document describes the security rules applied at the Pangolin edge proxy layer to protect Towerops from common web attacks.

## Overview

Pangolin acts as a security layer before traffic reaches the application server, filtering out:
- SQL injection attempts
- Cross-site scripting (XSS)
- Path traversal attacks
- Malicious bots and scanners
- Common exploit attempts
- Information disclosure vulnerabilities

## Applying the Rules

### Method 1: Pangolin CLI

```bash
# Upload rules to your Pangolin instance
pangolin rules upload pangolin-security-rules.toml

# Verify rules are active
pangolin rules list

# Test rules without blocking
pangolin rules test --dry-run
```

### Method 2: Pangolin Web UI

1. Log into your Pangolin dashboard
2. Navigate to **Security > Rules**
3. Click **Import Rules**
4. Upload `pangolin-security-rules.toml`
5. Review and activate

### Method 3: GitOps / Infrastructure as Code

Add to your Terraform/Pulumi configuration:

```hcl
resource "pangolin_security_rules" "towerops" {
  source = file("${path.module}/pangolin-security-rules.toml")
  enabled = true
}
```

## Rule Categories

### 1. SQL Injection Protection

Blocks attempts to:
- Use UNION queries to extract data
- Use OR/AND conditions to bypass authentication
- Query information_schema
- Use SQL comments to manipulate queries

**Example blocked requests:**
```
/api/users?id=1' OR '1'='1
/search?q=test' UNION SELECT * FROM users--
```

### 2. XSS Protection

Blocks attempts to inject JavaScript via:
- `<script>` tags
- JavaScript protocol handlers
- Event handlers (onclick, onload, etc.)

**Example blocked requests:**
```
/profile?name=<script>alert(1)</script>
/comment?text=<img src=x onerror=alert(1)>
```

### 3. Path Traversal Protection

Prevents attackers from accessing files outside the web root:
- Directory traversal sequences (../)
- Absolute path references (/etc/, C:\)
- Encoded traversal attempts

**Example blocked requests:**
```
/download?file=../../../../etc/passwd
/api/files?path=/etc/shadow
```

### 4. Common Exploit Paths

Blocks requests to paths that don't exist in Towerops but are commonly targeted:
- WordPress admin panels
- PHPMyAdmin
- cPanel interfaces
- Generic admin paths

**Example blocked requests:**
```
/wp-admin/
/phpmyadmin/
/admin/login.php
```

### 5. Malicious Bot Detection

Blocks known security scanners and malicious crawlers:
- Nikto, Nessus, Nmap
- SQLMap, Metasploit
- Aggressive scrapers
- Empty User-Agent headers

**Allowed bots:**
- Monitoring services (UptimeRobot, Pingdom)
- Towerops agents (legitimate traffic)

### 6. Shell Injection Protection

Prevents command injection attempts:
- Shell metacharacters (|, ;, `)
- Command substitution
- ShellShock vulnerability

**Example blocked requests:**
```
/api/run?cmd=ls | grep password
/execute?command=`cat /etc/passwd`
```

### 7. File Upload Exploits

Blocks malicious file extensions and double-extension tricks:
- PHP, ASP, JSP executable files
- Files disguised with double extensions
- Shell scripts

**Example blocked requests:**
```
/upload?file=shell.php
/api/files/avatar.jpg.php
```

### 8. Information Disclosure

Prevents access to sensitive files:
- `.git` and `.svn` directories
- `.env` environment files
- Backup files (.bak, .old, ~)
- Configuration files

**Example blocked requests:**
```
/.git/config
/.env
/config.php.bak
```

### 9. Protocol Attacks

Blocks obsolete or dangerous HTTP methods:
- HTTP/0.9 (obsolete since 1996)
- TRACE method (XST attacks)
- TRACK method

### 10. Known Exploits

Protects against recent vulnerabilities:
- Log4Shell (CVE-2021-44228)
- SSRF attempts
- XXE (XML External Entity)

## Monitoring and Tuning

### View Blocked Requests

```bash
# Real-time log streaming
pangolin logs stream --filter action=block

# Export blocked requests to CSV
pangolin logs export --action block --days 7 > blocked.csv
```

### False Positives

If legitimate traffic is being blocked:

1. **Identify the rule:**
```bash
pangolin logs show <request_id>
```

2. **Create an exception:**
```toml
[[rules]]
name = "Allow Specific Pattern"
match.url.path = "/your-endpoint"
action = "allow"
priority = 1000  # Higher priority = evaluated first
```

3. **Or disable the specific rule:**
```bash
pangolin rules disable "Block SQL Injection - UNION"
```

### Performance Impact

These rules are evaluated at the edge with minimal latency:
- Regex matching: ~0.1-0.5ms per request
- Header inspection: ~0.05ms per request
- Total overhead: < 1ms per request

## Testing

### Test Individual Rules

```bash
# Test SQL injection protection
curl "https://towerops.net/api/users?id=1' OR '1'='1"
# Should return: 403 Forbidden

# Test path traversal protection
curl "https://towerops.net/files?path=../../etc/passwd"
# Should return: 403 Forbidden

# Test legitimate request
curl "https://towerops.net/health"
# Should return: 200 OK
```

### Load Testing with Rules

```bash
# Ensure rules don't impact performance
ab -n 10000 -c 100 https://towerops.net/health
```

## Security Best Practices

1. **Keep Rules Updated**: Review and update rules quarterly
2. **Monitor Logs**: Set up alerts for high block rates
3. **Test Changes**: Use dry-run mode before activating new rules
4. **Layer Defense**: Don't rely solely on Pangolin - application-level validation is still required
5. **Regular Audits**: Review blocked requests monthly for patterns

## Rate Limiting (Optional)

If you have Pangolin Pro, uncomment the rate limiting rules in the config:

```toml
[[rules]]
name = "Rate Limit - General"
match.all = true
action = "rate_limit"
rate_limit.requests = 100
rate_limit.window = "1m"
rate_limit.by = "ip"
```

Recommended limits:
- **General traffic**: 100 req/min per IP
- **Login endpoints**: 10 req/min per IP
- **API endpoints**: 1000 req/min per token

## Geo-Blocking (Optional)

Block traffic from specific countries if needed:

```toml
[[rules]]
name = "Block High-Risk Countries"
match.geo.country_code = ["CN", "RU", "KP"]
action = "block"
log = false
```

**Warning**: Only use geo-blocking if you're certain you have no legitimate users in those regions.

## Troubleshooting

### Rules Not Working

1. **Verify rules are loaded:**
```bash
pangolin rules list | grep "Block SQL"
```

2. **Check rule syntax:**
```bash
pangolin rules validate pangolin-security-rules.toml
```

3. **Ensure Pangolin is in path:**
```bash
# Check traffic is flowing through Pangolin
pangolin status
```

### High Block Rate

If you're seeing unexpectedly high block rates:

1. **Analyze top blocked patterns:**
```bash
pangolin analytics blocked --top 10
```

2. **Check for scanning activity:**
```bash
pangolin logs stream --filter action=block | grep -E "(nikto|nmap)"
```

3. **Temporarily disable aggressive rules:**
```bash
pangolin rules disable "Block Scrapers and Crawlers"
```

## Compliance

These rules help meet security requirements for:
- **OWASP Top 10**: Addresses injection, XSS, SSRF, XXE
- **PCI DSS**: Provides web application firewall (WAF) capabilities
- **SOC 2**: Demonstrates security controls and logging
- **ISO 27001**: Shows defense-in-depth implementation

## Support

- **Pangolin Documentation**: https://docs.pangolin.net/
- **Rule Examples**: https://github.com/pangolin/rules-examples
- **Community Forum**: https://community.pangolin.net/

## Changelog

- **2026-01-15**: Initial rule set created
  - 30+ security rules covering OWASP Top 10
  - Bot and scanner detection
  - Protocol attack prevention
  - Information disclosure protection