ETB/ETB-API/security/Documentations/API_DOCUMENTATION.md

# 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.