Services Overview

CVEScan Web consists of four core services and a single initialization service, each with a distinct role in the platform's architecture:

  • WebUI: The user-facing interface for interacting with CVEScan Web.
  • API Server: Provides RESTful endpoints for all core platform operations and integrates with Keycloak for authentication.
  • Keycloak: Manages user authentication.
  • PostgreSQL Database: A single server hosting two separate databases for the API server and Keycloak, each secured with its own credentials.
  • Keycloak Configurator: A one-time initialization service that provisions Keycloak automatically on first deployment, including service account setup and configuration sharing with the API server.

All these services are typically managed together using Docker Compose, which simplifies deployment and networking.

For production environments, adding a reverse proxy as the single entry point to all services can be handy as it can also be used to handle HTTPS termination and route incoming requests to the appropriate internal service, ensuring controlled access. Moreover, it can help in defining rate limiting and access control strategies, enhancing the overall security posture of the deployment.

Below is an example architecture for a production environment using Docker Compose and a reverse proxy as the front door to the system:

flowchart TD
    subgraph Internal network
        A[Reverse Proxy]
        B[WebUI]
        C[API Server]
        D[Keycloak]
        E[PostgreSQL Database]
        F[Keycloak Configurator]
    end
    X[An external client] -->|HTTPS| A
    A -->|HTTP| B
    A -->|HTTP| C
    A -->|HTTP| D
    C -->|TCP/IP| E
    D -->|TCP/IP| E
    F -->|HTTP| D
    C -->|HTTP| D

Note

This is just a reference example. You may customize the deployment to fit your requirements. For instance, you can use a different reverse proxy, run the reverse proxy outside of Docker Compose, or deploy services on separate infrastructure.

Reverse Proxy

The reverse proxy is the only entry point to CVEScan Web services, serving as the front door of the system. It routes incoming requests to the appropriate services, ensuring controlled access and enabling rate limiting to prevent abuse.

Additionally, it handles HTTPS termination to secure data in transit by decrypting incoming TLS traffic and forwarding it to the appropriate services over HTTP. Since all services are deployed within an isolated Docker Compose network, communication between them remains secure despite using HTTP internally. This setup simplifies service interactions while maintaining external security through TLS.

WebUI

The WebUI serves as the user-facing interface for CVEScan Web, enabling users to interact with the platform seamlessly. It provides functionalities such as uploading scan reports, reviewing detected vulnerabilities, and managing annotations. Since the WebUI is accessed via a client browser, all its communication with the API server is routed securely through the reverse proxy.

API Server

The API server is the backbone of CVEScan Web, providing a comprehensive set of endpoints for managing the platform's core functionalities. Key endpoints include user and role management, and CRUD operations for vaults, projects, components, scans, and annotations. The API server integrates with Keycloak for secure authentication, ensuring that only authorized users can access the API.

The API is designed with RESTful principles and includes detailed OpenAPI documentation, enabling developers to easily integrate and extend the platform.

Keycloak

Keycloak is an open-source identity and access management solution used in CVEScan Web exclusively for user authentication. It handles authentication requests, manages user sessions, and integrates with the API server to provide a secure login mechanism for the system.

Additionally, Keycloak can be useful for implementing Single Sign-On (SSO) and identity federation, enabling seamless authentication across multiple systems and platforms.

In CVEScan, Keycloak is only used for authentication and does not handle authorization within CVEScan Web. The API server manages authorization and access control based on user roles defined in the API server's database.

Keycloak Configurator

The Keycloak Configurator is a one-time initialization service that automates the otherwise complex process of configuring Keycloak. This custom tool, written in TypeScript, eliminates the need for manual setup which would typically require a solid understanding of Keycloak and OpenID Connect protocols. It ensures Keycloak is properly configured with all the necessary settings to function correctly within the CVEScan Web ecosystem, creates service accounts, and shares secrets with the API server.

The Keycloak Configurator also creates a service account, which is crucial for enabling the API server to manage users and interact with Keycloak. The service account's secret is securely stored in the .secrets/.env file. This secret is automatically shared with the API server through a shared volume.

The Keycloak Configurator requires Keycloak administrator credentials to perform its tasks, and it will exit with code 0 after successfully configuring Keycloak.

Important

Although the Keycloak Configurator is designed to apply an effective configuration on the first deployment, you may need to manually adjust more advanced settings in Keycloak, such as configuring OTP (One-Time Password) for two-factor authentication, setting up identity federation for external identity providers, or adding a brute-force protection policy. These configurations are not handled by the Keycloak Configurator as they can vary significantly based on your specific security requirements and deployment context.

For more information on these advanced configurations, refer to the Keycloak documentation.

PostgreSQL Database

The database is a PostgreSQL server hosting two separate databases: one for the API server and another for Keycloak. Each database is secured with its own set of credentials, ensuring that only the respective service can access its data. This setup provides clear separation of concerns, enhances security, and simplifies data management.