cv-site/DEPLOYMENT_SECURITY.md

Quick Security Deployment Guide

Rate Limiter IP Spoofing Protection

TL;DR

Development: Already configured, spoofing protection active ✅ Production: Update 2 environment variables before deploying

---

Development (Default)

Configuration (.env):

BEHIND_PROXY=false
TRUSTED_PROXY_IP=

What it does:

• Ignores all X-Forwarded-For headers
• Uses actual connection IP (RemoteAddr)
• Logs all spoofing attempts
• Secure by default ✅

No action needed - Already configured!

---

Production Deployment

Step 1: Identify Your Reverse Proxy IP

# If using nginx/caddy on same server
TRUSTED_PROXY_IP=127.0.0.1

# If using load balancer
TRUSTED_PROXY_IP=10.0.0.5  # Your load balancer's internal IP

# If using Cloudflare (not recommended, use Cloudflare IP ranges)
# See: https://www.cloudflare.com/ips/

Step 2: Update .env

# Change these two lines:
BEHIND_PROXY=true
TRUSTED_PROXY_IP=127.0.0.1  # Replace with your proxy IP

Step 3: Verify Configuration

# Start server
./cv-site

# Check logs for confirmation
# Should see: "Rate limiter: Behind proxy mode (trusted proxy: 127.0.0.1)"

Step 4: Test Rate Limiting

# From your proxy/load balancer, make 4 requests
for i in {1..4}; do
  curl http://your-site.com/export/pdf?lang=en
done

# Expected: First 3 succeed, 4th returns 429

---

Security Verification

✅ Development Mode Test

# Should be rate limited after 3 requests (same real IP)
curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:1999/export/pdf
curl -H "X-Forwarded-For: 5.6.7.8" http://localhost:1999/export/pdf
curl -H "X-Forwarded-For: 9.9.9.9" http://localhost:1999/export/pdf
curl -H "X-Forwarded-For: 10.10.10.10" http://localhost:1999/export/pdf  # 429

✅ Production Mode Test

# Should trust X-Forwarded-For from trusted proxy
# Test from proxy/load balancer:
curl -H "X-Forwarded-For: 1.2.3.4" http://backend:1999/export/pdf  # OK
curl -H "X-Forwarded-For: 1.2.3.4" http://backend:1999/export/pdf  # OK
curl -H "X-Forwarded-For: 1.2.3.4" http://backend:1999/export/pdf  # OK
curl -H "X-Forwarded-For: 1.2.3.4" http://backend:1999/export/pdf  # 429

---

Monitoring

Security Logs to Watch

# Spoofing attempts in development
grep "SECURITY WARNING: X-Forwarded-For" /var/log/app.log

# Untrusted proxy in production
grep "SECURITY: Request from untrusted proxy" /var/log/app.log

# Invalid IPs
grep "SECURITY: Invalid IP in X-Forwarded-For" /var/log/app.log

Rate Limiting Metrics

# 429 responses (rate limited)
grep "429" /var/log/app.log | wc -l

# By endpoint
grep "export/pdf" /var/log/app.log | grep "429"

---

Troubleshooting

Issue: Rate limiting not working in production

Symptoms: All requests succeed, no rate limiting Diagnosis:

# Check configuration
env | grep BEHIND_PROXY
# Should show: BEHIND_PROXY=true

# Check logs
tail -f /var/log/app.log | grep "Rate limiter"
# Should see: "Behind proxy mode"

Fix:

1. Verify .env has BEHIND_PROXY=true
2. Verify TRUSTED_PROXY_IP matches your reverse proxy IP
3. Restart application

Issue: All requests rate limited immediately

Symptoms: First request returns 429 Diagnosis:

# Check if proxy IP is wrong
tail -f /var/log/app.log | grep "untrusted proxy"

Fix:

1. Get correct proxy IP: ss -tnp | grep :1999
2. Update TRUSTED_PROXY_IP in .env
3. Restart application

Issue: Security warnings in production logs

Symptoms: "SECURITY WARNING" logs appearing Diagnosis: Someone is sending requests with spoofed headers directly to your backend

Fix:

1. Ensure firewall blocks direct access to backend port
2. Only allow traffic from reverse proxy
3. Example (iptables):

iptables -A INPUT -p tcp --dport 1999 -s 127.0.0.1 -j ACCEPT
iptables -A INPUT -p tcp --dport 1999 -j DROP

---

Nginx Configuration Example

If using nginx as reverse proxy:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:1999;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Then set in .env:

BEHIND_PROXY=true
TRUSTED_PROXY_IP=127.0.0.1

---

Caddy Configuration Example

If using Caddy:

your-domain.com {
    reverse_proxy 127.0.0.1:1999
}

Then set in .env:

BEHIND_PROXY=true
TRUSTED_PROXY_IP=127.0.0.1

---

Security Checklist

Before Production Deployment

• Update BEHIND_PROXY=true in .env
• Set correct TRUSTED_PROXY_IP
• Test rate limiting from proxy
• Verify security logs are being written
• Ensure firewall blocks direct backend access
• Configure reverse proxy to set X-Forwarded-For
• Test spoofing attack (should fail)
• Set up monitoring/alerting for security logs
• Document proxy IP for team

After Deployment

• Monitor rate limiting effectiveness
• Check for "SECURITY WARNING" logs
• Verify 429 responses are being returned
• Test with penetration testing tools
• Review security logs weekly

---

Support

Issue: Security vulnerability or bypass detected Action:

1. Document the attack vector
2. Check logs: grep SECURITY /var/log/app.log
3. Review this guide for misconfigurations
4. Contact security team if issue persists

References:

• Implementation: internal/middleware/security.go
• Tests: internal/middleware/security_test.go
• Full report: SECURITY_VALIDATION.md