Running CVEScan Web

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_buffer_size 32k;
        proxy_buffers 4 32k;
        proxy_busy_buffers_size 64k;

        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;
    }
}

Not using Keycloak as the identity provider

CVEScan supports using Okta and Microsoft Entra ID as alternatives to Keycloak for authentication.

If you are not using Keycloak, please remove the location /auth/ block from nginx.conf.

Not using Keycloak as the identity provider

Notes:

• CVEScan does not manage non keycloak users. This means that creating, editing or deleting users in CVEScan will not impact their account in the identity provider.
• CVEScan does not grant access to every user registered in the identity provider. A system administrator must add authorized users and assign them roles from the users page at https://your_domain_name/webui/-/users.

If you want to use Okta or Microsoft Entra ID instead of Keycloak, follow the subsection for your provider as described below.

Okta

1. Register an Application

   Create an application in Okta by navigating to the Applications section and clicking on "Create App Integration". Configure the application with the following settings:

   Setting	Value
   Sign-in method	OIDC - OpenID Connect
   Application type	Single Page Application
   App integration name	Provide a name for your application (e.g. "CVEScan Web")
   Grant type	Authorization code & Refresh token
   Sign-in redirect URI	https://your_cvescan_domain_name/webui/login
   Sign-out redirect URI	https://your_cvescan_domain_name/webui/login
   Assignments (Controlled access)	Configure this the way it suits your needs

2. Register an Authorization Server

   Create an Authorization Server in Okta by navigating to the API section under Security and clicking on "Add Authorization Server". Configure the Authorization Server with the following settings:

   Setting	Value
   Name	Provide a name for your application (e.g. "CVEScan Web API")
   Audience	Provide a meaningful unique audience for the authorization server (e.g. "cvescan_web" or the URL of CVEScan API)
   Description	Provide a description for the authorization server (e.g. "Authorization server for CVEScan Web")

   Once the Authorization Server is created, navigate to the Access policies section and click on "Add Access Policy". Configure the access policy with the following settings:

   Setting	Value
   Name	Provide a name for your access policy (e.g. "CVEScan Web Policy")
   Description	Provide a description for your access policy (e.g. "Access policy for CVEScan Web")
   Assign to	Choose "The following clients" and type the name of the application you created in the previous step

   After creating the access policy, a rule must be created using the "Add Rule" button.

   Setting	Value
   Rule name	Provide a name for your rule (e.g. "CVEScan Web Rule")
   Grant type	Authorization code
   User is	You can opt for "Any user assigned the app" and manage the users from the application settings
   Scopes requested	The following scopes: openid, email and offline_access

3. Edit the .env file

   • Set CVESCAN_API_ADMIN_EMAIL to the email address of the user who will be the initial system administrator.
   • Remove CVESCAN_API_ADMIN_PASSWORD from your .env file, as it is not needed. The initial admin will log in using their Okta account (with the email specified above).
   • Replace the entire authentication section in your .env file with the values below, and substitute CHANGE_ME with the corresponding values (all values can be found in the Okta Applications and API pages):

   # authentication
   CVESCAN_API_IDP="okta"
   CVESCAN_OKTA_CLIENT_ID="CHANGE_ME"                  # Client ID of the Okta application created in step 1
   CVESCAN_OKTA_AUTH_SERVER_ISSUER_URI="CHANGE_ME"     # The issuer URI of the authorization server created in step 2
   CVESCAN_JWT_AUDIENCE="CHANGE_ME"                    # The audience value from the authorization server created in step 2
   CVESCAN_JWT_ISSUER="${CVESCAN_OKTA_AUTH_SERVER_ISSUER_URI}"  # no need to change this
   CVESCAN_JWT_CLIENT_ID="${CVESCAN_OKTA_CLIENT_ID}"            # no need to change this
   CVESCAN_JWKS_URL="${CVESCAN_OKTA_AUTH_SERVER_ISSUER_URI}/v1/keys"    # no need to change this
   

Microsoft Entra ID

1. Register the application in Entra ID

   • Register a Single Page Application.
   • Add the redirect URL: https://your_domain_name/webui/login
   • Set the access token version to v2 by adding "requestedAccessTokenVersion": 2 to the application manifest (doc)
   • Add the optional claim email to the access token (doc)

2. Edit the .env file

   • Set CVESCAN_API_ADMIN_EMAIL to the email address of the user who will be the initial system administrator.
   • Remove CVESCAN_API_ADMIN_PASSWORD from your .env file, as it is not needed. The initial admin will log in using their Microsoft account (with the email specified above).
   • Replace the entire authentication section in your .env file with the values below, and substitute CHANGE_ME with the corresponding values from your Entra ID application:

   # authentication
   CVESCAN_API_IDP="entra-id"
   CVESCAN_ENTRA_ID_TENANT_ID="CHANGE_ME"   # Tenant ID of your Entra ID application
   CVESCAN_ENTRA_ID_CLIENT_ID="CHANGE_ME"   # Client ID of your Entra ID application
   CVESCAN_ENTRA_ID_TENANT_URL="https://login.microsoftonline.com/${CVESCAN_ENTRA_ID_TENANT_ID}"
   CVESCAN_JWT_AUDIENCE="${CVESCAN_ENTRA_ID_CLIENT_ID}"
   CVESCAN_JWT_ISSUER="${CVESCAN_ENTRA_ID_TENANT_URL}/v2.0"
   CVESCAN_JWT_CLIENT_ID="${CVESCAN_ENTRA_ID_CLIENT_ID}"
   CVESCAN_JWKS_URL="${CVESCAN_ENTRA_ID_TENANT_URL}/discovery/v2.0/keys"
   

Local setup

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

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.