Updates

ETB-API/security/Documentations/API_DOCUMENTATION.md

@@ -0,0 +1,468 @@
+# Enterprise Incident Management API - Security Module
+
+## Overview
+
+This API provides advanced security features for enterprise incident management, including:
+
+- **Single Sign-On (SSO)** with SAML, LDAP, OAuth2, and OIDC support
+- **Multi-Factor Authentication (MFA)** with TOTP support
+- **Role-Based Access Control (RBAC)** and Attribute-Based Access Control (ABAC)
+- **Immutable Audit Trails** with integrity verification
+- **Data Classification** system with 5 security levels
+
+## Base URL
+
+```
+http://localhost:8000/security/
+```
+
+## Authentication
+
+The API supports multiple authentication methods:
+
+1. **Token Authentication** (Primary)
+2. **Session Authentication** (Web interface)
+3. **SSO Authentication** (SAML, OAuth2, LDAP)
+
+### Getting an Authentication Token
+
+```bash
+POST /security/api/auth/login/
+Content-Type: application/json
+
+{
+    "username": "admin",
+    "password": "admin123",
+    "mfa_token": "123456"  # Optional, required if MFA is enabled
+}
+```
+
+**Response:**
+```json
+{
+    "token": "your-auth-token-here",
+    "user": {
+        "id": "uuid",
+        "username": "admin",
+        "email": "admin@example.com",
+        "mfa_enabled": false,
+        "clearance_level": {
+            "name": "TOP_SECRET",
+            "level": 5
+        }
+    },
+    "message": "Login successful"
+}
+```
+
+## API Endpoints
+
+### Authentication Endpoints
+
+#### Login
+```http
+POST /security/api/auth/login/
+```
+
+#### Logout
+```http
+POST /security/api/auth/logout/
+Authorization: Token your-token-here
+```
+
+#### User Profile
+```http
+GET /security/api/auth/profile/
+Authorization: Token your-token-here
+```
+
+#### Change Password
+```http
+POST /security/api/auth/change-password/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "current_password": "old-password",
+    "new_password": "new-password",
+    "confirm_password": "new-password"
+}
+```
+
+#### MFA Status
+```http
+GET /security/api/auth/mfa-status/
+Authorization: Token your-token-here
+```
+
+### Data Classification Management
+
+#### List Classifications
+```http
+GET /security/api/classifications/
+Authorization: Token your-token-here
+```
+
+#### Create Classification
+```http
+POST /security/api/classifications/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "name": "CUSTOM",
+    "level": 6,
+    "description": "Custom classification level",
+    "color_code": "#ff0000",
+    "requires_clearance": true
+}
+```
+
+#### Update Classification
+```http
+PUT /security/api/classifications/{id}/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "name": "CUSTOM",
+    "level": 6,
+    "description": "Updated description",
+    "color_code": "#ff0000",
+    "requires_clearance": true
+}
+```
+
+#### Delete Classification
+```http
+DELETE /security/api/classifications/{id}/
+Authorization: Token your-token-here
+```
+
+### Role Management
+
+#### List Roles
+```http
+GET /security/api/roles/
+Authorization: Token your-token-here
+```
+
+#### Create Role
+```http
+POST /security/api/roles/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "name": "Incident Responder",
+    "description": "Can respond to and manage incidents",
+    "permission_ids": [1, 2, 3],
+    "classification_ids": [1, 2, 3],
+    "is_active": true
+}
+```
+
+#### Update Role
+```http
+PUT /security/api/roles/{id}/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "name": "Senior Incident Responder",
+    "description": "Can respond to and manage high-priority incidents",
+    "permission_ids": [1, 2, 3, 4],
+    "classification_ids": [1, 2, 3, 4],
+    "is_active": true
+}
+```
+
+### User Management
+
+#### List Users
+```http
+GET /security/api/users/
+Authorization: Token your-token-here
+```
+
+#### Create User
+```http
+POST /security/api/users/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "username": "newuser",
+    "email": "user@example.com",
+    "first_name": "John",
+    "last_name": "Doe",
+    "password": "secure-password",
+    "employee_id": "EMP001",
+    "department": "IT Security",
+    "clearance_level_id": 3,
+    "role_ids": [1, 2],
+    "is_active": true
+}
+```
+
+#### Lock User Account
+```http
+POST /security/api/users/{id}/lock_account/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "duration_minutes": 30
+}
+```
+
+#### Unlock User Account
+```http
+POST /security/api/users/{id}/unlock_account/
+Authorization: Token your-token-here
+```
+
+### Multi-Factor Authentication (MFA)
+
+#### List MFA Devices
+```http
+GET /security/api/mfa-devices/
+Authorization: Token your-token-here
+```
+
+#### Setup TOTP Device
+```http
+POST /security/api/mfa-devices/setup_totp/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "device_name": "My Phone",
+    "device_type": "TOTP"
+}
+```
+
+**Response:**
+```json
+{
+    "device_id": "uuid",
+    "qr_code_data": "otpauth://totp/...",
+    "qr_code_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
+    "message": "TOTP device created. Scan QR code with authenticator app."
+}
+```
+
+#### Verify TOTP Token
+```http
+POST /security/api/mfa-devices/{id}/verify_totp/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "token": "123456"
+}
+```
+
+#### Enable MFA
+```http
+POST /security/api/mfa-devices/enable_mfa/
+Authorization: Token your-token-here
+```
+
+#### Disable MFA
+```http
+POST /security/api/mfa-devices/disable_mfa/
+Authorization: Token your-token-here
+```
+
+### Audit Logs
+
+#### List Audit Logs
+```http
+GET /security/api/audit-logs/
+Authorization: Token your-token-here
+```
+
+**Query Parameters:**
+- `start_date`: Filter logs from this date (YYYY-MM-DD)
+- `end_date`: Filter logs until this date (YYYY-MM-DD)
+- `action_type`: Filter by action type (LOGIN, LOGOUT, etc.)
+- `severity`: Filter by severity (LOW, MEDIUM, HIGH, CRITICAL)
+- `user_id`: Filter by user ID
+
+**Example:**
+```http
+GET /security/api/audit-logs/?start_date=2024-01-01&severity=HIGH&action_type=LOGIN_FAILED
+Authorization: Token your-token-here
+```
+
+### SSO Provider Management
+
+#### List SSO Providers
+```http
+GET /security/api/sso-providers/
+Authorization: Token your-token-here
+```
+
+#### Create SSO Provider
+```http
+POST /security/api/sso-providers/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "name": "Company SAML",
+    "provider_type": "SAML",
+    "is_active": true,
+    "configuration": {
+        "entity_id": "https://company.com/saml",
+        "sso_url": "https://company.com/saml/sso",
+        "x509_cert": "-----BEGIN CERTIFICATE-----..."
+    },
+    "attribute_mapping": {
+        "username": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+        "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
+    }
+}
+```
+
+### Access Policy Management
+
+#### List Access Policies
+```http
+GET /security/api/access-policies/
+Authorization: Token your-token-here
+```
+
+#### Create Access Policy
+```http
+POST /security/api/access-policies/
+Authorization: Token your-token-here
+Content-Type: application/json
+
+{
+    "name": "High Security Access",
+    "description": "Allow access to high-security incidents only for senior staff",
+    "policy_type": "ALLOW",
+    "conditions": {
+        "user_clearance_level": {"gte": 4},
+        "user_roles": {"contains": "Security Admin"},
+        "time_of_day": {"between": [9, 17]}
+    },
+    "resource_type": "incident",
+    "actions": ["view", "edit"],
+    "priority": 10,
+    "is_active": true
+}
+```
+
+## Data Classification Levels
+
+The system includes 5 predefined classification levels:
+
+1. **PUBLIC** (Level 1) - Public information
+2. **INTERNAL** (Level 2) - Internal company information
+3. **CONFIDENTIAL** (Level 3) - Confidential information
+4. **RESTRICTED** (Level 4) - Restricted information
+5. **TOP_SECRET** (Level 5) - Top secret information
+
+## Security Features
+
+### Immutable Audit Trails
+
+All security-relevant actions are logged with:
+- SHA-256 hash for integrity verification
+- Timestamp and user information
+- IP address and user agent
+- Action details and severity level
+- Immutable records (cannot be modified or deleted)
+
+### Role-Based Access Control (RBAC)
+
+- Users can have multiple roles
+- Roles contain permissions and data classification access
+- Permissions are inherited from roles
+- Data access is controlled by clearance levels
+
+### Multi-Factor Authentication (MFA)
+
+- TOTP (Time-based One-Time Password) support
+- QR code generation for easy setup
+- Multiple devices per user
+- Primary device designation
+
+### Single Sign-On (SSO)
+
+- SAML 2.0 support
+- OAuth2/OIDC support (Google, Microsoft)
+- LDAP authentication
+- Configurable attribute mapping
+
+## Error Handling
+
+The API returns standard HTTP status codes:
+
+- `200 OK` - Success
+- `201 Created` - Resource created
+- `400 Bad Request` - Invalid request data
+- `401 Unauthorized` - Authentication required
+- `403 Forbidden` - Insufficient permissions
+- `404 Not Found` - Resource not found
+- `423 Locked` - Account locked
+- `500 Internal Server Error` - Server error
+
+Error responses include detailed error messages:
+
+```json
+{
+    "error": "Invalid credentials",
+    "details": "Username or password is incorrect"
+}
+```
+
+## Rate Limiting
+
+The API implements rate limiting for security endpoints:
+- Login attempts: 5 per minute per IP
+- MFA verification: 10 per minute per user
+- Password changes: 3 per hour per user
+
+## Getting Started
+
+1. **Start the development server:**
+   ```bash
+   python manage.py runserver
+   ```
+
+2. **Access the admin interface:**
+   ```
+   http://localhost:8000/admin/
+   Username: admin
+   Password: admin123
+   ```
+
+3. **Test the API:**
+   ```bash
+   # Login
+   curl -X POST http://localhost:8000/security/api/auth/login/ \
+     -H "Content-Type: application/json" \
+     -d '{"username": "admin", "password": "admin123"}'
+   
+   # Get user profile
+   curl -X GET http://localhost:8000/security/api/auth/profile/ \
+     -H "Authorization: Token your-token-here"
+   ```
+
+## Security Best Practices
+
+1. **Change default passwords** immediately
+2. **Enable MFA** for all administrative accounts
+3. **Configure SSO** for production environments
+4. **Regular audit log review** for security events
+5. **Implement proper data classification** for all resources
+6. **Use HTTPS** in production
+7. **Regular security updates** and patches
+
+## Support
+
+For technical support or security concerns, contact the security team at security@etb-incident-management.com.

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.