API Reference ============= This section provides detailed API documentation for the Vulnerability Scanner backend. Authentication -------------- All API endpoints (except ``/token`` and ``/users/create-admin``) require authentication via JWT Bearer token. Obtaining a Token ~~~~~~~~~~~~~~~~~ .. http:post:: /token Authenticate and obtain a JWT access token. **Request Body (form data):** - **username** (string): User's username - **password** (string): User's password **Response:** .. code-block:: json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer" } **Example:** .. code-block:: bash curl -X POST http://localhost:8000/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=alice.smith&password=Password123!" Using the Token ~~~~~~~~~~~~~~~ Include the token in the ``Authorization`` header:: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... User Endpoints -------------- Registration and Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: /users/create-admin Create the first admin user (only works if no admin exists). **Request Body:** .. code-block:: json { "username": "admin", "password": "SecurePassword123!", "full_name": "Administrator", "email": "admin@example.com" } .. http:post:: /users/register Register a new user account. **Request Body:** .. code-block:: json { "username": "newuser", "password": "Password123!", "full_name": "New User", "email": "newuser@example.com", "is_admin": false } .. http:get:: /users/has-admin Check if an admin user exists in the system. **Response:** .. code-block:: json { "has_admin": true } Profile Management ~~~~~~~~~~~~~~~~~~ .. http:get:: /users/me/profile Get the current user's profile information. **Authentication**: Required **Response:** .. code-block:: json { "id": 1, "username": "alice.smith", "full_name": "Alice Smith", "email": "alice.smith@example.com", "is_admin": true, "ips": ["192.168.1.10", "192.168.1.11"], "contact_person_id": 1 } .. http:put:: /users/me/profile-v2 Update the current user's profile. **Authentication**: Required **Request Body:** .. code-block:: json { "full_name": "Alice M. Smith", "email": "alice.smith@newdomain.com" } .. http:put:: /users/me/change-password Change the current user's password. **Authentication**: Required **Request Body:** .. code-block:: json { "old_password": "OldPassword123!", "new_password": "NewPassword456!" } IP Responsibility Management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:delete:: /users/me/ips/{ip_address} Remove an IP from the current user's responsibilities. **Authentication**: Required :param ip_address: The IP address to remove (e.g., "192.168.1.10") .. http:post:: /users/me/ips/{ip_address}/transfer Transfer an IP to another user. **Authentication**: Required :param ip_address: The IP address to transfer **Request Body:** .. code-block:: json { "target_username": "bob.jones" } Admin Endpoints --------------- User Management ~~~~~~~~~~~~~~~ .. http:get:: /admin/users Get all users with their IP assignments. **Authentication**: Admin required **Query Parameters:** - **skip** (integer, optional): Number of records to skip (default: 0) - **limit** (integer, optional): Maximum records to return (default: 100) **Response:** .. code-block:: json [ { "id": 1, "username": "alice.smith", "full_name": "Alice Smith", "email": "alice.smith@example.com", "is_admin": true, "ips": ["192.168.1.10", "192.168.1.11"], "contact_person_id": 1 } ] .. http:put:: /admin/users/{user_id} Update any user's profile. **Authentication**: Admin required :param user_id: The user ID **Request Body:** .. code-block:: json { "full_name": "Alice M. Smith", "email": "alice.smith@example.com", "is_admin": true } .. http:delete:: /admin/users/{user_id}/ips/{ip_address} Remove an IP from any user. **Authentication**: Admin required :param user_id: The user ID :param ip_address: The IP address to remove .. http:post:: /admin/users/{from_user_id}/ips/{ip_address}/transfer/{to_user_id} Transfer an IP between users. **Authentication**: Admin required :param from_user_id: Source user ID :param to_user_id: Target user ID :param ip_address: The IP address to transfer Contact Person Endpoints ------------------------- .. http:get:: /contact-persons/ Get all contact persons. **Authentication**: Admin required **Response:** .. code-block:: json [ { "id": 1, "name": "Alice Smith", "email": "alice.smith@example.com", "user_id": 1, "ips": [ {"ip_address": "192.168.1.10"}, {"ip_address": "192.168.1.11"} ] } ] .. http:post:: /contact-persons/ Create a new contact person. **Authentication**: Admin required **Request Body:** .. code-block:: json { "name": "New Contact", "email": "contact@example.com", "ips": ["192.168.1.20", "192.168.1.21"] } .. http:put:: /contact-persons/{contact_id} Update a contact person. **Authentication**: Admin required :param contact_id: The contact person ID .. http:delete:: /contact-persons/{contact_id} Delete a contact person. **Authentication**: Admin required :param contact_id: The contact person ID Dashboard Endpoints ------------------- .. http:get:: /dashboard/sent-reports Get enhanced dashboard data for sent reports. **Authentication**: Admin required See :doc:`/user_guide/sent-reports-dashboard` for detailed response format. Report Endpoints ---------------- .. http:post:: /reports/send-notifications/{scan_id} Send vulnerability notifications for a specific scan. **Authentication**: Admin required :param scan_id: The scan ID **Response:** .. code-block:: json { "message": "Notifications sent", "notifications_sent": 8, "total_hosts": 10, "errors": [ "No contact person found for IP: 192.168.1.50" ] } Error Responses --------------- All endpoints may return the following error responses: 400 Bad Request ~~~~~~~~~~~~~~~ .. code-block:: json { "detail": "Invalid request parameters" } 401 Unauthorized ~~~~~~~~~~~~~~~~ .. code-block:: json { "detail": "Not authenticated" } 403 Forbidden ~~~~~~~~~~~~~ .. code-block:: json { "detail": "Not enough permissions" } 404 Not Found ~~~~~~~~~~~~~ .. code-block:: json { "detail": "Resource not found" } 422 Unprocessable Entity ~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: json { "detail": [ { "loc": ["body", "email"], "msg": "value is not a valid email address", "type": "value_error.email" } ] } 500 Internal Server Error ~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: json { "detail": "Internal server error" } Pagination ---------- Endpoints that return lists support pagination via query parameters: - **skip**: Number of records to skip (default: 0) - **limit**: Maximum number of records to return (default: 100, max: 1000) **Example:** .. code-block:: bash GET /admin/users?skip=20&limit=10 Data Models ----------- User ~~~~ .. code-block:: json { "id": 1, "username": "alice.smith", "full_name": "Alice Smith", "email": "alice.smith@example.com", "is_admin": true } UserWithIPs ~~~~~~~~~~~ .. code-block:: json { "id": 1, "username": "alice.smith", "full_name": "Alice Smith", "email": "alice.smith@example.com", "is_admin": true, "ips": ["192.168.1.10", "192.168.1.11"], "contact_person_id": 1 } ContactPerson ~~~~~~~~~~~~~ .. code-block:: json { "id": 1, "name": "Alice Smith", "email": "alice.smith@example.com", "user_id": 1, "ips": [ {"ip_address": "192.168.1.10"}, {"ip_address": "192.168.1.11"} ] }