136 lines
2.8 KiB
Markdown
136 lines
2.8 KiB
Markdown
|
# Security Architecture
|
||
|
|
|
||
|
|
This document describes the security architecture of Crypto Trader.
|
||
|
|
|
||
|
|
## Security Layers
|
||
|
|
|
||
|
|
```
|
||
|
|
Application Layer
|
||
|
|
├──► API Key Encryption
|
||
|
|
├──► Permission Management
|
||
|
|
└──► Audit Logging
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
Storage Layer
|
||
|
|
├──► Encrypted Storage
|
||
|
|
└──► Secure Key Management
|
||
|
|
```
|
||
|
|
|
||
|
|
## API Key Encryption
|
||
|
|
|
||
|
|
### Encryption Process
|
||
|
|
|
||
|
|
```
|
||
|
|
Plain API Key
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
Fernet Encryption
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
Encrypted Key (Stored in Database)
|
||
|
|
```
|
||
|
|
|
||
|
|
### Key Management
|
||
|
|
|
||
|
|
- **Encryption Key**: Stored securely (environment variable or keyring)
|
||
|
|
- **Key Generation**: Automatic on first use
|
||
|
|
- **Key Rotation**: Manual rotation process
|
||
|
|
|
||
|
|
## Permission Management
|
||
|
|
|
||
|
|
### Permission Levels
|
||
|
|
|
||
|
|
- **Read-Only**: Data collection, backtesting only
|
||
|
|
- **Trading Enabled**: Full trading capabilities
|
||
|
|
|
||
|
|
### Permission Enforcement
|
||
|
|
|
||
|
|
```
|
||
|
|
API Request
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
Permission Check
|
||
|
|
│
|
||
|
|
├──► Read-Only Request
|
||
|
|
│ │
|
||
|
|
│ └──► Allow (read operations)
|
||
|
|
│
|
||
|
|
└──► Trading Request
|
||
|
|
│
|
||
|
|
├──► Trading Enabled?
|
||
|
|
│ │
|
||
|
|
│ ├──► Yes: Allow
|
||
|
|
│ └──► No: Reject
|
||
|
|
```
|
||
|
|
|
||
|
|
## Secure Storage
|
||
|
|
|
||
|
|
### Keyring Integration
|
||
|
|
|
||
|
|
- **Linux**: Secret Service (GNOME Keyring)
|
||
|
|
- **macOS**: Keychain
|
||
|
|
- **Windows**: Windows Credential Manager
|
||
|
|
|
||
|
|
### Fallback Storage
|
||
|
|
|
||
|
|
If keyring unavailable:
|
||
|
|
- Environment variable (development only)
|
||
|
|
- Encrypted file with user permission
|
||
|
|
|
||
|
|
## Audit Logging
|
||
|
|
|
||
|
|
All security events are logged:
|
||
|
|
|
||
|
|
- API key changes
|
||
|
|
- Permission changes
|
||
|
|
- Trading operations
|
||
|
|
- Configuration changes
|
||
|
|
- Error events
|
||
|
|
|
||
|
|
### Audit Log Format
|
||
|
|
|
||
|
|
```python
|
||
|
|
{
|
||
|
|
"timestamp": "2025-12-13T19:00:00Z",
|
||
|
|
"event_type": "API_KEY_CHANGED",
|
||
|
|
"user_id": "system",
|
||
|
|
"details": {
|
||
|
|
"exchange": "coinbase",
|
||
|
|
"action": "updated"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Data Privacy
|
||
|
|
|
||
|
|
- **Local Storage**: All data stored locally
|
||
|
|
- **No Telemetry**: No data sent externally
|
||
|
|
- **Encryption**: Sensitive data encrypted at rest
|
||
|
|
- **Access Control**: File system permissions
|
||
|
|
|
||
|
|
## Best Practices
|
||
|
|
|
||
|
|
1. **Use Read-Only Keys**: When possible, use read-only API keys
|
||
|
|
2. **IP Whitelisting**: Enable IP whitelisting on exchange accounts
|
||
|
|
3. **Regular Rotation**: Rotate API keys periodically
|
||
|
|
4. **Secure Environment**: Keep encryption keys secure
|
||
|
|
5. **Audit Review**: Regularly review audit logs
|
||
|
|
|
||
|
|
## Threat Model
|
||
|
|
|
||
|
|
### Threats Addressed
|
||
|
|
|
||
|
|
- **API Key Theft**: Encryption at rest
|
||
|
|
- **Unauthorized Trading**: Permission checks
|
||
|
|
- **Data Breach**: Local storage, encryption
|
||
|
|
- **Man-in-the-Middle**: HTTPS for API calls
|
||
|
|
- **Key Logging**: Secure keyring storage
|
||
|
|
|
||
|
|
### Security Boundaries
|
||
|
|
|
||
|
|
- **Application Boundary**: Application code
|
||
|
|
- **Storage Boundary**: Encrypted database
|
||
|
|
- **Network Boundary**: Secure API connections
|
||
|
|
- **System Boundary**: File system permissions
|
||
|
|
|