Updates

ETB-API/security/Documentations/ZERO_TRUST_ARCHITECTURE.md

@@ -0,0 +1,372 @@
+# Zero Trust Architecture Implementation
+
+## Overview
+
+The ETB-API security module now implements a comprehensive Zero Trust Architecture that goes beyond traditional perimeter-based security. This implementation provides context-aware, risk-based access control that continuously verifies and validates every access request.
+
+## Core Zero Trust Principles
+
+### 1. **Never Trust, Always Verify**
+- Every access request is evaluated regardless of source
+- Continuous verification of user identity and device trust
+- No implicit trust based on network location
+
+### 2. **Least Privilege Access**
+- Users receive minimum necessary access based on context
+- Dynamic permission adjustment based on risk assessment
+- Time-limited access with automatic expiration
+
+### 3. **Assume Breach**
+- Continuous monitoring and threat detection
+- Behavioral anomaly detection
+- Rapid response to security incidents
+
+## Zero Trust Components
+
+### 1. Device Posture Assessment
+
+**Purpose**: Evaluate the security posture of devices attempting to access the system.
+
+**Features**:
+- Device identification and fingerprinting
+- Security configuration assessment (antivirus, firewall, encryption)
+- Network type detection (corporate, home, public)
+- VPN connection status
+- Compliance verification
+- Risk scoring (0-100)
+
+**API Endpoints**:
+```http
+GET /security/api/device-postures/          # List user's devices
+POST /security/api/device-postures/         # Register new device
+POST /security/api/device-postures/{id}/update_posture/  # Update device info
+POST /security/api/device-postures/register_device/      # Register device
+```
+
+**Example Device Registration**:
+```json
+{
+  "device_id": "unique-device-identifier",
+  "device_name": "John's Laptop",
+  "device_type": "LAPTOP",
+  "os_type": "WINDOWS",
+  "os_version": "Windows 11",
+  "is_managed": true,
+  "has_antivirus": true,
+  "firewall_enabled": true,
+  "encryption_enabled": true,
+  "screen_lock_enabled": true,
+  "biometric_auth": true,
+  "network_type": "Corporate",
+  "vpn_connected": true
+}
+```
+
+### 2. Geolocation-Based Access Control
+
+**Purpose**: Control access based on geographic location and network context.
+
+**Features**:
+- Country, region, and city-based restrictions
+- IP range allow/block lists
+- Distance-based access control from office locations
+- Time zone and working hours restrictions
+- Risk-based location scoring
+
+**API Endpoints**:
+```http
+GET /security/api/geolocation-rules/        # List geolocation rules
+POST /security/api/geolocation-rules/       # Create new rule
+POST /security/api/geolocation-rules/{id}/test_rule/  # Test rule
+```
+
+**Example Geolocation Rule**:
+```json
+{
+  "name": "Bulgaria Office Access",
+  "rule_type": "ALLOW",
+  "allowed_countries": ["BG"],
+  "allowed_cities": ["Sofia", "Plovdiv", "Varna"],
+  "max_distance_from_office": 50.0,
+  "office_latitude": 42.6977,
+  "office_longitude": 23.3219,
+  "working_hours_only": true,
+  "working_hours_start": "08:00",
+  "working_hours_end": "18:00",
+  "working_days": [0, 1, 2, 3, 4]
+}
+```
+
+### 3. Risk Assessment Engine
+
+**Purpose**: Continuously assess risk for every access request using multiple factors.
+
+**Risk Factors**:
+- **Device Risk** (25%): Device security posture and compliance
+- **Location Risk** (20%): Geographic and network location
+- **Behavior Risk** (20%): User behavior patterns and anomalies
+- **Network Risk** (15%): Network security and VPN status
+- **Time Risk** (10%): Access time and working hours
+- **User Risk** (10%): User account status and history
+
+**Risk Levels**:
+- **LOW** (0-25): Normal access granted
+- **MEDIUM** (26-50): Step-up authentication required
+- **HIGH** (51-75): Manual review required
+- **CRITICAL** (76-100): Access denied
+
+**API Endpoints**:
+```http
+GET /security/api/risk-assessments/         # List user's assessments
+POST /security/api/risk-assessments/assess_access/  # Perform assessment
+GET /security/api/risk-assessments/my_risk_profile/  # Get risk profile
+```
+
+### 4. Adaptive Authentication
+
+**Purpose**: Dynamically adjust authentication requirements based on risk level.
+
+**Features**:
+- Risk-based authentication method selection
+- Context-aware risk adjustment
+- Behavioral analysis integration
+- Machine learning support (optional)
+- Fallback authentication methods
+
+**Authentication Methods**:
+- Password
+- MFA TOTP
+- MFA SMS/Email
+- Biometric
+- Hardware Token
+- SSO
+- Certificate
+
+**API Endpoints**:
+```http
+GET /security/api/adaptive-auth/            # List adaptive auth configs
+POST /security/api/adaptive-auth/{id}/test_auth_requirements/  # Test requirements
+```
+
+### 5. Behavioral Analysis
+
+**Purpose**: Learn and detect anomalous user behavior patterns.
+
+**Features**:
+- Login time and location patterns
+- Device usage patterns
+- Access frequency analysis
+- Session duration tracking
+- Anomaly scoring (0-1)
+
+**API Endpoints**:
+```http
+GET /security/api/behavior-profiles/        # List behavior profiles
+POST /security/api/behavior-profiles/{id}/calculate_anomaly/  # Calculate anomaly
+```
+
+## Zero Trust Middleware
+
+The system includes three middleware components that automatically apply Zero Trust principles:
+
+### 1. ZeroTrustMiddleware
+- Intercepts all requests
+- Performs risk assessment
+- Applies access policies
+- Updates behavior profiles
+
+### 2. DeviceRegistrationMiddleware
+- Handles device registration requests
+- Validates device information
+- Creates device posture records
+
+### 3. RiskBasedRateLimitMiddleware
+- Applies rate limiting based on risk level
+- Higher risk = stricter limits
+- Prevents abuse and brute force attacks
+
+## Configuration
+
+### Settings Configuration
+
+```python
+# Zero Trust Architecture Settings
+ZERO_TRUST_ENABLED = True
+ZERO_TRUST_STRICT_MODE = False  # Set to True for maximum security
+
+# Geolocation API Settings
+GEO_API_KEY = "your-api-key"  # Set your geolocation API key
+GEO_API_PROVIDER = 'ipapi'  # Options: 'ipapi', 'ipinfo', 'maxmind'
+
+# Device Posture Assessment
+DEVICE_POSTURE_ENABLED = True
+DEVICE_POSTURE_STRICT_MODE = False
+DEVICE_POSTURE_UPDATE_INTERVAL = 3600  # Update every hour
+
+# Risk Assessment Settings
+RISK_ASSESSMENT_ENABLED = True
+RISK_ASSESSMENT_CACHE_TTL = 300  # Cache for 5 minutes
+RISK_ASSESSMENT_ML_ENABLED = False  # Enable ML-based assessment
+
+# Behavioral Analysis Settings
+BEHAVIORAL_ANALYSIS_ENABLED = True
+BEHAVIORAL_LEARNING_PERIOD = 30  # Days to learn behavior
+BEHAVIORAL_ANOMALY_THRESHOLD = 0.7  # Anomaly threshold
+
+# Adaptive Authentication Settings
+ADAPTIVE_AUTH_ENABLED = True
+ADAPTIVE_AUTH_FALLBACK_METHODS = ['PASSWORD', 'MFA_TOTP']
+ADAPTIVE_AUTH_MAX_ATTEMPTS = 3
+ADAPTIVE_AUTH_LOCKOUT_DURATION = 15  # minutes
+```
+
+## API Usage Examples
+
+### 1. Check Zero Trust Status
+
+```bash
+curl -X GET "http://localhost:8000/security/api/zero-trust/status/" \
+  -H "Authorization: Token your-token"
+```
+
+**Response**:
+```json
+{
+  "zero_trust_enabled": true,
+  "user_status": {
+    "registered_devices": 2,
+    "trusted_devices": 1,
+    "latest_risk_level": "MEDIUM",
+    "latest_risk_score": 35
+  },
+  "system_configuration": {
+    "adaptive_auth_enabled": true,
+    "geolocation_rules_count": 3,
+    "behavioral_analysis_enabled": true,
+    "device_posture_enabled": true
+  },
+  "recommendations": [
+    {
+      "type": "device",
+      "priority": "medium",
+      "message": "1 untrusted devices detected",
+      "action": "improve_device_security"
+    }
+  ]
+}
+```
+
+### 2. Perform Risk Assessment
+
+```bash
+curl -X POST "http://localhost:8000/security/api/zero-trust/assess/" \
+  -H "Authorization: Token your-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "assessment_type": "ACCESS",
+    "resource_type": "incident",
+    "device_id": "device-123",
+    "location_data": {
+      "latitude": 42.6977,
+      "longitude": 23.3219,
+      "country_code": "BG",
+      "city": "Sofia"
+    }
+  }'
+```
+
+**Response**:
+```json
+{
+  "access_granted": true,
+  "reason": "Access granted - low risk",
+  "required_actions": [],
+  "risk_level": "LOW",
+  "risk_score": 25,
+  "auth_requirements": ["PASSWORD"],
+  "assessment_id": "uuid-here"
+}
+```
+
+### 3. Register Device
+
+```bash
+curl -X POST "http://localhost:8000/security/api/device-postures/register_device/" \
+  -H "Authorization: Token your-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "device_id": "unique-device-id",
+    "device_name": "My Laptop",
+    "device_type": "LAPTOP",
+    "os_type": "WINDOWS",
+    "is_managed": true,
+    "has_antivirus": true,
+    "firewall_enabled": true,
+    "encryption_enabled": true
+  }'
+```
+
+## Security Benefits
+
+### 1. **Enhanced Security Posture**
+- Continuous verification of all access requests
+- Context-aware access decisions
+- Reduced attack surface through least privilege
+
+### 2. **Improved Compliance**
+- Comprehensive audit trails
+- Risk-based access controls
+- Regulatory compliance support (GDPR, ISO 27001, SOC 2)
+
+### 3. **Better User Experience**
+- Adaptive authentication reduces friction for low-risk access
+- Transparent security controls
+- Self-service device registration
+
+### 4. **Operational Efficiency**
+- Automated risk assessment
+- Reduced manual security reviews
+- Proactive threat detection
+
+## Implementation Considerations
+
+### 1. **Performance**
+- Risk assessments are cached for 5 minutes
+- Geolocation lookups are optimized
+- Database queries are indexed for performance
+
+### 2. **Scalability**
+- Middleware can be disabled for high-traffic scenarios
+- Risk assessment can be moved to background tasks
+- Caching strategies for large-scale deployments
+
+### 3. **Privacy**
+- User behavior data is anonymized
+- Geolocation data is not stored permanently
+- Compliance with data protection regulations
+
+### 4. **Monitoring**
+- Comprehensive audit logging
+- Risk assessment metrics
+- Security event correlation
+
+## Future Enhancements
+
+### 1. **Machine Learning Integration**
+- ML-based risk scoring
+- Behavioral pattern recognition
+- Predictive threat detection
+
+### 2. **Advanced Analytics**
+- Risk trend analysis
+- Security posture dashboards
+- Compliance reporting
+
+### 3. **Integration Capabilities**
+- SIEM integration
+- Threat intelligence feeds
+- External security tools
+
+## Conclusion
+
+The Zero Trust Architecture implementation provides a robust, scalable, and comprehensive security framework that continuously adapts to changing threat landscapes while maintaining usability and compliance requirements. This implementation positions the ETB-API as a leader in enterprise security architecture.