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
- POST /token
Authenticate and obtain a JWT access token.
Request Body (form data):
username (string): User’s username
password (string): User’s password
Response:
{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer" }
Example:
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
- POST /users/create-admin
Create the first admin user (only works if no admin exists).
Request Body:
{ "username": "admin", "password": "SecurePassword123!", "full_name": "Administrator", "email": "admin@example.com" }
- POST /users/register
Register a new user account.
Request Body:
{ "username": "newuser", "password": "Password123!", "full_name": "New User", "email": "newuser@example.com", "is_admin": false }
- GET /users/has-admin
Check if an admin user exists in the system.
Response:
{ "has_admin": true }
Profile Management
- GET /users/me/profile
Get the current user’s profile information.
Authentication: Required
Response:
{ "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 }
- PUT /users/me/profile-v2
Update the current user’s profile.
Authentication: Required
Request Body:
{ "full_name": "Alice M. Smith", "email": "alice.smith@newdomain.com" }
- PUT /users/me/change-password
Change the current user’s password.
Authentication: Required
Request Body:
{ "old_password": "OldPassword123!", "new_password": "NewPassword456!" }
IP Responsibility Management
- DELETE /users/me/ips/{ip_address}
Remove an IP from the current user’s responsibilities.
Authentication: Required
- Parameters:
ip_address – The IP address to remove (e.g., “192.168.1.10”)
- POST /users/me/ips/{ip_address}/transfer
Transfer an IP to another user.
Authentication: Required
- Parameters:
ip_address – The IP address to transfer
Request Body:
{ "target_username": "bob.jones" }
Admin Endpoints
User Management
- 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:
[ { "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 } ]
- PUT /admin/users/{user_id}
Update any user’s profile.
Authentication: Admin required
- Parameters:
user_id – The user ID
Request Body:
{ "full_name": "Alice M. Smith", "email": "alice.smith@example.com", "is_admin": true }
- DELETE /admin/users/{user_id}/ips/{ip_address}
Remove an IP from any user.
Authentication: Admin required
- Parameters:
user_id – The user ID
ip_address – The IP address to remove
- POST /admin/users/{from_user_id}/ips/{ip_address}/transfer/{to_user_id}
Transfer an IP between users.
Authentication: Admin required
- Parameters:
from_user_id – Source user ID
to_user_id – Target user ID
ip_address – The IP address to transfer
Contact Person Endpoints
- GET /contact-persons/
Get all contact persons.
Authentication: Admin required
Response:
[ { "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"} ] } ]
- POST /contact-persons/
Create a new contact person.
Authentication: Admin required
Request Body:
{ "name": "New Contact", "email": "contact@example.com", "ips": ["192.168.1.20", "192.168.1.21"] }
- PUT /contact-persons/{contact_id}
Update a contact person.
Authentication: Admin required
- Parameters:
contact_id – The contact person ID
- DELETE /contact-persons/{contact_id}
Delete a contact person.
Authentication: Admin required
- Parameters:
contact_id – The contact person ID
Dashboard Endpoints
- GET /dashboard/sent-reports
Get enhanced dashboard data for sent reports.
Authentication: Admin required
See Sent Reports Dashboard for detailed response format.
Report Endpoints
- POST /reports/send-notifications/{scan_id}
Send vulnerability notifications for a specific scan.
Authentication: Admin required
- Parameters:
scan_id – The scan ID
Response:
{ "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
{
"detail": "Invalid request parameters"
}
403 Forbidden
{
"detail": "Not enough permissions"
}
404 Not Found
{
"detail": "Resource not found"
}
422 Unprocessable Entity
{
"detail": [
{
"loc": ["body", "email"],
"msg": "value is not a valid email address",
"type": "value_error.email"
}
]
}
500 Internal Server Error
{
"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:
GET /admin/users?skip=20&limit=10
Data Models
User
{
"id": 1,
"username": "alice.smith",
"full_name": "Alice Smith",
"email": "alice.smith@example.com",
"is_admin": true
}
UserWithIPs
{
"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
{
"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"}
]
}