Running CVEScan Web

This documentation provides a reference example, and may not fit your specific requirements or infrastructure. You are encouraged to adapt the deployment to your needs.

Also, as CVEScan will store sensitive data, please ensure that you follow best practices for securing your deployment, such as using strong admin credentials, enabling TLS with a modern configuration (e.g., using strong ciphers, disabling outdated protocols, etc.), and restricting access to the Keycloak admin console.

Prerequisites

Please ensure you have the following tools installed on your machine:

Git. This guide was tested with Git version 2.43.0.
Docker. This guide was tested with Docker version 28.2.2, build e6534b4.

1. Cloning the Repository

The first step is to clone the CVEScan Web repository. Depending on your access level, you can either clone the source code repository or the distribution repository.

Source Code Access: If you have access to the CVEScan Web source code repository, you can clone it using the following command:
```
git clone https://gitlab.com/witekio/rnd/theembeddedkit/cvescan/cvescan-web.git
```
You will be prompted for your GitLab credentials. As your repository access is managed through an access token, you may enter any value for the username, but you must provide your personal access token as the password to authenticate successfully.

Once cloned, navigate to the project directory using:
```
cd cvescan-web
```
Pre-built Images Access: If you only have access to the CVEScan Web Dist repository, you can clone it using the following command:
```
git clone https://gitlab.com/witekio/rnd/theembeddedkit/cvescan/cvescan-web-dist.git
```
You will be prompted for your GitLab credentials. As your repository access is managed through an access token, you may enter any value for the username, but you must provide your personal access token as the password to authenticate successfully.

Once cloned, navigate to the project directory using:
```
cd cvescan-web-dist
```

2. Configuring NGINX Reverse Proxy

A sample nginx.conf file is provided in the root directory of the CVEScan Web repository. This configuration file must be customized to match your specific environment and serves as the NGINX reverse proxy configuration for the CVEScan Web application.

For production environments, it is strongly recommended to configure a domain name and enable SSL/TLS to ensure secure communication between clients and the server. While it is technically possible to run CVEScan Web using HTTP and direct IP address access, it is not suitable for production environments. Even if you are deploying the application on a private network, using a domain name and SSL/TLS is a best practice to enhance security and protect sensitive data.

To set up SSL/TLS, update the nginx.conf file with your domain name and the paths to your SSL certificate and key. Please refer to the NGINX documentation for detailed instructions.

The provided nginx.conf file includes lines with comments beginning with # TODO. These lines require customization to match your specific environment configuration.

Important

The provided nginx.conf file grants access to all Keycloak endpoints including the admin console. However, for security reasons, it is highly recommended to restrict access to the Keycloak admin console to specific IP addresses or networks.

Please refer to the Keycloak documentation for guidance on which endpoints should be exposed, and consult the NGINX access module documentation for instructions on configuring access controls.

Local setup

If you want to test the application locally, you can replace the content of the nginx.conf file with the following minimal configuration. This configuration is suitable for local development and testing purposes, allowing you to run the application without a domain name or SSL/TLS. However, please note that this configuration is not secure and should NEVER be used in production environments. It is intended for local testing only.

server {
    listen          80;
    server_name     localhost;

    location /webui/ {
        proxy_pass http://webui:80/webui/;

        proxy_set_header        Host               $host;
        proxy_set_header        X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header        X-Forwarded-Host   $host;
        proxy_set_header        X-Forwarded-Proto  $scheme;
        proxy_set_header        X-Forwarded-Port   $server_port;
    }

    location /api/ {
        proxy_pass http://api:3100/api/;

        proxy_set_header        Host               $host;
        proxy_set_header        X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header        X-Forwarded-Host   $host;
        proxy_set_header        X-Forwarded-Proto  $scheme;
        proxy_set_header        X-Forwarded-Port   $server_port;
    }

    location /auth/ {
        proxy_pass http://keycloak:8080/auth/;

        proxy_set_header        Host               $host;
        proxy_set_header        X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header        X-Forwarded-Host   $host;
        proxy_set_header        X-Forwarded-Proto  $scheme;
        proxy_set_header        X-Forwarded-Port   $server_port;
    }

    #? Redirect /webui and / to /webui/
    location = /webui {
        return 301 /webui/;
    }
    location = / {
        return 301 /webui/;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

3. Setting Up Environment Variables

CVEScan Web relies on environment variables for its configuration. To set these up, create a .env file in the root of your project and add the variables listed below. Docker Compose will use this file to configure the application services.

COMPOSE_PROJECT_NAME=cvescan_web

# This is an intermediary variable used to build other environment variables to avoid repetition:
CVESCAN_HOST="https://your_domain_name" # Specify the protocol and don't end with /

CVESCAN_DB_ADMIN_USER="postgres"
CVESCAN_DB_ADMIN_PASSWORD="CHANGE_ME"

CVESCAN_API_EXPOSE_SWAGGER=false   # Default: false

CVESCAN_API_DB_NAME="cvescan_api"
CVESCAN_API_DB_USER="cvescan_api_user"
CVESCAN_API_DB_PASSWORD="CHANGE_ME"
CVESCAN_API_ADMIN_EMAIL="CHANGE_ME"
CVESCAN_API_ADMIN_PASSWORD="CHANGE_ME"

CVESCAN_KEYCLOAK_DB_NAME="cvescan_keycloak"
CVESCAN_KEYCLOAK_DB_USER="cvescan_keycloak_user"
CVESCAN_KEYCLOAK_DB_PASSWORD="CHANGE_ME"

CVESCAN_KEYCLOAK_ADMIN="CHANGE_ME"
CVESCAN_KEYCLOAK_ADMIN_PASSWORD="CHANGE_ME"

CVESCAN_KEYCLOAK_HOST="${CVESCAN_HOST}"         # don't end with /
CVESCAN_KEYCLOAK_REALM="cvescan"                # if you change this value make sure to update the `environment.*.ts` files in the webui project
CVESCAN_JWT_AUDIENCE="cvescan_web"              # if you change this value make sure to update the `environment.*.ts` files in the webui project


CVESCAN_WEBUI_HOST_URL="${CVESCAN_HOST}" # don't end with /

Important

Please replace all CHANGE_ME values before running the application. These values are critical for the security and functionality of the system.
All admin credentials specified in the .env file like the CVESCAN_API_ADMIN_EMAIL, CVESCAN_API_ADMIN_PASSWORD, CVESCAN_KEYCLOAK_ADMIN, CVESCAN_KEYCLOAK_ADMIN_PASSWORD and DB users and passwords are used only on the first run of the application. Changing these values after the initial setup will have no effect.

Note

The CVESCAN_HOST variable is used to set the base URL for the API, Keycloak and the WebUI. Make sure to replace your_domain_name with your actual domain name.
The CVESCAN_API_EXPOSE_SWAGGER variable is used to enable or disable exposing the openapi documentation for the API service. By default, it is set to false. If you want to expose the API documentation, set it to true. The API documentation will be available at the /api/openapi endpoint.
The CVESCAN_API_ADMIN_EMAIL and CVESCAN_API_ADMIN_PASSWORD variables are used to create the initial system admin user for the API server. You will use these credentials to log in to the WebUI and manage the application.
The CVESCAN_KEYCLOAK_ADMIN and CVESCAN_KEYCLOAK_ADMIN_PASSWORD variables are used to create the initial Keycloak admin user. This user will be used to access the Keycloak admin console.

Local setup

If you want to test the application locally, please set the CVESCAN_HOST variable to http://localhost

4. Setting Up Docker Volumes

Inside the docker-compose.yml file, you will find a number of volumes defined for the services. These volumes are used to persist data across container restarts and to share data between the host and the containers or the containers themselves.

While the docker-compose.yml file already defines all the necessary volumes, you may want to customize the volumes paths to suit your environment. For example, you may change the paths to store the data in a specific directory on your host machine. You can refer to the Docker compose volumes documentation for more information on how to configure volumes.

5. Starting Services

Once all configurations steps are complete, you can start all services using Docker Compose. Depending on your access to the CVEScan Web repository, you can either build the images from source code or use pre-built images from the registry.

Source code based approach: If you have access to the CVEScan Web source code repository, you can build and run the images from source code using:
```
docker compose up --build
```
Pre-built images access: If you only have access to the CVEScan Web Dist repository, or if you want to use the pre-built images, you will need to add the following variables to the .env file:
```
CVESCAN_REGISTRY=registry.gitlab.com/witekio/rnd/theembeddedkit/cvescan/cvescan-web-dist
CVESCAN_IMAGE_TAG=2.0.0 # You can change this to the desired version tag available in the registry
```
Then login to the registry using:
```
docker login registry.gitlab.com
```
You will be prompted for your GitLab credentials. As your repository access is managed through an access token, you may enter any value for the username, but you must provide your personal access token as the password to authenticate successfully.

Then you can start the services using the pre-built images:
```
docker compose up
```

Please be patient as this process may take some time, especially if it is the first time you are running the application. You need to wait until you see the api service logs indicating:

LOG [InitService] System initialized successfully.

Info

You will see some warnings in the logs related to the Keycloak service, stating the detection of a non-secure context. This is expected as the API service is communicating directly with Keycloak over HTTP within the Docker network as illustrated in the services overview.
The provided docker-compose.yml file is configured to automatically restart the services in case of failure or Docker daemon restart. This is done using the restart: always directive in the docker-compose.yml file.
The provided docker-compose.yml file is configured so that the database is not accessible from outside the compose network. If you want to access the database from outside the compose network, you will need to expose the database port in the docker-compose.yml and add the cvescan-external network to the database service. Another possibility is to adapt the NGINX configuration to proxy the database requests.

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.

Depending on your domain name, the protocol you are using (HTTP/HTTPS), the NGINX configuration, and the CVESCAN_API_EXPOSE_SWAGGER environment variable value, you can access the services at:

WebUI: (protocol)://(domain_name)/webui
API documentation (if exposed): (protocol)://(domain_name)/api/openapi
Keycloak Admin Console (if exposed): (protocol)://(domain_name)/auth/admin/

For example, if you are using HTTP and you are running the application on your local machine with the domain name localhost, you can access the services at:

WebUI: http://localhost/webui
API documentation (if exposed): http://localhost/api/openapi
Keycloak Admin Console (if exposed): http://localhost/auth/admin/