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

# 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:

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

# 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:

pangolin logs show <request_id>

2. Create an exception:

[[rules]]
name = "Allow Specific Pattern"
match.url.path = "/your-endpoint"
action = "allow"
priority = 1000  # Higher priority = evaluated first

3. Or disable the specific rule:

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

# 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

# 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:

[[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:

[[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:

pangolin rules list | grep "Block SQL"

2. Check rule syntax:

pangolin rules validate pangolin-security-rules.toml

3. Ensure Pangolin is in path:

# Check traffic is flowing through Pangolin
pangolin status

High Block Rate

If you're seeing unexpectedly high block rates:

1. Analyze top blocked patterns:

pangolin analytics blocked --top 10

2. Check for scanning activity:

pangolin logs stream --filter action=block | grep -E "(nikto|nmap)"

3. Temporarily disable aggressive rules:

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