Architecture

This document describes the architecture and components of VulnerabilityHub.

System Overview

VulnerabilityHub follows a modern three-tier architecture, designed for scalability and maintainability. It separates the presentation layer (Frontend) from the business logic (Backend API) and data persistence (Database).

        graph TD
    User[User / Admin] -->|HTTPS| Frontend["Frontend SPA<br/>(Vue 3 + Vuetify)"]
    Frontend -->|REST API| Backend["Backend API<br/>(FastAPI)"]

    subgraph Data Layer
        DB[("MariaDB<br/>Database")]
    end

    subgraph External Services
        SMTP[SMTP Server]
        ExtDB["External CMDB<br/>(Optional)"]
        LDAP["LDAP / AD<br/>(Future/Optional)"]
        ClamAV[ClamAV Scanner]
    end

    subgraph Observability
        Grafana[Grafana]
        Prometheus[Prometheus]
    end

    Backend -->|SQLAlchemy| DB
    Backend -->|SMTP| SMTP
    Backend -->|Import| ExtDB
    Backend -->|Auth| LDAP
    Backend -->|Scan| ClamAV

    Prometheus -->|Scrape Metrics| Backend
    Grafana -->|Query| DB
    Grafana -->|Query| Prometheus

Core Components

1. Frontend (Vue 3)

The frontend is a Single Page Application (SPA) built with Vue 3 and TypeScript.

  • Framework: Vue 3 (Composition API)

  • UI Library: Vuetify 3 (Material Design)

  • State Management: Pinia

  • Routing: Vue Router

  • Networking: Axios

It handles user authentication, scan management, interactive dashboards, and administration interfaces.

2. Backend (FastAPI)

The backend is a high-performance, async REST API built with Python 3.9+ and FastAPI.

  • API Framework: FastAPI

  • ORM: SQLAlchemy (Sync/Async patterns)

  • Validation: Pydantic v2

  • ML Engine: Facebook Prophet (for vulnerability forecasting)

  • Security: OAuth2/JWT flavor for auth, Role-Based Access Control (RBAC).

Key Responsibilities: - XML Parsing (Greenbone/OpenVAS reports) - Business Logic (Disputes, Notifications, Imports) - Background Tasks (Email sending, File processing) - Audit Logging (Comprehensive tracking of actions) - Virus Scanning: Integrated with ClamAV to scan all uploaded files.

3. Database (MariaDB)

The relational database serves as the single source of truth.

  • Core Data: Scans, Hosts, Vulnerabilities, Results.

  • Identity: Users, Contact Persons, Permissions.

  • Audit: audit_logs, access_logs.

  • Time Series: Materialized views for efficient analytics.

4. Monitoring (Grafana + Prometheus)

  • Grafana: Visualizes vulnerability trends and system metrics directly from the DB and via Prometheus.

  • Prometheus: Scrapes application metrics (endpoint latency, error rates) exposed by prometheus-fastapi-instrumentator.

Data Flows

For detailed diagrams of system interactions (Scan Upload, Dispute Resolution, etc.), please refer to Data Flows.

Security Architecture

  • Audit Logging: Every critical action (create/update/delete, file access) is logged to the audit_logs table. See Audit Logging.

  • Input Validation: Strict typing with Pydantic prevents injection and data corruption.

  • Authentication: Stateless JWT tokens with distinction between “User” (interactive) and “Contact Person” (magic link) contexts.

    • Future Plan: LDAP/AD integration for simplified user management.

  • Network Isolation: Database and internal services are not exposed publicly in production environments.