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.