Data Flows

This section details the key data flows within VulnerabilityHub, utilizing sequence diagrams to illustrate interactions between components.

Scan Upload Process

        sequenceDiagram
    participant User
    participant FE as Frontend
    participant API as Backend API
    participant Parser as XML Parser
    participant DB as Database

    User->>FE: Uploads XML Report
    FE->>API: POST /scans/upload
    API->>Parser: Parse XML Content
    Parser-->>API: Extraction (Hosts, Vulns)
    API->>DB: Transactional Save
    DB-->>API: Success
    API->>User: 200 OK (Upload Queued/Done)

    par Notifications
        API->>DB: Identify Contact Persons
        API->>User: Send Email Notification
    end
    

Contact Person Import

        sequenceDiagram
    participant Admin
    participant API as Backend API
    participant Importer as Import Service
    participant DB as Database

    Admin->>API: Trigger Import (CSV/DB)
    API->>Importer: Load Data
    Importer->>DB: Fetch Existing Contacts
    Importer->>Importer: Diff & Conflict Detection

    alt Conflicts Found
        Importer-->>API: Return Conflicts
        API-->>Admin: Request Resolution
    else No Conflicts
        Importer->>DB: Apply Changes (Create/Update/Delete)
        Importer->>DB: Log Audit Events
        API-->>Admin: Success
    end
    

Dispute Resolution Flow

When a user challenges the assignment of a report or finding.

        sequenceDiagram
    participant User
    participant API as Backend API
    participant DB as Database
    participant Admin

    User->>API: POST /disputes
    Note over User,API: Reason: "Not my IP"
    API->>DB: Create Dispute Record
    API-->>User: 200 OK

    Note over Admin: Review Process
    Admin->>API: GET /disputes
    Admin->>API: POST /disputes/{id}/resolve

    alt Resolved (Reassigned)
        API->>DB: Updates IP Ownership
        API->>DB: Closes Dispute
        API->>User: Email (Resolution)
    else Ignored
        API->>DB: Closes Dispute (Ignored)
    end
    

Report Access via Magic Link

How external contact persons access restricted reports without a full user account.

        sequenceDiagram
    participant CP as Contact Person
    participant API as Backend API
    participant DB as Database

    CP->>API: GET /reports/view/{token}
    API->>DB: Validate Token & Expiry

    alt Valid Token
        API->>DB: Log Access (IP, User Agent)
        API->>DB: Fetch Report Content
        API-->>CP: Visual Report (HTML/PDF)
    else Invalid/Expired
        API-->>CP: 403 Forbidden
    end
    

Vulnerability Prediction Flow

How future vulnerability trends are calculated.

        sequenceDiagram
    participant Job as Scheduler
    participant Service as Prediction Service
    participant DB as Database
    participant Prophet as ML Engine

    Job->>Service: Trigger Analysis
    Service->>DB: Fetch Historical Data (vulnerability_time_series)
    DB-->>Service: Time Series Data
    Service->>Prophet: Fit Model & Predict
    Prophet-->>Service: Forecast Data
    Service->>DB: Store Predictions

    Note over DB: Grafana reads from here
    

Authentication Flow

User login process.

        sequenceDiagram
    participant User
    participant Frontend
    participant API as Backend API
    participant DB as Database

    User->>Frontend: Enter Credentials
    Frontend->>API: POST /auth/login
    API->>DB: Verify Username & Password Hash

    alt Valid
        DB-->>API: User Data
        API->>API: Generate Access Token (JWT)
        API-->>Frontend: Token + User Info
        Frontend->>Frontend: Store Token
    else Invalid
        API-->>Frontend: 401 Unauthorized
    end