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

POST /security/api/auth/login/
Content-Type: application/json

{
    "username": "admin",
    "password": "admin123",
    "mfa_token": "123456"  # Optional, required if MFA is enabled
}

Response:

{
    "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

POST /security/api/auth/login/

Logout

POST /security/api/auth/logout/
Authorization: Token your-token-here

User Profile

GET /security/api/auth/profile/
Authorization: Token your-token-here

Change Password

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

GET /security/api/auth/mfa-status/
Authorization: Token your-token-here

Data Classification Management

List Classifications

GET /security/api/classifications/
Authorization: Token your-token-here

Create Classification

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

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

DELETE /security/api/classifications/{id}/
Authorization: Token your-token-here

Role Management

List Roles

GET /security/api/roles/
Authorization: Token your-token-here

Create Role

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

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

GET /security/api/users/
Authorization: Token your-token-here

Create User

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

POST /security/api/users/{id}/lock_account/
Authorization: Token your-token-here
Content-Type: application/json

{
    "duration_minutes": 30
}

Unlock User Account

POST /security/api/users/{id}/unlock_account/
Authorization: Token your-token-here

Multi-Factor Authentication (MFA)

List MFA Devices

GET /security/api/mfa-devices/
Authorization: Token your-token-here

Setup TOTP Device

POST /security/api/mfa-devices/setup_totp/
Authorization: Token your-token-here
Content-Type: application/json

{
    "device_name": "My Phone",
    "device_type": "TOTP"
}

Response:

{
    "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

POST /security/api/mfa-devices/{id}/verify_totp/
Authorization: Token your-token-here
Content-Type: application/json

{
    "token": "123456"
}

Enable MFA

POST /security/api/mfa-devices/enable_mfa/
Authorization: Token your-token-here

Disable MFA

POST /security/api/mfa-devices/disable_mfa/
Authorization: Token your-token-here

Audit Logs

List Audit Logs

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:

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

GET /security/api/sso-providers/
Authorization: Token your-token-here

Create SSO Provider

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

GET /security/api/access-policies/
Authorization: Token your-token-here

Create Access Policy

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:

{
    "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:

   python manage.py runserver
   

2. Access the admin interface:

   http://localhost:8000/admin/
   Username: admin
   Password: admin123
   

3. Test the API:

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