# 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**:
```bash
./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**:
```bash
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**:
```bash
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**:
```bash
./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

```bash
# 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

```bash
# 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

```bash
# 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**:
```nginx
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

```mermaid
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

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

### If nginx Won't Reload

```bash
# 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

```bash
# 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