mev-beta/docs/3_core_packages/SECURITY_PACKAGE.md

Security Package Documentation

Overview

The security package provides secure private key management and transaction signing for the MEV Bot application. It implements comprehensive security measures including encryption, rate limiting, key rotation, audit logging, and permission controls to protect sensitive cryptographic assets.

Core Components

KeyManager Structure

The main key manager structure provides secure key management:

1. Logger - Structured logging for security events
2. Keystore - Ethereum keystore for key storage
3. Encryption Key - Master encryption key for key protection
4. Keys - In-memory map of secure keys
5. Configuration - Security configuration parameters
6. Rate Limiting - Transaction signing rate limiting
7. Audit Logging - Security audit trail

KeyManagerConfig Structure

Configuration for the key manager:

• KeystorePath - Path to keystore directory
• EncryptionKey - Master encryption key
• KeyRotationDays - Days before key rotation warning
• MaxSigningRate - Maximum signings per minute
• RequireHardware - Whether to require hardware security module
• BackupPath - Path for encrypted key backups
• AuditLogPath - Path for audit logging
• SessionTimeout - How long before re-authentication required

SecureKey Structure

Represents a securely stored private key:

• Address - Ethereum address
• EncryptedKey - AES-GCM encrypted private key
• CreatedAt - Key creation timestamp
• LastUsed - Last usage timestamp
• UsageCount - Number of times used
• MaxUsage - Maximum usage limit (optional)
• ExpiresAt - Expiration time (optional)
• BackupLocations - Backup file locations
• KeyType - Key type ("trading", "emergency", "backup")
• Permissions - Key permissions
• IsActive - Whether key is active

KeyPermissions Structure

Defines what operations a key can perform:

• CanSign - Whether key can sign transactions
• CanTransfer - Whether key can transfer value
• MaxTransferWei - Maximum transfer amount (optional)
• AllowedContracts - Allowed contract addresses (optional)
• RequireConfirm - Whether confirmation is required

Key Management Functions

NewKeyManager(config *KeyManagerConfig, logger *logger.Logger) (*KeyManager, error)

Creates a new secure key manager:

1. Validates configuration
2. Creates keystore directory
3. Initializes encryption
4. Loads existing keys
5. Starts background maintenance tasks

GenerateKey(keyType string, permissions KeyPermissions) (common.Address, error)

Generates a new private key with specified permissions:

1. Creates new ECDSA private key
2. Encrypts with AES-GCM
3. Stores securely with metadata
4. Creates backup
5. Logs audit entry

ImportKey(privateKeyHex string, keyType string, permissions KeyPermissions) (common.Address, error)

Imports an existing private key:

1. Parses hex private key
2. Checks for duplicates
3. Encrypts with AES-GCM
4. Stores securely with metadata
5. Creates backup
6. Logs audit entry

GetKeyInfo(address common.Address) (*SecureKey, error)

Returns information about a key without sensitive data:

1. Retrieves key information
2. Removes encrypted key data
3. Returns safe copy

ListKeys() []common.Address

Returns addresses of all managed keys:

1. Iterates through key map
2. Returns address list

RotateKey(oldAddress common.Address) (common.Address, error)

Creates a new key to replace an existing one:

1. Generates new key with same permissions
2. Marks old key as inactive
3. Logs audit entry

Transaction Signing

SignTransaction(request *SigningRequest) (*SigningResult, error)

Signs a transaction with comprehensive security checks:

1. Validates key exists and is active
2. Checks permissions and limits
3. Applies rate limiting
4. Performs security warnings
5. Decrypts private key
6. Signs transaction
7. Updates key usage
8. Logs audit entry

Security Checks Performed:

• Key existence and activity
• Signing permissions
• Key expiration
• Usage limits
• Transfer permissions and limits
• Contract interaction permissions
• Rate limiting
• Security warnings

SigningRequest Structure

• Transaction - Transaction to sign
• ChainID - Chain identifier
• From - Sender address
• Purpose - Description of transaction
• UrgencyLevel - Urgency level (1-5)

SigningResult Structure

• SignedTx - Signed transaction
• Signature - Raw signature bytes
• SignedAt - Signing timestamp
• KeyUsed - Key used for signing
• AuditID - Audit identifier
• Warnings - Security warnings

Encryption and Security

Key Encryption

The key manager uses AES-GCM encryption:

1. AES-256 - Strong symmetric encryption
2. GCM Mode - Authenticated encryption
3. Random Nonces - Unique per encryption
4. Scrypt KDF - Secure key derivation

encryptPrivateKey(privateKey *ecdsa.PrivateKey) ([]byte, error)

Encrypts a private key using AES-GCM:

1. Converts private key to bytes
2. Creates AES cipher
3. Generates random nonce
4. Encrypts with authentication
5. Clears original key bytes

decryptPrivateKey(encryptedKey []byte) (*ecdsa.PrivateKey, error)

Decrypts an encrypted private key:

1. Creates AES cipher
2. Extracts nonce
3. Decrypts with authentication
4. Converts to ECDSA private key
5. Clears decrypted bytes

Memory Security

The key manager implements memory security measures:

• Clears private key bytes after use
• Uses secure key derivation
• Implements secure random generation
• Clears sensitive data from memory

Rate Limiting

checkRateLimit(address common.Address) error

Checks if signing rate limit is exceeded:

1. Tracks signings per key
2. Resets counter every minute
3. Enforces maximum rate
4. Returns error if exceeded

Configuration

• MaxSigningRate - Maximum signings per minute per key
• Rate Limiting Disabled - When MaxSigningRate <= 0

Audit Logging

auditLog(operation string, keyAddress common.Address, success bool, details string)

Writes an entry to the audit log:

1. Creates audit entry with timestamp
2. Calculates risk score
3. Writes to audit log file
4. Logs to main logger

AuditEntry Structure

• Timestamp - Event timestamp
• Operation - Operation performed
• KeyAddress - Key address involved
• Success - Whether operation succeeded
• Details - Detailed information
• IPAddress - IP address (optional)
• UserAgent - User agent (optional)
• RiskScore - Risk score (1-10)

Risk Scoring

• Failed Operations - High risk (8)
• Transaction Signing - Medium risk (3)
• Key Generation - Medium-high risk (5)
• Key Rotation - Medium risk (4)
• Other Operations - Low risk (2)

Backup and Recovery

createKeyBackup(secureKey *SecureKey) error

Creates an encrypted backup of a key:

1. Creates backup file path
2. Prepares backup data
3. Encrypts with additional encryption
4. Writes to backup file
5. Updates backup locations

Backup Security

• Separate Encryption - Additional encryption for backups
• Secure Storage - Configurable backup path
• Multiple Backups - Tracks backup locations
• Encrypted Data - Backup data encryption

Maintenance and Monitoring

backgroundTasks()

Runs periodic maintenance tasks:

1. Hourly maintenance checks
2. Key expiration monitoring
3. Key rotation reminders

performMaintenance()

Performs periodic security maintenance:

1. Checks for expired keys
2. Checks for keys needing rotation
3. Logs warnings for security issues

Key Lifecycle Management

• Automatic Key Generation - Generates default key if none exist
• Key Expiration - Automatic expiration checking
• Rotation Reminders - Periodic rotation warnings
• Usage Tracking - Key usage monitoring

Security Features

Encryption Security

• AES-256-GCM - Industry standard encryption
• Scrypt KDF - Secure key derivation
• Random Nonces - Unique per encryption
• Authenticated Encryption - Tamper detection

Access Control

• Permission-Based - Fine-grained permissions
• Usage Limits - Maximum usage tracking
• Contract Restrictions - Allowed contract lists
• Transfer Limits - Maximum transfer amounts

Rate Limiting

• Per-Key Limits - Individual key rate limits
• Time-Based - Minute-based rate limiting
• Configurable - Adjustable rate limits

Audit Trail

• Comprehensive Logging - All security events logged
• Risk Scoring - Automated risk assessment
• Detailed Information - Rich audit data
• Persistent Storage - File-based audit logs

Key Management

• Automatic Generation - Default key generation
• Rotation Support - Secure key rotation
• Expiration Tracking - Automatic expiration
• Backup Creation - Encrypted key backups

Best Practices

Key Security

1. Use strong encryption keys
2. Regularly rotate keys
3. Monitor key usage
4. Implement usage limits
5. Use separate keys for different purposes

Transaction Security

1. Validate all transactions
2. Apply rate limiting
3. Check permissions
4. Log all signings
5. Monitor for anomalies

Audit Security

1. Log all security events
2. Calculate risk scores
3. Monitor audit logs
4. Retain logs appropriately
5. Protect audit file access

Backup Security

1. Create regular backups
2. Store backups securely
3. Encrypt backup data
4. Test backup recovery
5. Monitor backup integrity

Error Handling

Security Errors

• Invalid Keys - Key parsing failures
• Encryption Failures - Encryption/decryption errors
• Rate Limiting - Signing rate exceeded
• Permission Denied - Insufficient permissions
• Key Expired - Expired key usage

Recovery

• Automatic Key Generation - Recovers from no keys
• Backup Restoration - Key recovery from backups
• Graceful Degradation - Continues operation when possible
• Detailed Logging - Clear error information

Testing

Unit Tests

• Key generation and import
• Encryption and decryption
• Transaction signing
• Rate limiting
• Audit logging
• Backup creation

Integration Tests

• End-to-end key management
• Security workflow testing
• Performance under load
• Failure scenario handling

Future Improvements

Enhanced Security

1. Hardware security module (HSM) integration
2. Multi-signature support
3. Threshold signatures
4. Key sharding
5. Biometric authentication

Advanced Features

1. Key recovery mechanisms
2. Advanced audit analytics
3. Machine learning anomaly detection
4. Blockchain-based audit trails
5. Zero-knowledge proof integration