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:

# 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

{
  "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) 🆕

// 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

# 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 🆕

# 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):

# 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

# 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

# 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

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

2. Store in Vault

# 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

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

4. Restart Services

# 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

# 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

# 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
• Authorization Guide
• Deployment Security
• Incident Response Playbook

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