ping_service/manager/SECURITY.md

# Security Checklist for Internet-Exposed Deployment

This manager application is hardened for direct internet exposure without a reverse proxy. This document summarizes the security measures implemented and provides a deployment checklist.

## Built-in Security Features

### ✅ Application-Level Security

| Feature | Implementation | Status |
|---------|---------------|--------|
| **Two-Factor Authentication** | TOTP (RFC 6238) with QR code enrollment | ✅ Active |
| **Encrypted Storage** | AES-256-GCM double encryption (Server Key + User Key) | ✅ Active |
| **Secure Sessions** | Encrypted session IDs, HttpOnly, Secure, SameSite=Strict cookies | ✅ Active |
| **Session Expiration** | 1 hour for authenticated sessions, 5 minutes for temp sessions | ✅ Active |
| **Rate Limiting** | 10/min auth endpoints, 100/min API endpoints (per IP) | ✅ Active |
| **Input Validation** | Length checks, null byte protection, sanitization | ✅ Active |
| **Security Headers** | HSTS, CSP, X-Frame-Options, X-Content-Type-Options, etc. | ✅ Active |
| **TLS 1.2+ Only** | Strong cipher suites (ECDHE + AES-GCM/ChaCha20) | ✅ Active |
| **DoS Protection** | Timeouts, size limits, slowloris protection | ✅ Active |
| **Security Logging** | AUTH_FAILURE and RATE_LIMIT_EXCEEDED with source IP | ✅ Active |
| **Gateway API Keys** | 256-bit keys, encrypted storage, Bearer token auth (optional) | ⚙️ Optional |

### 🔒 Encryption Details

**User Data Encryption (Double Layer):**
1. **Server Key**: 32-byte AES key encrypts entire user database file
2. **User Key**: Derived from User ID + Server Key via PBKDF2, encrypts individual TOTP secrets

**Session Security:**
- Session IDs generated with nanosecond timestamp
- Encrypted with Server Key before storing in cookie
- Cookie flags: `HttpOnly`, `Secure`, `SameSite=Strict`

**TLS Configuration:**
- Minimum: TLS 1.2
- Cipher suites: ECDHE_ECDSA/RSA with AES_GCM and ChaCha20_Poly1305
- Perfect Forward Secrecy (PFS) guaranteed

**API Key Security (Gateway Mode):**
- 256-bit cryptographically secure random keys
- Encrypted storage with Server Key (AES-256-GCM)
- Bearer token authentication (OAuth 2.0 standard)
- Usage tracking (request count, last used timestamp)
- Instant revocation capability

### 🛡️ Attack Protection

| Attack Type | Protection Mechanism |
|------------|---------------------|
| **Brute Force** | Rate limiting (10/min) + fail2ban integration |
| **Slowloris** | ReadHeaderTimeout (5s), ReadTimeout (15s) |
| **Large Payloads** | Request body limit (10MB), MaxHeaderBytes (1MB) |
| **XSS** | Content-Security-Policy header, input validation |
| **CSRF** | SameSite=Strict cookies |
| **Clickjacking** | X-Frame-Options: DENY |
| **MIME Sniffing** | X-Content-Type-Options: nosniff |
| **SQL Injection** | N/A (no SQL database, uses encrypted file storage) |
| **Command Injection** | Input validation, no shell execution of user input |
| **Null Byte Injection** | Explicit null byte checking in validation |

## Production Deployment Checklist

### Before First Run

- [ ] **Generate SERVER_KEY**: On first run, save the generated key to environment
  ```bash
  export SERVER_KEY="base64-encoded-32-byte-key"
  ```

- [ ] **Create Admin User**: Add initial user with TOTP
  ```bash
  ./manager --add-user=admin
  # Scan QR code with authenticator app
  ```

- [ ] **Configure Environment Variables**:
  ```bash
  export SERVER_KEY="your-key-here"
  export DYFI_DOMAIN="example.dy.fi"
  export DYFI_USER="your-email@example.com"
  export DYFI_PASS="your-password"
  export ACME_EMAIL="admin@example.com"
  export LOG_FILE="/var/log/twostepauth.log"
  ```

### Firewall Configuration

- [ ] **Open Ports**:
  - Port 443 (HTTPS)
  - Port 80 (Let's Encrypt HTTP-01 challenge only)

- [ ] **Install fail2ban**:
  ```bash
  apt-get install fail2ban
  ```

- [ ] **Configure fail2ban Filter** (`/etc/fail2ban/filter.d/twostepauth.conf`):
  ```ini
  [Definition]
  failregex = AUTH_FAILURE: .* from IP <HOST>
              RATE_LIMIT_EXCEEDED: .* from IP <HOST>
              API_KEY_INVALID: .* from IP <HOST>
              API_KEY_MISSING: .* from IP <HOST>
  ignoreregex =
  ```

- [ ] **Configure fail2ban Jail** (`/etc/fail2ban/jail.d/twostepauth.local`):
  ```ini
  [twostepauth]
  enabled  = true
  port     = 80,443
  filter   = twostepauth
  logpath  = /var/log/twostepauth.log
  maxretry = 5
  bantime  = 3600
  findtime = 600
  ```

- [ ] **Restart fail2ban**:
  ```bash
  systemctl restart fail2ban
  systemctl status fail2ban
  ```

### DNS Configuration (dy.fi)

- [ ] Register domain at https://www.dy.fi/
- [ ] Note your dy.fi credentials
- [ ] Configure environment variables (DYFI_DOMAIN, DYFI_USER, DYFI_PASS)
- [ ] Manager will automatically update DNS every 20 hours

### TLS Certificate

**Option A: Let's Encrypt (Production)**
- [ ] Ensure ports 80 and 443 are open
- [ ] Run with domain flag:
  ```bash
  sudo ./manager --port=443 --domain=example.dy.fi
  ```
- [ ] Certificates will be automatically obtained and renewed

**Option B: Self-Signed (Development/Internal)**
- [ ] Run without domain flag:
  ```bash
  ./manager --port=8080
  ```
- [ ] Accept self-signed certificate warning in browser

### Gateway Mode (Optional)

If you need to support external ping workers outside your network:

- [ ] **Enable Gateway**: Add `--enable-gateway` flag when starting manager
  ```bash
  sudo ./manager --port=443 --domain=example.dy.fi --enable-gateway
  ```
- [ ] **Register Internal Workers**: Add input/output services to dashboard
- [ ] **Generate API Keys**: Create keys for each external ping worker
- [ ] **Secure API Keys**: Store keys in environment variables, not in code
- [ ] **Monitor Usage**: Regularly check `/api/apikeys/list` for unusual activity
- [ ] **Rotate Keys**: Rotate API keys periodically (recommended: every 90 days)
- [ ] **Revoke Unused**: Remove keys for decommissioned workers

See [GATEWAY.md](GATEWAY.md) for detailed setup instructions.

### Running as Systemd Service

Create `/etc/systemd/system/ping-manager.service`:

```ini
[Unit]
Description=Ping Service Manager
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/ping_service/manager
Environment="SERVER_KEY=your-key-here"
Environment="DYFI_DOMAIN=example.dy.fi"
Environment="DYFI_USER=your-email@example.com"
Environment="DYFI_PASS=your-password"
Environment="ACME_EMAIL=admin@example.com"
Environment="LOG_FILE=/var/log/twostepauth.log"
ExecStart=/opt/ping_service/manager/manager --port=443 --domain=example.dy.fi --enable-gateway
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Enable and start:
```bash
systemctl daemon-reload
systemctl enable ping-manager
systemctl start ping-manager
systemctl status ping-manager
```

### Monitoring

- [ ] **Check Logs**:
  ```bash
  tail -f /var/log/twostepauth.log
  ```

- [ ] **Monitor fail2ban**:
  ```bash
  fail2ban-client status twostepauth
  ```

- [ ] **Health Endpoint**: Verify `/health` responds:
  ```bash
  curl https://example.dy.fi/health
  # Should return: {"status":"healthy"}
  ```

- [ ] **dy.fi Failover**: Check logs for DNS pointer status (ACTIVE/STANDBY/FAILOVER)

## Security Best Practices

### User Management
- ✅ Use strong, unique User IDs (avoid common names like "admin", "root")
- ✅ Backup TOTP secret or print QR code in case device is lost
- ✅ Regularly rotate SERVER_KEY and regenerate user TOTP secrets
- ✅ Remove unused user accounts promptly

### Server Hardening
- ✅ Keep Go and system packages up to date
- ✅ Run as non-root user when possible (except for port 443 binding)
- ✅ Use dedicated server/VM for the manager (isolation)
- ✅ Enable automatic security updates
- ✅ Regular backups of `users_data` and `workers_data.json`

### Network Security
- ✅ Use fail2ban to block repeat offenders
- ✅ Consider additional firewall rules (e.g., geographic restrictions)
- ✅ Monitor logs for unusual patterns
- ✅ Set up alerts for AUTH_FAILURE spikes

### Application Updates
- ✅ Monitor this repository for security updates
- ✅ Test updates in staging environment first
- ✅ Have rollback plan ready
- ✅ Review CHANGELOG for security-related changes

## Security Audit Results

### Common Vulnerabilities (OWASP Top 10)

| Vulnerability | Risk | Mitigation |
|--------------|------|------------|
| **A01: Broken Access Control** | ✅ Low | TOTP 2FA, encrypted sessions, auth checks on all endpoints |
| **A02: Cryptographic Failures** | ✅ Low | TLS 1.2+, AES-256-GCM, strong ciphers, HSTS enabled |
| **A03: Injection** | ✅ Low | Input validation, no SQL/command execution of user input |
| **A04: Insecure Design** | ✅ Low | Defense in depth: rate limiting + fail2ban + input validation |
| **A05: Security Misconfiguration** | ✅ Low | Secure defaults, security headers, minimal attack surface |
| **A06: Vulnerable Components** | ⚠️ Medium | Keep dependencies updated (Go, autocert, otp libraries) |
| **A07: Authentication Failures** | ✅ Low | TOTP 2FA, rate limiting, fail2ban, secure session management |
| **A08: Software/Data Integrity** | ✅ Low | TLS for all communication, encrypted storage |
| **A09: Logging/Monitoring Failures** | ✅ Low | Comprehensive security logging, fail2ban integration |
| **A10: SSRF** | ✅ Low | No user-controlled URL fetching (REST client is admin-only) |

### Recommended Additional Measures

**Optional Enhancements** (not required, but can improve security):

1. **Geographic Restrictions**: Use `iptables` or `ufw` to block regions you don't operate in
2. **Port Knocking**: Hide port 443 behind port knocking sequence
3. **VPN Access**: Require VPN connection for dashboard access
4. **IP Whitelist**: Restrict admin access to known IPs only
5. **Alert System**: Set up email/Telegram alerts for AUTH_FAILURE events
6. **Backup Encryption**: Encrypt backup files of `users_data`
7. **Audit Logging**: Log all worker registration/removal events
8. **Multi-User Support**: Add role-based access control (RBAC) for team access

## Incident Response

If you suspect a security breach:

1. **Immediate Actions**:
   - Check fail2ban status: `fail2ban-client status twostepauth`
   - Review logs: `grep AUTH_FAILURE /var/log/twostepauth.log`
   - Check active sessions: Restart service to clear all sessions
   - Review worker list for unauthorized additions

2. **Containment**:
   - Rotate SERVER_KEY immediately
   - Regenerate all user TOTP secrets
   - Review and remove any suspicious workers
   - Check worker health logs for unusual access patterns

3. **Recovery**:
   - Update to latest version
   - Review fail2ban rules
   - Audit all configuration files
   - Restore from known-good backup if necessary

4. **Prevention**:
   - Analyze attack vector
   - Implement additional controls if needed
   - Update this document with lessons learned

## Support and Reporting

- **Security Issues**: Report privately to maintainer before public disclosure
- **Questions**: Open GitHub issue (do not include sensitive info)
- **Updates**: Watch repository for security announcements

---

**Last Updated**: 2026-01-07
**Version**: 1.0
**Security Review Status**: Self-audited, production-ready for small-to-medium deployments