chore(security): enhance environment configuration, CI workflows, and wallet daemon with security improvements
- Restructure .env.example with security-focused documentation, service-specific environment file references, and AWS Secrets Manager integration - Update CLI tests workflow to single Python 3.13 version, add pytest-mock dependency, and consolidate test execution with coverage - Add comprehensive security validation to package publishing workflow with manual approval gates, secret scanning, and release
This commit is contained in:
oib
379
docs/policies/CLI_TRANSLATION_SECURITY_POLICY.md
Normal file
379
docs/policies/CLI_TRANSLATION_SECURITY_POLICY.md
Normal file
@@ -0,0 +1,379 @@
|
||||
# AITBC CLI Translation Security Policy
|
||||
|
||||
## 🔐 Security Overview
|
||||
|
||||
This document outlines the comprehensive security policy for CLI translation functionality in the AITBC platform, ensuring that translation services never compromise security-sensitive operations.
|
||||
|
||||
## ⚠️ Security Problem Statement
|
||||
|
||||
### Identified Risks
|
||||
1. **API Dependency**: Translation services rely on external APIs (OpenAI, Google, DeepL)
|
||||
2. **Network Failures**: Translation unavailable during network outages
|
||||
3. **Data Privacy**: Sensitive command data sent to third-party services
|
||||
4. **Command Injection**: Risk of translated commands altering security context
|
||||
5. **Performance Impact**: Translation delays critical operations
|
||||
6. **Audit Trail**: Loss of original command intent in translation
|
||||
|
||||
### Security-Sensitive Operations
|
||||
- **Agent Strategy Commands**: `aitbc agent strategy --aggressive`
|
||||
- **Wallet Operations**: `aitbc wallet send --to 0x... --amount 100`
|
||||
- **Deployment Commands**: `aitbc deploy --production`
|
||||
- **Signing Operations**: `aitbc sign --message "approve transfer"`
|
||||
- **Genesis Operations**: `aitbc genesis init --network mainnet`
|
||||
|
||||
## 🛡️ Security Framework
|
||||
|
||||
### Security Levels
|
||||
|
||||
#### 🔴 CRITICAL (Translation Disabled)
|
||||
**Commands**: `agent`, `strategy`, `wallet`, `sign`, `deploy`, `genesis`, `transfer`, `send`, `approve`, `mint`, `burn`, `stake`
|
||||
|
||||
**Policy**:
|
||||
- ✅ Translation: **DISABLED**
|
||||
- ✅ External APIs: **BLOCKED**
|
||||
- ✅ User Consent: **REQUIRED**
|
||||
- ✅ Fallback: **Original text only**
|
||||
|
||||
**Rationale**: These commands handle sensitive operations where translation could compromise security or financial transactions.
|
||||
|
||||
#### 🟠 HIGH (Local Translation Only)
|
||||
**Commands**: `config`, `node`, `chain`, `marketplace`, `swap`, `liquidity`, `governance`, `vote`, `proposal`
|
||||
|
||||
**Policy**:
|
||||
- ✅ Translation: **LOCAL ONLY**
|
||||
- ✅ External APIs: **BLOCKED**
|
||||
- ✅ User Consent: **REQUIRED**
|
||||
- ✅ Fallback: **Local dictionary**
|
||||
|
||||
**Rationale**: Important operations that benefit from localization but don't require external services.
|
||||
|
||||
#### 🟡 MEDIUM (Fallback Mode)
|
||||
**Commands**: `balance`, `status`, `monitor`, `analytics`, `logs`, `history`, `simulate`, `test`
|
||||
|
||||
**Policy**:
|
||||
- ✅ Translation: **EXTERNAL WITH LOCAL FALLBACK**
|
||||
- ✅ External APIs: **ALLOWED**
|
||||
- ✅ User Consent: **NOT REQUIRED**
|
||||
- ✅ Fallback: **Local translation on failure**
|
||||
|
||||
**Rationale**: Standard operations where translation enhances user experience but isn't critical.
|
||||
|
||||
#### 🟢 LOW (Full Translation)
|
||||
**Commands**: `help`, `version`, `info`, `list`, `show`, `explain`
|
||||
|
||||
**Policy**:
|
||||
- ✅ Translation: **FULL CAPABILITIES**
|
||||
- ✅ External APIs: **ALLOWED**
|
||||
- ✅ User Consent: **NOT REQUIRED**
|
||||
- ✅ Fallback: **External retry then local**
|
||||
|
||||
**Rationale**: Informational commands where translation improves accessibility without security impact.
|
||||
|
||||
## 🔧 Implementation Details
|
||||
|
||||
### Security Manager Architecture
|
||||
|
||||
```python
|
||||
# Security enforcement flow
|
||||
async def translate_with_security(request):
|
||||
1. Determine command security level
|
||||
2. Apply security policy
|
||||
3. Check user consent requirements
|
||||
4. Execute translation based on policy
|
||||
5. Log security check for audit
|
||||
6. Return with security metadata
|
||||
```
|
||||
|
||||
### Policy Configuration
|
||||
|
||||
```python
|
||||
# Default security policies
|
||||
CRITICAL_POLICY = {
|
||||
"translation_mode": "DISABLED",
|
||||
"allow_external_apis": False,
|
||||
"require_explicit_consent": True,
|
||||
"timeout_seconds": 0,
|
||||
"max_retries": 0
|
||||
}
|
||||
|
||||
HIGH_POLICY = {
|
||||
"translation_mode": "LOCAL_ONLY",
|
||||
"allow_external_apis": False,
|
||||
"require_explicit_consent": True,
|
||||
"timeout_seconds": 5,
|
||||
"max_retries": 1
|
||||
}
|
||||
```
|
||||
|
||||
### Local Translation System
|
||||
|
||||
For security-sensitive operations, a local translation system provides basic localization:
|
||||
|
||||
```python
|
||||
LOCAL_TRANSLATIONS = {
|
||||
"help": {"es": "ayuda", "fr": "aide", "de": "hilfe", "zh": "帮助"},
|
||||
"error": {"es": "error", "fr": "erreur", "de": "fehler", "zh": "错误"},
|
||||
"success": {"es": "éxito", "fr": "succès", "de": "erfolg", "zh": "成功"},
|
||||
"wallet": {"es": "cartera", "fr": "portefeuille", "de": "börse", "zh": "钱包"},
|
||||
"transaction": {"es": "transacción", "fr": "transaction", "de": "transaktion", "zh": "交易"}
|
||||
}
|
||||
```
|
||||
|
||||
## 🚨 Security Controls
|
||||
|
||||
### 1. Command Classification System
|
||||
|
||||
```python
|
||||
def get_command_security_level(command_name: str) -> SecurityLevel:
|
||||
critical_commands = {'agent', 'strategy', 'wallet', 'sign', 'deploy'}
|
||||
high_commands = {'config', 'node', 'chain', 'marketplace', 'swap'}
|
||||
medium_commands = {'balance', 'status', 'monitor', 'analytics'}
|
||||
low_commands = {'help', 'version', 'info', 'list', 'show'}
|
||||
|
||||
# Return appropriate security level
|
||||
```
|
||||
|
||||
### 2. API Access Control
|
||||
|
||||
```python
|
||||
# External API blocking for critical operations
|
||||
if security_level == SecurityLevel.CRITICAL:
|
||||
raise SecurityException("External APIs blocked for critical operations")
|
||||
|
||||
# Timeout enforcement for external calls
|
||||
if policy.allow_external_apis:
|
||||
result = await asyncio.wait_for(
|
||||
external_translate(request),
|
||||
timeout=policy.timeout_seconds
|
||||
)
|
||||
```
|
||||
|
||||
### 3. Fallback Mechanisms
|
||||
|
||||
```python
|
||||
async def translate_with_fallback(request):
|
||||
try:
|
||||
# Try external translation first
|
||||
return await external_translate(request)
|
||||
except (TimeoutError, NetworkError, APIError):
|
||||
# Fallback to local translation
|
||||
return await local_translate(request)
|
||||
except Exception:
|
||||
# Ultimate fallback: return original text
|
||||
return request.original_text
|
||||
```
|
||||
|
||||
### 4. Audit Logging
|
||||
|
||||
```python
|
||||
def log_security_check(request, policy):
|
||||
log_entry = {
|
||||
"timestamp": datetime.utcnow().isoformat(),
|
||||
"command": request.command_name,
|
||||
"security_level": request.security_level.value,
|
||||
"translation_mode": policy.translation_mode.value,
|
||||
"target_language": request.target_language,
|
||||
"user_consent": request.user_consent,
|
||||
"text_length": len(request.text)
|
||||
}
|
||||
security_audit_log.append(log_entry)
|
||||
```
|
||||
|
||||
## 📋 Usage Examples
|
||||
|
||||
### Security-Compliant Translation
|
||||
|
||||
```python
|
||||
from aitbc_cli.security import cli_translation_security, TranslationRequest
|
||||
|
||||
# Critical command - translation disabled
|
||||
request = TranslationRequest(
|
||||
text="Transfer 100 AITBC to 0x1234...",
|
||||
target_language="es",
|
||||
command_name="transfer",
|
||||
security_level=SecurityLevel.CRITICAL
|
||||
)
|
||||
|
||||
response = await cli_translation_security.translate_with_security(request)
|
||||
# Result: Original text returned, translation disabled
|
||||
```
|
||||
|
||||
### Medium Security Command
|
||||
|
||||
```python
|
||||
# Status command - fallback mode allowed
|
||||
request = TranslationRequest(
|
||||
text="Current balance: 1000 AITBC",
|
||||
target_language="fr",
|
||||
command_name="balance",
|
||||
security_level=SecurityLevel.MEDIUM
|
||||
)
|
||||
|
||||
response = await cli_translation_security.translate_with_security(request)
|
||||
# Result: Translated with external API, local fallback on failure
|
||||
```
|
||||
|
||||
### Local Translation Only
|
||||
|
||||
```python
|
||||
# Configuration command - local only
|
||||
request = TranslationRequest(
|
||||
text="Node configuration updated",
|
||||
target_language="de",
|
||||
command_name="config",
|
||||
security_level=SecurityLevel.HIGH
|
||||
)
|
||||
|
||||
response = await cli_translation_security.translate_with_security(request)
|
||||
# Result: Local dictionary translation only
|
||||
```
|
||||
|
||||
## 🔍 Security Monitoring
|
||||
|
||||
### Security Report Generation
|
||||
|
||||
```python
|
||||
from aitbc_cli.security import get_translation_security_report
|
||||
|
||||
report = get_translation_security_report()
|
||||
print(f"Total security checks: {report['security_summary']['total_checks']}")
|
||||
print(f"Critical operations: {report['security_summary']['by_security_level']['critical']}")
|
||||
print(f"Recommendations: {report['recommendations']}")
|
||||
```
|
||||
|
||||
### Real-time Monitoring
|
||||
|
||||
```python
|
||||
# Monitor translation security in real-time
|
||||
def monitor_translation_security():
|
||||
summary = cli_translation_security.get_security_summary()
|
||||
|
||||
# Alert on suspicious patterns
|
||||
if summary['by_security_level'].get('critical', 0) > 0:
|
||||
send_security_alert("Critical command translation attempts detected")
|
||||
|
||||
# Monitor failure rates
|
||||
recent_failures = [log for log in summary['recent_checks']
|
||||
if log.get('translation_failed', False)]
|
||||
|
||||
if len(recent_failures) > 5: # Threshold
|
||||
send_security_alert("High translation failure rate detected")
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Security policy configuration
|
||||
AITBC_TRANSLATION_SECURITY_LEVEL="medium" # Global security level
|
||||
AITBC_TRANSLATION_EXTERNAL_APIS="false" # Block external APIs
|
||||
AITBC_TRANSLATION_TIMEOUT="10" # API timeout in seconds
|
||||
AITBC_TRANSLATION_AUDIT="true" # Enable audit logging
|
||||
```
|
||||
|
||||
### Configuration File
|
||||
|
||||
```json
|
||||
{
|
||||
"translation_security": {
|
||||
"critical_level": "disabled",
|
||||
"high_level": "local_only",
|
||||
"medium_level": "fallback",
|
||||
"low_level": "full",
|
||||
"audit_logging": true,
|
||||
"max_audit_entries": 1000
|
||||
},
|
||||
"external_apis": {
|
||||
"timeout_seconds": 10,
|
||||
"max_retries": 3,
|
||||
"cache_enabled": true,
|
||||
"cache_ttl": 3600
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🚨 Incident Response
|
||||
|
||||
### Translation Service Outage
|
||||
|
||||
```python
|
||||
# Automatic fallback during service outage
|
||||
async def handle_translation_outage():
|
||||
# Temporarily disable external APIs
|
||||
configure_translation_security(
|
||||
critical_level="disabled",
|
||||
high_level="local_only",
|
||||
medium_level="local_only", # Downgrade from fallback
|
||||
low_level="local_only" # Downgrade from full
|
||||
)
|
||||
|
||||
# Log security policy change
|
||||
log_security_incident("Translation outage - external APIs disabled")
|
||||
```
|
||||
|
||||
### Security Incident Response
|
||||
|
||||
```python
|
||||
def handle_security_incident(incident_type: str):
|
||||
if incident_type == "suspicious_translation_activity":
|
||||
# Disable translation for sensitive operations
|
||||
configure_translation_security(
|
||||
critical_level="disabled",
|
||||
high_level="disabled",
|
||||
medium_level="local_only",
|
||||
low_level="fallback"
|
||||
)
|
||||
|
||||
# Trigger security review
|
||||
trigger_security_review()
|
||||
```
|
||||
|
||||
## 📊 Security Metrics
|
||||
|
||||
### Key Performance Indicators
|
||||
|
||||
- **Translation Success Rate**: Percentage of successful translations by security level
|
||||
- **Fallback Usage Rate**: How often local fallback is used
|
||||
- **API Response Time**: External API performance metrics
|
||||
- **Security Violations**: Attempts to bypass security policies
|
||||
- **User Consent Rate**: How often users grant consent for translation
|
||||
|
||||
### Monitoring Dashboard
|
||||
|
||||
```python
|
||||
def get_security_metrics():
|
||||
return {
|
||||
"translation_success_rate": calculate_success_rate(),
|
||||
"fallback_usage_rate": calculate_fallback_rate(),
|
||||
"api_response_times": get_api_metrics(),
|
||||
"security_violations": count_violations(),
|
||||
"user_consent_rate": calculate_consent_rate()
|
||||
}
|
||||
```
|
||||
|
||||
## 🔮 Future Enhancements
|
||||
|
||||
### Planned Security Features
|
||||
|
||||
1. **Machine Learning Detection**: AI-powered detection of sensitive command patterns
|
||||
2. **Dynamic Policy Adjustment**: Automatic security level adjustment based on context
|
||||
3. **Zero-Knowledge Translation**: Privacy-preserving translation protocols
|
||||
4. **Blockchain Auditing**: Immutable audit trail on blockchain
|
||||
5. **Multi-Factor Authentication**: Additional security for sensitive translations
|
||||
|
||||
### Research Areas
|
||||
|
||||
1. **Federated Learning**: Local translation models without external dependencies
|
||||
2. **Quantum-Resistant Security**: Future-proofing against quantum computing threats
|
||||
3. **Behavioral Analysis**: User behavior patterns for anomaly detection
|
||||
4. **Cross-Platform Security**: Consistent security across all CLI platforms
|
||||
|
||||
---
|
||||
|
||||
**Security Policy Status**: ✅ **IMPLEMENTED**
|
||||
**Last Updated**: March 3, 2026
|
||||
**Next Review**: March 17, 2026
|
||||
**Security Level**: 🔒 **HIGH** - Comprehensive protection for sensitive operations
|
||||
|
||||
This security policy ensures that CLI translation functionality never compromises security-sensitive operations while providing appropriate localization capabilities for non-critical commands.
|
||||
Reference in New Issue
Block a user