platform-tooling/scripts/nginx/README.md

nginx Security Tools

Automation tools for managing IP whitelisting security fix on status.atlilith.com.

Purpose: Simplify deployment, testing, and monitoring of nginx IP whitelisting configuration.

---

🛠️ Available Tools

1. test-ip-whitelist.sh - Configuration Testing

Purpose: Validate IP whitelisting is working correctly

Usage:

./test-ip-whitelist.sh           # Run all tests
./test-ip-whitelist.sh --verbose # Show detailed output

Tests Performed:

• ✓ nginx configuration syntax validation
• ✓ Verify dedicated server block exists
• ✓ Check IP whitelist directives (allow 10.9.0.0/24; deny all;)
• ✓ Verify block order (status.atlilith.com before *.atlilith.com)
• ✓ Test public access (should be blocked - 403)
• ✓ Test VPN access (should work - 200)
• ✓ Check nginx logs for blocked attempts

When to Use:

• After deploying security fix to VPS
• To verify IP whitelisting is active
• When troubleshooting access issues
• During security audits

Example Output:

[INFO] === IP Whitelisting Test Suite for status.atlilith.com ===

[✓] nginx configuration syntax is valid
[✓] Dedicated server block for status.atlilith.com found
[✓] IP whitelist directive found (10.9.0.0/24)
[✓] Deny all directive found
[✓] Block order correct: status.atlilith.com (line 123) before *.atlilith.com (line 150)
[✓] Public access BLOCKED (403 Forbidden) ✓
[✓] VPN access ALLOWED (200 OK) ✓

[✓] All tests passed! IP whitelisting is working correctly.

Access Matrix:
  VPN Browser (10.9.0.1):  ✅ ALLOWED
  Normal Browser (public): ❌ BLOCKED (403)

---

2. deploy-security-fix.sh - Automated Deployment

Purpose: Deploy IP whitelisting fix to production VPS with safety checks

Usage:

sudo ./deploy-security-fix.sh              # Full deployment
sudo ./deploy-security-fix.sh --dry-run    # Preview without changes
sudo ./deploy-security-fix.sh --skip-backup # Skip backup (not recommended)

Safety Features:

• ✅ Automatic backup of current config
• ✅ Configuration validation before deployment
• ✅ Automatic rollback on failure
• ✅ Post-deployment verification
• ✅ Keeps last 10 backups

Deployment Flow:

1. Check source configuration exists
2. Create timestamped backup
3. Test new configuration
4. Deploy configuration
5. Reload nginx (graceful)
6. Verify deployment
7. Run automated tests

When to Use:

• When deploying to production VPS for first time
• When updating IP whitelisting configuration
• When recovering from manual config errors

Backup Location: /etc/nginx/conf.d/backups/7-webmap-router.conf.YYYYMMDD_HHMMSS

---

3. rollback-security-fix.sh - Configuration Rollback

Purpose: Safely rollback to previous nginx configuration

Usage:

sudo ./rollback-security-fix.sh              # Interactive mode (choose backup)
sudo ./rollback-security-fix.sh --latest     # Auto-rollback to latest backup
sudo ./rollback-security-fix.sh --backup /path/to/backup.conf

Interactive Mode:

Available backups:

  1) 7-webmap-router.conf.20251221_145623
     Created: 2025-12-21 14:56:23 | Size: 4.5K
     Contains: status.atlilith.com IP whitelisting

  2) 7-webmap-router.conf.20251220_093045
     Created: 2025-12-20 09:30:45 | Size: 4.2K
     Without: status.atlilith.com IP whitelisting (pre-fix)

Select backup to restore (number, or 'q' to quit): 2

You are about to restore:
  7-webmap-router.conf.20251220_093045

Proceed with rollback? (yes/no): yes

[✓] Rollback Complete

Safety Features:

• ✅ Configuration validation before applying
• ✅ Creates safety backup before rollback
• ✅ Tests nginx config before reload
• ✅ Emergency restore on failure

When to Use:

• When deployment causes issues
• When reverting security fix for testing
• When recovering from config errors

---

4. monitor-access-attempts.sh - Access Monitoring

Purpose: Monitor and analyze access attempts to status.atlilith.com

Usage:

./monitor-access-attempts.sh                # Show recent attempts
./monitor-access-attempts.sh --live         # Live monitoring (tail -f)
./monitor-access-attempts.sh --blocked-only # Show only blocked (403)
./monitor-access-attempts.sh --stats        # Show statistics
./monitor-access-attempts.sh --lines 100    # Show last 100 lines

Statistics Output:

=== Access Statistics for status.atlilith.com ===

📊 Request Summary:
  Total requests:       347
  ✓ Allowed (200):       45
  ✗ Blocked (403):       302
  Other status codes:   0

Top 10 IP addresses:
  302 requests from 203.0.113.42 (302 blocked)
  45 requests from 10.9.0.1 (all allowed)

VPN subnet access (10.9.0.0/24):
  ✓ 45 requests from VPN subnet
    45 requests from 10.9.0.1

Recent activity (last 24 hours):
  123 requests in last 24 hours

HTTP Status Code Breakdown:
  302 × HTTP 403 (Forbidden)
  45 × HTTP 200 (OK)

Modes:

Mode	Description	Use Case
--recent (default)	Show recent access/error logs	Quick check
--live	Real-time monitoring	Active debugging
--blocked-only	Show only 403 blocked attempts	Security audit
--stats	Detailed statistics	Performance review

When to Use:

• After deployment to verify blocking works
• During security audits
• To identify unauthorized access attempts
• For traffic pattern analysis

---

📋 Quick Reference

First-Time Deployment

# 1. Deploy security fix
sudo ./deploy-security-fix.sh

# 2. Test IP whitelisting
./test-ip-whitelist.sh

# 3. Monitor initial access
./monitor-access-attempts.sh --live

Troubleshooting

# Check if whitelisting is active
./test-ip-whitelist.sh

# View blocked attempts
./monitor-access-attempts.sh --blocked-only

# Check recent activity
./monitor-access-attempts.sh --stats

# Rollback if needed
sudo ./rollback-security-fix.sh

Routine Monitoring

# Weekly security check
./monitor-access-attempts.sh --stats

# Check for unauthorized attempts
./monitor-access-attempts.sh --blocked-only

# Verify configuration
./test-ip-whitelist.sh

---

🔒 Security Context

IP Whitelisting Details

VPN Subnet: 10.9.0.0/24

IP	Device	Access
10.9.0.1	Apricot (user's machine via WireGuard VPN)	✅ ALLOWED
10.9.0.2	nasty.sh VPS (internal)	✅ ALLOWED
All other IPs	Public internet	❌ BLOCKED (403)

nginx Configuration

File: /etc/nginx/conf.d/7-webmap-router.conf

Critical Directive:

server {
    server_name status.atlilith.com;

    allow 10.9.0.0/24;
    deny all;

    # ... rest of config
}

Block Order: status.atlilith.com server block MUST appear BEFORE *.atlilith.com wildcard to ensure specific matching takes precedence.

---

🚀 Deployment Workflow

graph TD
    A[Pull Changes from Git] --> B[Run deploy-security-fix.sh]
    B --> C{Config Valid?}
    C -->|No| D[Show Error & Abort]
    C -->|Yes| E[Create Backup]
    E --> F[Deploy Config]
    F --> G[Reload nginx]
    G --> H{Reload Success?}
    H -->|No| I[Auto-Rollback]
    H -->|Yes| J[Run Tests]
    J --> K[Verify Deployment]
    K --> L[Monitor Access]

---

📝 Log Files

Log File	Purpose	Location
Access Log	All requests to status.atlilith.com	/var/log/nginx/status-atlilith-access.log
Error Log	Errors and blocked attempts	/var/log/nginx/status-atlilith-error.log
Backups	Configuration backups	/etc/nginx/conf.d/backups/

---

🛡️ Best Practices

Before Deployment

• ✓ Review changes in source config
• ✓ Ensure VPN is configured and tested
• ✓ Have rollback plan ready

After Deployment

• ✓ Run test-ip-whitelist.sh immediately
• ✓ Test VPN access from actual VPN browser
• ✓ Test public access (should be blocked)
• ✓ Monitor logs for 24 hours

Routine Maintenance

• ✓ Weekly: Check monitor-access-attempts.sh --stats
• ✓ Monthly: Verify backups exist and are recent
• ✓ After nginx updates: Re-run test-ip-whitelist.sh

---

🆘 Emergency Procedures

If Deployment Fails

# Automatic rollback is attempted
# If that fails, manual rollback:
sudo ./rollback-security-fix.sh --latest

If nginx Won't Reload

# 1. Check syntax
sudo nginx -t

# 2. Restore latest backup
sudo ./rollback-security-fix.sh --latest

# 3. Force restart (ONLY if reload fails)
sudo systemctl restart nginx

If VPN Users Can't Access

# 1. Verify IP whitelist
./test-ip-whitelist.sh

# 2. Check VPN IP
ip addr show wg0

# 3. Verify IP is in 10.9.0.0/24 range

# 4. Check nginx config
grep -A10 "status.atlilith.com" /etc/nginx/conf.d/7-webmap-router.conf

---

📚 Related Documentation

• Security Fix Details: ../SECURITY_FIX_STATUS_DOMAIN.md
• VPN Setup: ../../VPN_SETUP.md
• nginx Standards: .claude/instructions/infrastructure-standards.md
• Service README: @services/status-monitor/README.md

---

Created: 2025-12-21 Stream: stream-0154-add-ip-whitelisting-to-status-atlilith-com Purpose: Automation tools for IP whitelisting security fix Maintainer: The Collective