Skip to content

api_reference.md

Latest commit

 

History

History
543 lines (449 loc) · 9.13 KB

api_reference.md

File metadata and controls

543 lines (449 loc) · 9.13 KB
Raw

CyberSentinel API Reference

Base URL: http://localhost:8000/api/v1

Authentication

All protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Auth Endpoints

Register User

Create a new user account.

POST /auth/register

Request Body:

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

Response (201 Created):

{
  "id": 1,
  "email": "user@example.com",
  "role": "user",
  "xp": 0,
  "level": 1,
  "awareness_score": 0.0,
  "created_at": "2024-01-15T10:30:00Z"
}

Errors:

  • 400 - Email already registered
  • 422 - Invalid email format or password too short

Login

Authenticate and receive access token.

POST /auth/login

Request Body:

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

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Errors:

  • 401 - Invalid email or password
  • 403 - Account disabled

Get Current User

Get authenticated user's profile.

GET /auth/me

Response (200 OK):

{
  "id": 1,
  "email": "user@example.com",
  "role": "user",
  "xp": 1250,
  "level": 5,
  "awareness_score": 78.5,
  "created_at": "2024-01-15T10:30:00Z",
  "total_challenges": 45,
  "correct_challenges": 38,
  "streak": 7
}

Refresh Token

Get a new access token.

POST /auth/refresh

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Detection Endpoints

Analyze Text

Analyze text for phishing indicators.

POST /detect/analyze

Request Body:

{
  "text": "URGENT: Your account will be suspended! Click here to verify: http://fake-bank.com"
}

Response (200 OK):

{
  "risk_level": "high",
  "confidence": 0.87,
  "indicators": [
    {
      "name": "Urgency Tactics",
      "description": "The message uses pressure tactics to rush you into action",
      "severity": "medium"
    },
    {
      "name": "Suspicious Links",
      "description": "Contains potentially malicious URLs",
      "severity": "high"
    },
    {
      "name": "Generic Greeting",
      "description": "Uses impersonal greeting",
      "severity": "low"
    }
  ],
  "explanation": "WARNING: This message displays multiple phishing characteristics: Urgency Tactics, Suspicious Links. Do not click links or provide personal information.",
  "analyzed_at": "2024-01-15T10:35:00Z"
}

Risk Levels:

  • safe - No indicators detected (< 0.15)
  • low - Minor suspicious elements (0.15 - 0.30)
  • medium - Moderate phishing indicators (0.30 - 0.50)
  • high - Multiple phishing characteristics (0.50 - 0.75)
  • critical - Highly likely phishing (> 0.75)

Get Indicator Types

List all phishing indicator types.

GET /detect/indicators

Response (200 OK):

{
  "indicators": [
    {
      "id": "urgency",
      "name": "Urgency Tactics",
      "description": "Creates false sense of urgency",
      "examples": ["Act now!", "Limited time offer"]
    },
    {
      "id": "domain_mismatch",
      "name": "Domain Mismatch",
      "description": "Sender domain doesn't match organization",
      "examples": ["support@paypa1.com"]
    }
  ]
}

Training Endpoints

Get Challenge

Get a training challenge.

GET /training/challenge

Query Parameters:

Parameter Type Description
category string Filter by category (optional)
difficulty string easy, medium, hard (optional)
adaptive boolean Use adaptive selection (default: true)

Response (200 OK):

{
  "id": "ch_abc123",
  "category": "urgency",
  "difficulty": "medium",
  "email_content": "Subject: URGENT: Account Suspension Notice\n\nDear Customer,\n\nYour account will be suspended...",
  "question": "What phishing tactic is primarily used in this email?",
  "options": [
    {"id": "a", "text": "Creating urgency and fear"},
    {"id": "b", "text": "Offering a reward"},
    {"id": "c", "text": "Professional networking"},
    {"id": "d", "text": "Technical support request"}
  ],
  "xp_reward": 40
}

Submit Challenge Answer

Submit answer for a challenge.

POST /training/submit

Request Body:

{
  "challenge_id": "ch_abc123",
  "selected_option": "a",
  "time_taken": 15.5
}

Response (200 OK):

{
  "correct": true,
  "correct_answer": "a",
  "explanation": "This email uses urgency tactics with phrases like 'PERMANENTLY DELETED' to pressure you into clicking without thinking.",
  "xp_earned": 44,
  "new_total_xp": 1294,
  "new_level": 5,
  "streak": 8,
  "streak_bonus": 4
}

Get Training Progress

Get user's training statistics.

GET /training/progress

Response (200 OK):

{
  "total_challenges": 45,
  "correct_challenges": 38,
  "accuracy": 84.4,
  "current_streak": 8,
  "best_streak": 12,
  "xp": 1294,
  "level": 5,
  "xp_to_next_level": 206,
  "level_progress": 58.8
}

Get Leaderboard

Get top users by XP.

GET /training/leaderboard

Query Parameters:

Parameter Type Description
limit integer Max results (default: 10, max: 50)

Response (200 OK):

{
  "leaderboard": [
    {
      "rank": 1,
      "email": "cha***",
      "level": 8,
      "xp": 4100,
      "awareness_score": 88.5
    },
    {
      "rank": 2,
      "email": "ali***",
      "level": 7,
      "xp": 3200,
      "awareness_score": 85.2
    }
  ]
}

User Endpoints

Get Analytics

Get detailed user analytics.

GET /user/analytics

Response (200 OK):

{
  "overall_accuracy": 84.4,
  "total_challenges": 45,
  "average_time": 22.5,
  "improvement_rate": 12.5,
  "weakness_categories": [
    {
      "category": "suspicious_links",
      "score": 68.0,
      "attempts": 30,
      "label": "Link Analysis"
    },
    {
      "category": "urgency",
      "score": 72.0,
      "attempts": 25,
      "label": "Urgency Tactics"
    }
  ],
  "performance_trends": [
    {"date": "2024-01-09", "accuracy": 75.0, "challenges": 4},
    {"date": "2024-01-10", "accuracy": 80.0, "challenges": 5},
    {"date": "2024-01-11", "accuracy": 85.7, "challenges": 7}
  ],
  "suggested_focus": "suspicious_links"
}

Get Achievements

Get user's achievements.

GET /user/achievements

Response (200 OK):

{
  "achievements": [
    {
      "id": "first_challenge",
      "name": "First Steps",
      "description": "Complete your first challenge",
      "icon": "🎯",
      "unlocked": true
    },
    {
      "id": "level_10",
      "name": "Veteran",
      "description": "Reach level 10",
      "icon": "🌟",
      "unlocked": false
    }
  ],
  "total_unlocked": 5,
  "total_available": 8
}

Admin Endpoints

All admin endpoints require role: "admin"

Get All Users

List all users.

GET /admin/users

Query Parameters:

Parameter Type Description
skip integer Pagination offset
limit integer Results per page (max: 100)
search string Filter by email

Response (200 OK):

[
  {
    "id": 2,
    "email": "demo@cybersentinel.com",
    "role": "user",
    "xp": 1250,
    "level": 5,
    "awareness_score": 78.5,
    "created_at": "2024-01-10T08:00:00Z",
    "last_active": "2024-01-15T10:30:00Z",
    "total_challenges": 45,
    "accuracy": 84.4
  }
]

Update User

Modify user settings.

PUT /admin/users/{user_id}

Request Body:

{
  "role": "admin",
  "xp": 5000,
  "level": 10,
  "is_active": true
}

Response (200 OK):

{
  "message": "User updated successfully",
  "user_id": 2
}

Delete User

Remove a user account.

DELETE /admin/users/{user_id}

Response (200 OK):

{
  "message": "User deleted successfully"
}

Errors:

  • 400 - Cannot delete yourself
  • 404 - User not found

Get System Stats

Get platform-wide statistics.

GET /admin/stats

Response (200 OK):

{
  "total_users": 150,
  "active_users_today": 45,
  "total_detections": 1250,
  "average_accuracy": 76.8,
  "total_challenges_completed": 3420
}

Error Responses

All errors follow this format:

{
  "detail": "Error message description"
}

Common Status Codes:

Code Meaning
400 Bad Request - Invalid input
401 Unauthorized - Invalid/missing token
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
422 Validation Error - Invalid request body
500 Internal Server Error

Rate Limiting

Endpoint Type Limit
Authentication 10 requests/minute
Detection 60 requests/minute
Training 100 requests/minute
Admin 30 requests/minute

Headers returned:

  • X-RateLimit-Limit: Max requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Time until limit resets