Security Base API Documentation

GET User Authentication Status

Checks the current authentication status of the user.

Description

This endpoint allows you to verify if a user is currently logged in and their session is active. It's useful for protecting routes and providing real-time feedback to the user.

Parameters

None.

Responses

{
    "authenticated": true,
    "user_id": "uuid-1234-abcd",
    "username": "admin"
}

{
    "authenticated": false,
    "message": "No active session found."
}

POST User Login

Authenticates a user with their credentials.

Description

Submit user credentials to log into the system. A successful login will return a session token.

Request Body

A JSON object containing the user's email/username and password.

{
    "identifier": "user@example.com",
    "password": "securepassword123"
}

Responses

{
    "message": "Login successful.",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

{
    "message": "Invalid username or password."
}

{
    "message": "Too many login attempts. Please try again in 5 minutes."
}

GET Get All Users

Retrieves a list of all registered users.

Description

This endpoint is typically restricted to administrators and returns a paginated list of users with their basic information.

Query Parameters

• page (integer, optional): The page number to retrieve.
• limit (integer, optional): The number of users per page.
• search (string, optional): Filter users by username or email.

Responses

{
    "total_users": 150,
    "page": 1,
    "limit": 20,
    "users": [
        {
            "user_id": "uuid-abc-123",
            "username": "johndoe",
            "email": "john.doe@example.com",
            "role": "user",
            "created_at": "2023-10-26T10:00:00Z"
        },
        // ... more users
    ]
}

{
    "message": "Access denied. Only administrators can view all users."
}

POST Report New Incident

Submit a new security incident report.

Description

Allows authenticated users to report new security incidents, providing details about the event.

Request Body

A JSON object detailing the incident.

{
    "title": "Phishing Attempt Detected",
    "description": "Received suspicious email asking for credentials.",
    "severity": "medium",
    "category": "phishing",
    "reported_by": "uuid-abcd-1234",
    "location": "user@example.com inbox"
}

Responses

{
    "message": "Incident reported successfully.",
    "incident_id": "inc-9876-wxyz"
}

{
    "message": "Missing required field: title."
}

{
    "message": "Authentication required."
}

GET Get Vulnerability Scan Results

Retrieve results from recent vulnerability scans.

Description

Fetch detailed results from automated vulnerability scans performed on your systems or applications.

Query Parameters

• scan_id (string, optional): Filter results for a specific scan.
• status (string, optional): Filter by vulnerability status (e.g., "open", "closed", "in-progress").
• severity (string, optional): Filter by severity level (e.g., "low", "medium", "high", "critical").

Responses

{
    "scan_id": "scan-20231026-1500",
    "scan_date": "2023-10-26T15:00:00Z",
    "vulnerabilities": [
        {
            "vuln_id": "CVE-2023-XXXX",
            "name": "SQL Injection Vulnerability",
            "severity": "critical",
            "status": "open",
            "description": "The application is vulnerable to SQL injection attacks...",
            "cvss_score": 9.8,
            "affected_asset": "webserver.example.com/login"
        },
        // ... more vulnerabilities
    ]
}

{
    "message": "No vulnerability scan results found."
}

GET Get Audit Logs

Retrieve system audit logs for security events.

Description

Access detailed logs of all significant security-related events within the system, such as login attempts, access changes, and configuration modifications.

Query Parameters

• start_date (datetime, optional): Filter logs from a specific start date.
• end_date (datetime, optional): Filter logs up to a specific end date.
• event_type (string, optional): Filter by specific event type (e.g., "login_success", "file_access", "config_change").
• user_id (string, optional): Filter logs associated with a specific user.

Responses

{
    "logs": [
        {
            "timestamp": "2023-10-26T11:30:15Z",
            "event_type": "login_success",
            "user_id": "uuid-1234-abcd",
            "username": "admin",
            "ip_address": "192.168.1.100",
            "details": "Successful login from internal IP."
        },
        {
            "timestamp": "2023-10-26T11:35:02Z",
            "event_type": "config_change",
            "user_id": "uuid-abcd-1234",
            "username": "security_officer",
            "ip_address": "10.0.0.5",
            "details": "Firewall rule updated: Added port 22 for SSH."
        }
        // ... more logs
    ]
}

{
    "message": "Invalid date format. Please use ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)."
}

{
    "message": "Access to audit logs is restricted."
}