foxhunt/docs/SECURITY.md

# Foxhunt Security Implementation

## 🔒 Overview

The Foxhunt HFT trading system implements enterprise-grade security measures designed to protect against threats while maintaining ultra-low latency performance. This document outlines the comprehensive security implementations and best practices.

## 🛡️ Security Architecture

### Defense in Depth

The security system implements multiple layers of protection:

1. **Network Security** - TLS 1.3, firewall rules, VPN access
2. **Authentication** - Multi-factor authentication, secure session management  
3. **Authorization** - Role-based access control with fine-grained permissions
4. **Input Validation** - Comprehensive sanitization and injection prevention
5. **Audit Logging** - Complete security event tracking and SIEM integration
6. **Encryption** - AES-256-GCM for data at rest and in transit
7. **Secrets Management** - HashiCorp Vault integration

### Security Components

```
┌─────────────────────────────────────────────────────────┐
│                    Web Application                        │
├─────────────────────────────────────────────────────────┤
│  Authentication Middleware │ Authorization Middleware    │
├─────────────────────────────────────────────────────────┤
│  Input Validation          │ Rate Limiting              │
├─────────────────────────────────────────────────────────┤
│  Audit Logger              │ SIEM Integration           │
├─────────────────────────────────────────────────────────┤
│  Encryption Manager        │ Secrets Manager            │
├─────────────────────────────────────────────────────────┤
│  HashiCorp Vault           │ Database Security          │
└─────────────────────────────────────────────────────────┘
```

## 🔐 Authentication & Authorization

### Authentication Methods

1. **Mutual TLS (mTLS) Authentication** 🆕
   - Client certificate validation for service-to-service communication
   - Automated certificate provisioning via HashiCorp Vault PKI
   - Certificate rotation with zero downtime
   - Circuit breaker pattern for Vault reliability
   - Required for all production gRPC endpoints

2. **JWT Token Authentication** ✨ *Enhanced* - **VAULT INTEGRATED** 🔐
   - **SECURITY ENHANCEMENT**: Production JWT secrets stored in HashiCorp Vault
   - **SECURITY ENHANCEMENT**: Minimum 64-character JWT secrets (512-bit security)
   - **SECURITY FIX**: Authentication bypass vulnerability patched
   - **VAULT ROTATION**: JWT secret rotation managed via Vault (secret/foxhunt/jwt)
   - Shannon entropy validation for secret strength
   - Secure JWT tokens with 1-hour expiration
   - Argon2 password hashing with salt
   - Session management with automatic timeout
   - Account lockout after 5 failed attempts
   - Enhanced validation with strict issuer/audience checks
   - Fallback to environment variables for development only

3. **API Key Authentication** ✨ *Enhanced*
   - **SECURITY ENHANCEMENT**: Hardcoded development credentials removed
   - Prefixed API keys (`foxhunt_`) with SHA-256 hashing
   - Database-backed validation with encrypted storage
   - Secure development mode with explicit configuration
   - Configurable expiration and rate limiting
   - IP address restrictions (optional)
   - Granular permission scoping
   - Last-used timestamp tracking

4. **Multi-Factor Authentication (Optional)**
   - TOTP-based (Google Authenticator compatible)
   - Backup codes for recovery
   - Required for admin accounts

### User Roles & Permissions

| Role | Permissions | Description |
|------|------------|-------------|
| **Admin** | All permissions | System administrators |
| **TradingManager** | Portfolio + Risk + View | Senior traders |
| **Trader** | Execute + Modify + Cancel orders | Active traders |
| **RiskManager** | Risk limits + Emergency stop | Risk oversight |
| **Analyst** | View positions + Historical data | Quantitative analysts |
| **ComplianceOfficer** | Audit logs + Compliance reports | Regulatory compliance |
| **Viewer** | Read-only access | Observers |
| **ApiUser** | API access only | Automated systems |
| **Auditor** | Audit logs + System config | External auditors |

### Permission Matrix

| Resource | Admin | TradingManager | Trader | RiskManager | Analyst | ComplianceOfficer | Viewer | ApiUser | Auditor |
|----------|-------|----------------|---------|------------|---------|-------------------|--------|---------|---------|
| Execute Trades | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Modify Orders | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Cancel Orders | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| View Positions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Set Risk Limits | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Emergency Stop | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| View Audit Logs | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ |
| System Admin | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |

## 🔒 Input Validation & Security

### Enhanced Validation Rules ✨

The system implements comprehensive input validation with recent security enhancements:

1. **Symbol Validation** ✨ *Enhanced*
   - Pattern: `^[A-Z0-9._-]+$`
   - Length: 1-20 characters
   - **SECURITY ENHANCEMENT**: Advanced SQL injection pattern detection
   - Real-time threat pattern matching

2. **Order Validation** ✨ *Enhanced*
   - Quantity: 1-1,000,000,000 (no zero or negative)
   - Price: 0.01-1,000,000.00 (for limit orders)
   - Finite numbers only (no NaN/Infinity)
   - **SECURITY ENHANCEMENT**: Buffer overflow protection
   - Input length limits to prevent DoS attacks

3. **JWT Secret Validation** 🆕
   - **CRITICAL**: Minimum 64-character requirement (up from 32)
   - Shannon entropy calculation (minimum 4.0 bits/char)
   - Mixed case, numbers, and symbols required
   - Weak pattern detection (repeated sequences, dictionary words)
   - Maximum length protection (1024 chars) against DoS

4. **API Key Validation** 🆕
   - Minimum 20-character requirement
   - Maximum 255-character limit
   - Valid character set enforcement (alphanumeric + underscore/hyphen)
   - Database hash verification with salting

5. **User Input Validation** ✨ *Enhanced*
   - Email: RFC 5322 compliant format
   - Username: Alphanumeric with limited special chars
   - Password: Minimum 12 chars, complexity requirements
   - **SECURITY ENHANCEMENT**: Advanced pattern matching

6. **Injection Prevention** ✨ *Enhanced*
   - **SECURITY ENHANCEMENT**: Multi-layer SQL injection detection
   - XSS payload detection with context-aware filtering
   - Command injection prevention with whitelist validation
   - NoSQL injection protection
   - **NEW**: Buffer overflow detection and prevention

### Security Patterns Detected

The system automatically detects and blocks:

```regex
# SQL Injection
(?i)(union|select|insert|update|delete|drop|exec|execute)
('|\"|;|--|\|\/\*|\*\/)

# XSS
(\<|\>|&lt;|&gt;|&amp;)
(?i)(script|javascript|vbscript|onload|onerror)

# Command Injection  
(;|\||&|`|\$\()
```

## 📝 Audit Logging & Monitoring

### Audit Events

All security-relevant events are logged:

- **Authentication Events**: Login success/failure, token issued/expired
- **Authorization Events**: Permission granted/denied, role changes
- **Trading Events**: Order placed/cancelled, trades executed
- **Administrative Events**: Configuration changes, user management
- **Security Events**: Suspicious activity, security breaches

### Log Format

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2023-12-07T10:30:00Z",
  "event_type": "LoginSuccess", 
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "username": "trader@foxhunt.com",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "resource": "orders",
  "action": "create",
  "result": "success",
  "metadata": {
    "session_id": "session-123",
    "order_id": "order-456"
  },
  "severity": "info"
}
```

### SIEM Integration

- **Splunk** integration for enterprise monitoring
- **Elasticsearch** support for log analysis
- **Real-time alerting** for security incidents
- **Threat intelligence** integration

## 🔐 Encryption & Secrets Management

### Enhanced Encryption Standards ✨

1. **Data at Rest** ✨ *Enhanced*
   - AES-256-GCM encryption
   - Key rotation every 90 days
   - Hardware Security Module (HSM) support
   - **SECURITY ENHANCEMENT**: Database field-level encryption

2. **Data in Transit** ✨ *Enhanced*
   - TLS 1.3 minimum version
   - Perfect Forward Secrecy
   - **NEW**: Mutual TLS (mTLS) for service communication
   - Certificate pinning
   - **SECURITY ENHANCEMENT**: Automated certificate rotation

3. **Application Secrets** ✨ *Enhanced*
   - HashiCorp Vault integration with circuit breaker
   - **NEW**: Vault PKI engine for certificate management
   - Automatic secret rotation
   - **SECURITY ENHANCEMENT**: AppRole authentication
   - Encrypted environment variables
   - **SECURITY FIX**: Hardcoded credentials removed

### Certificate Management (NEW) 🆕

```rust
// Automated Certificate Lifecycle Management
let cert_manager = CertificateManager::new(config).await?;
let cert = cert_manager.get_certificate("trading-service").await?;

// Zero-downtime rotation
cert_manager.start_rotation_task().await;
```

### Secrets Management ✨ *Enhanced*

```bash
# Vault Integration Example
vault write secret/foxhunt/prod/db \
  username="prod_user" \
  password="secure_password"

vault write secret/foxhunt/prod/api \
  polygon_key="your_key" \
  jwt_secret="$(openssl rand -base64 64)"  # 64+ chars required

# NEW: PKI Certificate Management
vault write pki/roles/trading-service \
  allowed_domains="trading.foxhunt.internal" \
  allow_subdomains=true \
  max_ttl="24h"
```

### Security Configuration Validation 🆕

```bash
# JWT Secret Validation
FOXHUNT_JWT_SECRET=$(openssl rand -base64 64)  # Minimum 64 chars
echo "JWT secret entropy: $(python3 -c 'import math; s="$FOXHUNT_JWT_SECRET"; print(f"{-sum(s.count(c)/len(s)*math.log2(s.count(c)/len(s)) for c in set(s)):.2f} bits/char")')" 

# Development Mode Security Warning
if [ "$FOXHUNT_DEVELOPMENT_MODE" = "true" ]; then
    echo "⚠️  SECURITY WARNING: Development mode enabled - NOT for production!"
fi
```

## ⚡ Performance Considerations

### Low-Latency Security

Security implementations are optimized for HFT requirements:

- **Authentication**: < 100μs token validation
- **Authorization**: < 50μs permission checks  
- **Input Validation**: < 10μs for order validation
- **Audit Logging**: Asynchronous, non-blocking
- **Encryption**: Hardware-accelerated when available

### Caching Strategy

- **JWT Claims**: Cached for session duration
- **User Permissions**: 5-minute cache TTL
- **Rate Limits**: In-memory sliding window
- **Audit Events**: Batched writes every 1 second

## 🚨 Incident Response

### Security Incidents

1. **Detection**: SIEM alerts, anomaly detection
2. **Analysis**: Log correlation, threat hunting
3. **Containment**: Account lockout, service isolation
4. **Eradication**: Malware removal, vulnerability patching
5. **Recovery**: Service restoration, monitoring
6. **Lessons Learned**: Process improvement, training

### Emergency Procedures

- **Emergency Stop**: Halt all trading activities
- **Account Lockout**: Disable compromised accounts
- **Service Isolation**: Network segmentation
- **Incident Communication**: Stakeholder notification

## 🔧 Configuration

### Environment Variables

Critical security configuration (see `.env.example`):

```bash
# JWT Configuration
FOXHUNT_JWT_SECRET=your-64-character-secret
FOXHUNT_SESSION_TIMEOUT_MINUTES=480

# Authentication
FOXHUNT_MAX_FAILED_ATTEMPTS=5
FOXHUNT_LOCKOUT_DURATION_MINUTES=15
FOXHUNT_PASSWORD_MIN_LENGTH=12

# Encryption
FOXHUNT_ENCRYPTION_ALGORITHM=AES-256-GCM
FOXHUNT_TLS_VERSION=1.3

# Vault
FOXHUNT_VAULT_URL=https://vault.example.com
FOXHUNT_VAULT_TOKEN=hvs.your-token-here
```

### Production Checklist

- [ ] Generate strong JWT secret (64+ characters)
- [ ] Configure HashiCorp Vault for secrets
- [ ] Enable TLS 1.3 with valid certificates
- [ ] Set up SIEM integration (Splunk/ELK)
- [ ] Configure firewall rules and VPN access
- [ ] Enable MFA for all admin accounts
- [ ] Set appropriate session timeouts
- [ ] Configure audit log retention (90+ days)
- [ ] Set up automated security scanning
- [ ] Configure backup and disaster recovery

## 🧪 Security Testing

### Test Coverage

The security test suite includes:

1. **Authentication Tests**
   - Valid/invalid credentials
   - Token validation and expiration
   - Account lockout scenarios
   - Concurrent authentication

2. **Authorization Tests**
   - Role-based access control
   - Permission boundary testing
   - Privilege escalation prevention

3. **Input Validation Tests**
   - SQL injection attempts
   - XSS payloads
   - Command injection
   - Buffer overflow attempts
   - Malformed JSON payloads

4. **Security Integration Tests**
   - End-to-end authentication flows
   - Audit log verification
   - Rate limiting enforcement
   - Session management

### Running Security Tests

```bash
# Run comprehensive security test suite
cargo test security_integration_tests

# Run specific security tests
cargo test test_authentication_integration
cargo test test_input_validation_comprehensive
cargo test test_authorization_roles

# Run security benchmarks
cargo bench security_benchmarks
```

## 🔍 Vulnerability Management

### Security Scanning

Regular security assessments include:

- **SAST**: Static Application Security Testing
- **DAST**: Dynamic Application Security Testing
- **Dependency Scanning**: Known vulnerability detection
- **Container Scanning**: Docker image vulnerabilities
- **Infrastructure Scanning**: Cloud security posture

### Penetration Testing

Annual penetration testing covers:

- **External Attack Surface**: Internet-facing services
- **Internal Networks**: Lateral movement scenarios
- **Application Security**: Business logic flaws
- **Social Engineering**: Phishing simulations
- **Physical Security**: Data center access

## 📋 Compliance

### Regulatory Compliance

The security implementation supports:

- **SOX**: Audit trails and access controls
- **PCI DSS**: Secure payment card handling
- **GDPR**: Privacy by design and data protection
- **FINRA**: Financial services requirements
- **MiFID II**: European markets compliance
- **SOC 2 Type II**: Security and availability controls

### Security Certifications

Target certifications:
- ISO 27001 (Information Security Management)
- SOC 2 Type II (Security and Availability)
- PCI DSS Level 1 (Payment Card Security)

## 🔐 JWT Secret Rotation (Agent H2)

### Overview

JWT signing secrets are now securely managed through HashiCorp Vault with production-grade cryptographic strength. This implementation provides:

- **512-bit security**: Minimum 64-character secrets (base64-encoded)
- **Vault integration**: Centralized secret management at `secret/foxhunt/jwt`
- **Graceful rotation**: Zero-downtime secret updates
- **Entropy validation**: Automatic strength verification
- **Development fallback**: Environment variable support for local development

### Configuration Priority

The system loads JWT configuration in the following order:

1. **Vault** (Production): `secret/foxhunt/jwt`
   - `jwt_secret`: 64+ character base64 string
   - `jwt_issuer`: "foxhunt-api-gateway"
   - `jwt_audience`: "foxhunt-services"
   - `rotation_date`: ISO 8601 date for tracking

2. **JWT_SECRET_FILE** (File-based): Path to secret file
   - Used when Vault is unavailable
   - File should contain only the secret (trimmed)

3. **JWT_SECRET** (Environment): Direct environment variable
   - Development only - logs warning
   - Not recommended for production

### Current Production Secret

```bash
# Stored in Vault at secret/foxhunt/jwt
Secret Length: 88 characters (base64)
Entropy: High (verified)
Rotation Date: 2025-10-18
Next Rotation: 2026-01-18 (90 days)
```

### Rotation Procedure

#### 1. Generate New Secret

```bash
# Generate 64-byte (512-bit) secret
openssl rand -base64 64 | tr -d '\n'
```

#### 2. Store in Vault

```bash
# Connect to Vault
export VAULT_ADDR='http://localhost:8200'
export VAULT_TOKEN='<production-token>'

# Store new secret with metadata
vault kv put secret/foxhunt/jwt \
  jwt_secret='<new-secret>' \
  jwt_issuer='foxhunt-api-gateway' \
  jwt_audience='foxhunt-services' \
  rotation_date="$(date -u +%Y-%m-%d)"
```

#### 3. Verify Storage

```bash
# Verify secret was stored (redacted output)
vault kv get secret/foxhunt/jwt
```

#### 4. Restart Services

```bash
# Restart API Gateway to load new secret
docker-compose restart api_gateway

# Verify gateway is healthy
docker-compose logs -f api_gateway | grep "JWT configuration loaded"
```

#### 5. Validate Authentication

```bash
# Test JWT generation and validation
cargo test -p api_gateway jwt_service

# Test end-to-end authentication
curl -H "Authorization: Bearer <token>" https://localhost:50051/health
```

### Security Requirements

**Secret Strength**:
- Minimum 64 characters (512-bit security)
- Must include at least 3 of: uppercase, lowercase, digits, special characters
- Maximum 5 consecutive repeated characters
- No sequential patterns (e.g., "123456", "abcdef")

**Rotation Policy**:
- Regular rotation: Every 90 days
- Incident rotation: Within 24 hours of suspected compromise
- Planned rotation: During low-traffic maintenance windows

**Access Control**:
- Vault access restricted to operations team
- Secret access audited and logged
- Rotation events tracked in security logs

### Testing

```bash
# Unit tests for JWT config
cargo test -p config jwt_config

# Integration tests with Vault
VAULT_ADDR=http://localhost:8200 VAULT_TOKEN=foxhunt-dev-root \
  cargo test -p api_gateway jwt_service::tests

# Validate secret strength
cargo test -p api_gateway test_jwt_secret
```

### Troubleshooting

**Vault Connection Failed**:
- Check `VAULT_ADDR` and `VAULT_TOKEN` environment variables
- Verify Vault service is running: `docker-compose ps vault`
- System falls back to `JWT_SECRET` environment variable with warning

**Authentication Failures After Rotation**:
- Old tokens remain valid until expiration (1 hour)
- Force token refresh by logging out and back in
- Check service logs for JWT validation errors

**Secret Validation Fails**:
- Secret must be at least 64 characters
- Check entropy requirements (character variety)
- Generate new secret with `openssl rand -base64 64`

## 🆘 Security Contacts

### Security Team

- **Security Officer**: security@foxhunt.com
- **Incident Response**: incident@foxhunt.com
- **Vulnerability Reports**: security-reports@foxhunt.com

### Emergency Contacts

- **24/7 Security Hotline**: +1-555-SEC-HELP (555-732-4357)
- **Incident Response Team**: incident-team@foxhunt.com

## 📚 Additional Resources

### Documentation

- [Authentication API Reference](./docs/api/authentication.md)
- [Authorization Guide](./docs/guides/authorization.md)
- [Deployment Security](./docs/deployment/security.md)
- [Incident Response Playbook](./docs/security/incident-response.md)

### Security Training

- Security awareness training for all staff
- Secure coding practices for developers
- Incident response training for operations
- Regular security updates and briefings

---

**Last Updated**: October 2025 (Agent H2: JWT Secret Rotation)
**Version**: 1.1
**Classification**: Internal Use Only