diff --git a/docs/PANGOLIN_SECURITY.md b/docs/PANGOLIN_SECURITY.md deleted file mode 100644 index d22d8e3f..00000000 --- a/docs/PANGOLIN_SECURITY.md +++ /dev/null @@ -1,340 +0,0 @@ -# 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/docs/security-analysis.md b/docs/security-analysis.md deleted file mode 100644 index 0b3d6bf6..00000000 --- a/docs/security-analysis.md +++ /dev/null @@ -1,216 +0,0 @@ -# Security Analysis and Mitigations - -This document tracks Sobelow security findings and the mitigations applied to address them. - -## Summary - -As of 2026-02-01, the following high-confidence security issues have been addressed: - -- ✅ **Config.CSP**: Content-Security-Policy headers configured -- ✅ **Config.HTTPS**: HTTPS enforcement enabled in production -- ✅ **Traversal.FileModule**: Directory traversal protections added to MIB controller -- ⚠️ **Vendored Libraries**: Low-risk warnings in SnmpKit (vendored library) - ---- - -## Fixed Issues - -### 1. Config.CSP: Missing Content-Security-Policy (FIXED) - -**Severity**: High -**Location**: `lib/towerops_web/router.ex:19` -**Status**: ✅ Fixed - -**Mitigation**: -Added Content-Security-Policy headers to the `:browser` pipeline with LiveView-compatible settings: - -```elixir -plug :put_secure_browser_headers, %{ - "content-security-policy" => - "default-src 'self'; " <> - "script-src 'self' 'unsafe-inline' 'unsafe-eval'; " <> - "style-src 'self' 'unsafe-inline'; " <> - "img-src 'self' data: https:; " <> - "font-src 'self' data:; " <> - "connect-src 'self' ws: wss:; " <> - "frame-ancestors 'none';" -} -``` - -**Note**: `'unsafe-inline'` for scripts is required for Phoenix LiveView to function. This is a documented requirement for LiveView applications. - ---- - -### 2. Config.HTTPS: HTTPS Not Enabled (FIXED) - -**Severity**: High -**Location**: `config/prod.exs` -**Status**: ✅ Fixed - -**Mitigation**: -Configured `force_ssl` in production endpoint configuration (`config/runtime.exs`): - -```elixir -config :towerops, ToweropsWeb.Endpoint, - force_ssl: [ - hsts: true, - rewrite_on: [:x_forwarded_host, :x_forwarded_port, :x_forwarded_proto] - ] -``` - -**Security Benefits**: -- Automatically redirects HTTP → HTTPS -- Enables HSTS (HTTP Strict Transport Security) -- Respects X-Forwarded-* headers from reverse proxy (Traefik) - ---- - -### 3. Traversal.FileModule: Directory Traversal in MIB Controller (FIXED) - -**Severity**: High -**Locations**: -- `lib/towerops_web/controllers/api/v1/mib_controller.ex:119` (File.rm_rf) -- `lib/towerops_web/controllers/api/v1/mib_controller.ex:229` (File.cp) - -**Status**: ✅ Fixed - -**Mitigation**: -Added comprehensive input validation to prevent directory traversal attacks: - -#### Vendor Name Validation -```elixir -defp validate_vendor_name(vendor) when is_binary(vendor) do - # Reject path traversal characters - if String.contains?(vendor, [".", "/", "\\", ":"]) do - {:error, "Invalid vendor name: cannot contain path separators or dots"} - else - # Only allow alphanumeric, hyphen, underscore - if vendor =~ ~r/^[a-zA-Z0-9_-]+$/ do - :ok - else - {:error, "Invalid vendor name: must contain only letters, numbers, hyphens, and underscores"} - end - end -end -``` - -#### Filename Validation -```elixir -defp validate_filename(filename) when is_binary(filename) do - # Reject directory traversal sequences - if String.contains?(filename, ["..", "/", "\\"]) or String.starts_with?(filename, ".") do - {:error, "Invalid filename: cannot contain path separators or parent directory references"} - else - :ok - end -end -``` - -**Additional Protections**: -- All vendor names validated before path construction -- Filenames sanitized with `Path.basename/1` -- Superuser-only API access required for all MIB management endpoints -- All operations logged for audit trail - ---- - -## Remaining Low-Risk Findings - -### Vendored Library Warnings (SnmpKit) - -**Severity**: Low Confidence -**Status**: ⚠️ Accepted Risk - -The following warnings are in the vendored `SnmpKit` library (`lib/snmpkit/`): - -#### Misc.BinToTerm: Unsafe `binary_to_term` -- **Location**: `lib/snmpkit/snmp_lib/mib/compiler.ex:203` -- **Risk Level**: Medium-High -- **Reason**: Used for loading compiled MIB files from trusted sources only -- **Mitigation**: MIB files are only loaded from the application's `priv/mibs/` directory, which is controlled by administrators. No user-provided binary data is deserialized. - -#### DOS.StringToAtom / DOS.ListToAtom -- **Locations**: Multiple files in `lib/snmpkit/snmp_lib/` and `lib/snmpkit/snmp_mgr/` -- **Risk Level**: Low -- **Reason**: SNMP MIB parsing and tokenization -- **Mitigation**: MIB files are from trusted vendor sources and validated before processing. Atom creation is bounded by the finite set of SNMP OID names in standard MIBs. - -#### Traversal.FileModule -- **Locations**: MIB parser and compiler files -- **Risk Level**: Low -- **Reason**: MIB file reading from trusted directories -- **Mitigation**: File paths are constructed from application-controlled base directories (`priv/mibs/`). User input does not directly influence file paths. - -#### SQL.Query: SQL injection -- **Locations**: `lib/towerops/monitoring.ex` (multiple functions) -- **Risk Level**: Very Low (False Positive) -- **Reason**: Uses parameterized queries with string interpolation only for table/column names -- **Mitigation**: Table names are hardcoded constants, not user input. All user values use proper `$1`, `$2` parameter binding. - ---- - -## Ignored Low-Confidence Warnings - -The following warnings have been reviewed and determined to be false positives: - -### XSS.Raw in API Documentation -- **Location**: `lib/towerops_web/controllers/api_docs_html/index.html.heex` -- **Reason**: Uses `raw(~S"""...""")` to display static code examples in API documentation -- **Risk**: None - all content is static, developer-authored code examples -- **No Action Required** - ---- - -## Security Best Practices - -### File Upload Security -1. ✅ Validate all filenames and vendor names -2. ✅ Use `Path.basename/1` to strip directory components -3. ✅ Restrict operations to predefined base directories -4. ✅ Require superuser authentication for file management -5. ✅ Log all file operations for audit trail - -### HTTPS Configuration -1. ✅ Force SSL with HSTS enabled -2. ✅ Respect X-Forwarded-* headers from reverse proxy -3. ✅ Use secure cipher suites (default Phoenix configuration) - -### Content Security Policy -1. ✅ Default to 'self' for all resources -2. ✅ Allow WebSocket connections for LiveView -3. ✅ Prevent framing with `frame-ancestors 'none'` -4. ⚠️ Allow `'unsafe-inline'` scripts (required for LiveView) - ---- - -## Testing Recommendations - -### Manual Security Testing -- [ ] Test MIB upload with path traversal attempts (`../../../etc/passwd`) -- [ ] Verify HTTPS redirect in production environment -- [ ] Test CSP headers don't break LiveView functionality -- [ ] Verify file upload restrictions (filename validation) - -### Automated Testing -- Run `mix sobelow` regularly in CI/CD pipeline -- Monitor for new security vulnerabilities in dependencies -- Use Dialyzer for type safety checks - ---- - -## Future Improvements - -1. **Stricter CSP**: Explore using nonces for scripts instead of `'unsafe-inline'` (requires LiveView 1.0+) -2. **File Upload Limits**: Add file size limits for MIB uploads -3. **Rate Limiting**: Implement rate limiting on API endpoints -4. **Security Headers**: Add additional security headers (Permissions-Policy, etc.) -5. **Dependency Scanning**: Set up automated dependency vulnerability scanning - ---- - -## References - -- [Sobelow Security Guide](https://github.com/paraxialio/sobelow_guide) -- [Phoenix Security Best Practices](https://hexdocs.pm/phoenix/security.html) -- [OWASP Top 10](https://owasp.org/www-project-top-ten/) -- [Content Security Policy Reference](https://content-security-policy.com/)