Skip to content

Security: cluster2600/ELVIS

Security

SECURITY.md

Security Documentation - ELVIS Trading Bot

Overview

ELVIS Trading Bot implements enterprise-grade security practices with HashiCorp Vault integration for secure secrets management and API key protection.

🔐 HashiCorp Vault Integration

Security Architecture

  • Centralized Secret Management: All API keys, credentials, and sensitive data stored in Vault
  • Encryption at Rest: Vault encrypts all secrets using AES-256-GCM
  • Encryption in Transit: All communications with Vault use TLS
  • Token-Based Authentication: Secure token-based access control
  • Audit Logging: Complete audit trail of all secret access

Implementation Details

Vault Client (utils/vault_client.py)

  • Purpose: Secure interface to HashiCorp Vault KV v2 secrets engine
  • Features:
    • Encrypted local cache with Fernet encryption
    • TTL-based cache invalidation (5 minutes)
    • Automatic token refresh and authentication
    • Comprehensive error handling and fallbacks

Enhanced Secrets Manager (utils/secrets_manager.py)

  • Multi-Layer Security:
    1. Primary: HashiCorp Vault (most secure)
    2. Secondary: OS Keyring (system-level encryption)
    3. Fallback: Encrypted local files (Fernet encryption)
    4. Last Resort: Environment variables

Secret Storage Hierarchy

Vault KV v2 Paths:
├── secret/trading/api-keys/
│   ├── binance-api-key
│   ├── binance-api-secret
│   └── telegram-bot-token
├── secret/database/credentials/
│   ├── postgres-host
│   ├── postgres-user
│   └── postgres-password
└── secret/notifications/webhooks/
    └── webhook-urls

Security Benefits

1. Zero Hardcoded Secrets

  • No API keys, passwords, or tokens in source code
  • All sensitive data retrieved dynamically from secure storage
  • Reduces risk of accidental exposure in logs or code repositories

2. Principle of Least Privilege

  • Each component requests only the secrets it needs
  • Role-based access control (when Vault policies are configured)
  • Time-limited token access

3. Comprehensive Audit Trail

  • All secret access logged with timestamps
  • Failed authentication attempts tracked
  • Secret rotation events recorded

4. Encryption Everywhere

  • At Rest: Vault backend encryption + local cache encryption
  • In Transit: TLS for all Vault communications
  • In Memory: Minimal exposure time, automatic cleanup

5. Graceful Degradation

  • System continues operating if Vault is temporarily unavailable
  • Automatic fallback to secure local storage
  • Health monitoring and alerting for Vault connectivity

🔧 Configuration & Setup

Development Environment

# Start Vault dev server
vault server -dev -dev-root-token-id=trading-bot-token

# Set environment variables
export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=trading-bot-token

# Initialize secrets
vault kv put secret/trading/api-keys \
    binance-api-key=your-api-key \
    binance-api-secret=your-api-secret

Production Environment

# Use proper Vault cluster with:
# - TLS certificates
# - Authentication backends (LDAP/AWS/GCP)
# - Comprehensive policies
# - High availability setup
# - Backup and disaster recovery

Security Best Practices

1. Token Management

# Tokens have limited TTL
# Automatic renewal implemented
# Secure token storage (not in environment variables)

2. Error Handling

# No sensitive data in error messages
# Secure fallback mechanisms
# Comprehensive logging without secret exposure

3. Cache Security

# Local cache encrypted with Fernet
# TTL-based automatic expiration
# Secure key generation and storage

🚨 Security Monitoring

Real-Time Health Checks

  • API Connection Tester: Monitors Vault connectivity and authentication
  • Dashboard Integration: Visual indicators for security status
  • Automated Alerts: Notifications for security issues

Health Check Indicators

  • ✅ Vault Connected: Authentication successful, secrets accessible
  • ⚠️ Vault Warning: Connected but degraded performance
  • ❌ Vault Error: Authentication failed or connectivity issues

Monitoring Metrics

vault_status = {
    'enabled': True,
    'connected': True,
    'healthy': True,
    'url': 'https://vault.example.com',
    'response_time': 0.003,  # 3ms
    'last_checked': datetime.now()
}

🛡️ Security Compliance

Industry Standards

  • OWASP: Follows OWASP Top 10 security practices
  • SOC 2: Vault provides SOC 2 Type II compliance
  • FIPS 140-2: Cryptographic modules meet FIPS standards
  • Common Criteria: EAL4+ evaluated security

Data Protection

  • PII Handling: No personally identifiable information stored
  • API Key Protection: Military-grade encryption for trading credentials
  • Access Logging: Complete audit trail for compliance

Risk Mitigation

  • Secret Rotation: Automated rotation capabilities
  • Breach Response: Immediate revocation and re-keying
  • Incident Response: Comprehensive logging for forensics

🔍 Security Testing

Automated Security Checks

# Vault connectivity tests
def test_vault_security():
    - Authentication verification
    - Encryption validation
    - Access control testing
    - Audit log verification

Penetration Testing

  • Regular security assessments
  • Vulnerability scanning
  • Code security reviews
  • Infrastructure hardening

📚 Additional Resources

Documentation

Emergency Procedures

  • Vault Compromise: Immediate token revocation and re-keying
  • Secret Exposure: Automated rotation and notification
  • Service Disruption: Graceful fallback to secure local storage

Last Updated: July 20, 2025
Security Review: Complete
Next Review: January 20, 2026

Note: This security implementation represents enterprise-grade protection for cryptocurrency trading operations. All security measures are actively monitored and regularly audited.

There aren’t any published security advisories