diff --git a/docs/PANGOLIN_SECURITY.md b/docs/PANGOLIN_SECURITY.md new file mode 100644 index 00000000..d22d8e3f --- /dev/null +++ b/docs/PANGOLIN_SECURITY.md @@ -0,0 +1,340 @@ +# 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: +- ` +/comment?text= +``` + +### 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 +``` + +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 diff --git a/pangolin-security-rules.toml b/pangolin-security-rules.toml new file mode 100644 index 00000000..bcc1cecd --- /dev/null +++ b/pangolin-security-rules.toml @@ -0,0 +1,285 @@ +# Pangolin Security Rules for Towerops +# Block common web attacks and malicious traffic +# +# Apply these rules to your Pangolin configuration to filter traffic before +# it reaches your application server. +# +# Documentation: https://docs.pangolin.net/ + +# ============================================================================ +# SQL Injection Attempts +# ============================================================================ + +[[rules]] +name = "Block SQL Injection - UNION" +match.url.regex = "(?i)(union.*(all|select)|select.*from.*information_schema)" +action = "block" +log = true + +[[rules]] +name = "Block SQL Injection - Common Patterns" +match.url.regex = "(?i)(\\bor\\b.*=.*|\\band\\b.*=.*|'.*or.*'|\".*or.*\"|;.*drop|;.*delete|;.*insert|;.*update)" +action = "block" +log = true + +[[rules]] +name = "Block SQL Injection - Comments" +match.url.regex = "(?i)(/\\*.*\\*/|--.*$|#.*$)" +action = "block" +log = true + +# ============================================================================ +# Cross-Site Scripting (XSS) +# ============================================================================ + +[[rules]] +name = "Block XSS - Script Tags" +match.url.regex = "(?i)(