Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
762 lines (652 loc) · 13.5 KB

API_DOCUMENTATION.md

File metadata and controls

762 lines (652 loc) · 13.5 KB
Raw

API DOCUMENTATION

Complete API Reference for Insider Threat Detection System

Base URL

Development:  http://localhost:5000
Production:   https://api.insider-threat.example.com

Authentication

All endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer <jwt_token>

Response Format

All responses are JSON:

{
  "status": "success|error",
  "code": 200,
  "data": {},
  "message": "Human readable message"
}

TABLE OF CONTENTS

  1. Authentication Endpoints
  2. Incident Management
  3. Evidence Management
  4. Analytics & Reporting
  5. User Management
  6. System Administration
  7. Error Codes
  8. Rate Limiting
  9. Webhooks

AUTHENTICATION ENDPOINTS

POST /api/auth/login

Authenticate user with email and password

Request:

{
  "email": "admin@example.com",
  "password": "SecurePassword123!"
}

Response (200):

{
  "status": "success",
  "code": 200,
  "data": {
    "user": {
      "id": "user-001",
      "email": "admin@example.com",
      "name": "Admin User",
      "role": "admin",
      "mfaEnabled": true
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "mfaRequired": true
  }
}

Error (401):

{
  "status": "error",
  "code": 401,
  "error": "InvalidCredentials",
  "message": "Email or password is incorrect"
}

POST /api/auth/verify-mfa

Verify MFA code

Request:

{
  "code": "123456"
}

Response (200):

{
  "status": "success",
  "code": 200,
  "data": {
    "user": { /* user object */ },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

GET /api/auth/me

Get current authenticated user

Response (200):

{
  "status": "success",
  "data": {
    "user": {
      "id": "user-001",
      "email": "admin@example.com",
      "name": "Admin User",
      "role": "admin",
      "mfaEnabled": true,
      "createdAt": "2026-01-01T00:00:00Z",
      "lastLogin": "2026-01-22T10:30:00Z"
    }
  }
}

POST /api/auth/logout

Logout current user

Response (200):

{
  "status": "success",
  "message": "Successfully logged out"
}

INCIDENT MANAGEMENT

GET /api/incidents

List all incidents with pagination and filtering

Query Parameters:

  • page (int): Page number (default: 1)
  • limit (int): Items per page (default: 10, max: 100)
  • status (string): Filter by status (new, investigating, resolved, closed)
  • riskLevel (string): Filter by risk (critical, high, medium, low)
  • search (string): Search incidents by title/description
  • sortBy (string): Sort field (createdAt, riskLevel, status)
  • sortOrder (string): asc or desc

Example:

GET /api/incidents?page=1&limit=10&status=investigating&sortBy=riskLevel&sortOrder=desc

Response (200):

{
  "status": "success",
  "data": {
    "incidents": [
      {
        "id": "inc-001",
        "title": "Suspicious File Transfer",
        "description": "User transferred 2GB of data to external USB",
        "userId": "user-001",
        "riskLevel": "critical",
        "status": "investigating",
        "evidenceCount": 5,
        "createdAt": "2026-01-20T14:30:00Z",
        "updatedAt": "2026-01-22T10:15:00Z",
        "createdBy": "system",
        "assignedTo": "analyst-001"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "totalCount": 45,
      "totalPages": 5
    }
  }
}

GET /api/incidents/{incidentId}

Get incident details

Response (200):

{
  "status": "success",
  "data": {
    "incident": {
      "id": "inc-001",
      "title": "Suspicious File Transfer",
      "description": "Detailed description",
      "userId": "user-001",
      "riskLevel": "critical",
      "status": "investigating",
      "timeline": [
        {
          "timestamp": "2026-01-20T14:30:00Z",
          "event": "File transfer detected",
          "details": "2GB data"
        }
      ],
      "evidence": [
        {
          "id": "ev-001",
          "filename": "transfer_log.txt",
          "fileHash": "abc123..."
        }
      ],
      "relatedIncidents": ["inc-002"],
      "riskScore": 95,
      "createdAt": "2026-01-20T14:30:00Z"
    }
  }
}

POST /api/incidents

Create new incident

Request:

{
  "title": "Suspicious Activity Detected",
  "description": "Description of suspicious activity",
  "userId": "user-001",
  "riskLevel": "high",
  "tags": ["malware", "suspicious"]
}

Response (201):

{
  "status": "success",
  "code": 201,
  "data": {
    "incident": {
      "id": "inc-999",
      "title": "Suspicious Activity Detected",
      "status": "new",
      "createdAt": "2026-01-22T10:30:00Z"
    }
  }
}

PUT /api/incidents/{incidentId}

Update incident

Request:

{
  "status": "resolved",
  "notes": "Investigation complete, user educated",
  "resolution": "User was unaware of policy violation"
}

Response (200):

{
  "status": "success",
  "data": {
    "incident": { /* updated incident */ }
  }
}

DELETE /api/incidents/{incidentId}

Delete incident (Admin only)

Response (204): No content

EVIDENCE MANAGEMENT

GET /api/evidence

List all evidence items

Query Parameters:

  • page (int): Page number
  • limit (int): Items per page
  • incidentId (string): Filter by incident

Response (200):

{
  "status": "success",
  "data": {
    "evidence": [
      {
        "id": "ev-001",
        "filename": "suspicious_log.txt",
        "fileSize": 2048,
        "fileHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "hashAlgorithm": "sha256",
        "incidentId": "inc-001",
        "collectedBy": "system",
        "collectionTimestamp": "2026-01-20T14:35:00Z",
        "status": "verified",
        "tags": ["critical", "file"]
      }
    ],
    "totalCount": 12
  }
}

GET /api/evidence/{evidenceId}

Get evidence details with chain of custody

Response (200):

{
  "status": "success",
  "data": {
    "evidence": {
      "id": "ev-001",
      "filename": "suspicious_log.txt",
      "fileSize": 2048,
      "fileHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "fileHashAlgorithm": "sha256",
      "encryptionKeyId": "key-2026-01",
      "storageLocation": "/vault/ev-001",
      "collectedAt": "2026-01-20T14:35:00Z",
      "collectedBy": "system",
      "chainOfCustody": [
        {
          "action": "collected",
          "actor": "system",
          "timestamp": "2026-01-20T14:35:00Z",
          "details": "Evidence collected from USB device"
        },
        {
          "action": "transferred",
          "from": "system",
          "to": "analyst-001",
          "timestamp": "2026-01-20T15:00:00Z",
          "details": "Initial analysis"
        }
      ]
    }
  }
}

GET /api/evidence/{evidenceId}/chain-of-custody

Get chain of custody history

Response (200):

{
  "status": "success",
  "data": {
    "evidenceId": "ev-001",
    "chainOfCustody": [
      {
        "sequence": 1,
        "action": "collected",
        "actor": "system",
        "timestamp": "2026-01-20T14:35:00Z",
        "location": "/evidence/vault/ev-001"
      },
      {
        "sequence": 2,
        "action": "transferred",
        "from": "system",
        "to": "analyst-001",
        "timestamp": "2026-01-20T15:00:00Z",
        "signature": "analyst-001-sig"
      }
    ],
    "status": "verified",
    "integrityVerified": true
  }
}

POST /api/evidence/{evidenceId}/verify-hash

Verify evidence integrity

Request:

{
  "expectedHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Response (200):

{
  "status": "success",
  "data": {
    "verified": true,
    "matchingHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "verificationTimestamp": "2026-01-22T10:30:00Z"
  }
}

ANALYTICS & REPORTING

GET /api/analytics/summary

Get system analytics summary

Response (200):

{
  "status": "success",
  "data": {
    "summary": {
      "totalEvents": 156234,
      "totalIncidents": 45,
      "activeIncidents": 12,
      "resolvedIncidents": 33,
      "totalUsers": 250,
      "usersWithAnomalies": 18,
      "highRiskUsers": 3,
      "lastIncidentTime": "2026-01-22T09:45:00Z"
    }
  }
}

GET /api/analytics/trends

Get incident trends over time

Query Parameters:

  • days (int): Number of days (default: 30)
  • granularity (string): day, week, month

Response (200):

{
  "status": "success",
  "data": {
    "trends": [
      {
        "date": "2026-01-22",
        "incidents": 3,
        "anomalies": 12,
        "alertsTriggered": 8,
        "risksDetected": 2
      }
    ]
  }
}

GET /api/analytics/user-risk-scores

Get user risk scores

Response (200):

{
  "status": "success",
  "data": {
    "userRisks": [
      {
        "userId": "user-001",
        "email": "user@example.com",
        "riskScore": 85,
        "riskLevel": "high",
        "riskFactors": [
          "mass_file_access",
          "usb_device_usage",
          "after_hours_access"
        ],
        "lastActivity": "2026-01-22T10:15:00Z"
      }
    ]
  }
}

POST /api/reports/generate

Generate forensic report

Request:

{
  "type": "incident",
  "incidentId": "inc-001",
  "format": "pdf",
  "includeChainOfCustody": true,
  "includeEvidence": true
}

Response (201):

{
  "status": "success",
  "code": 201,
  "data": {
    "reportId": "rep-001",
    "status": "processing",
    "estimatedTime": "30 seconds"
  }
}

GET /api/reports/{reportId}/download

Download generated report

Response (200): Returns file (application/pdf or application/vnd.openxmlformats)

USER MANAGEMENT

GET /api/admin/users

List all users (Admin only)

Response (200):

{
  "status": "success",
  "data": {
    "users": [
      {
        "id": "user-001",
        "email": "admin@example.com",
        "name": "Admin User",
        "role": "admin",
        "mfaEnabled": true,
        "status": "active",
        "createdAt": "2026-01-01T00:00:00Z",
        "lastLogin": "2026-01-22T10:30:00Z"
      }
    ],
    "totalCount": 5
  }
}

POST /api/admin/users

Create new user (Admin only)

Request:

{
  "email": "analyst@example.com",
  "name": "Security Analyst",
  "role": "analyst",
  "sendInvitation": true
}

Response (201):

{
  "status": "success",
  "code": 201,
  "data": {
    "user": {
      "id": "user-new",
      "email": "analyst@example.com",
      "status": "invited"
    }
  }
}

PUT /api/admin/users/{userId}

Update user (Admin only)

Request:

{
  "role": "viewer",
  "status": "inactive"
}

Response (200):

{
  "status": "success",
  "data": { /* updated user */ }
}

SYSTEM ADMINISTRATION

GET /api/admin/system/health

Get system health status

Response (200):

{
  "status": "success",
  "data": {
    "health": {
      "api": {
        "status": "healthy",
        "responseTime": 145,
        "requests24h": 45230
      },
      "database": {
        "status": "healthy",
        "connections": 5,
        "size": "2.3 GB"
      },
      "storage": {
        "total": 1000,
        "used": 600,
        "free": 400
      },
      "memory": {
        "total": 8192,
        "used": 4096,
        "free": 4096
      },
      "monitors": {
        "fileMonitor": "active",
        "usbMonitor": "active",
        "processMonitor": "active"
      }
    }
  }
}

GET /api/admin/system/config

Get system configuration (Admin only)

Response (200):

{
  "status": "success",
  "data": {
    "config": {
      "retention": {
        "incidentLogs": 2555,
        "auditLogs": 2555,
        "evidence": 3650
      },
      "security": {
        "mfaRequired": true,
        "sessionTimeout": 30,
        "passwordExpiry": 90
      },
      "monitoring": {
        "fileMonitorEnabled": true,
        "usbMonitorEnabled": true,
        "processMonitorEnabled": true
      }
    }
  }
}

PUT /api/admin/system/config

Update system configuration (Admin only)

ERROR CODES

Code Error Description
200 OK Request successful
201 Created Resource created
204 No Content Request successful, no content
400 Bad Request Invalid request format
401 Unauthorized Missing/invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource not found
409 Conflict Resource already exists
422 Unprocessable Entity Invalid request data
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error
503 Service Unavailable Service temporarily unavailable

RATE LIMITING

Limits:

  • 100 requests per minute per IP address
  • 1000 requests per minute per authenticated user
  • WebSocket connections: 10 per user

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642858260

WEBHOOKS (Optional)

Subscribe to incident events:

Event Types:

  • incident.created
  • incident.updated
  • incident.resolved
  • evidence.collected
  • alert.critical

API Documentation - Version 1.0.0 Last Updated: January 22, 2026