On Prem

DNS Binding and Setup

After ZeroThreat On-Prem is installed, the installer displays a local access URL for your instance. This is useful for initial access, but for regular usage, you should bind the instance to a supported domain and serve it over HTTPS. The guide already assumes that successful onprem installation setup.

This page explains how to bind a domain to your installed ZeroThreat On-Prem instance using Nginx as a reverse proxy and mkcert for locally trusted HTTPS certificates.

Reverse proxy choice
This guide uses Nginx as an example. You can also use Apache, an internal load balancer, an ingress controller, or any other reverse proxy that can route HTTP/HTTPS traffic to your ZeroThreat On-Prem instance.
The goal is the same regardless of tool: resolve a supported domain inside your network, proxy traffic to the local ZeroThreat instance, and configure HTTPS.

Domain Requirements for ZeroThreat Chrome Extension

The ZeroThreat Chrome Extension will only open or load correctly when the On-Prem instance is bound to one of the supported domain patterns.

Supported domain patterns:

https://*.websec.ai/*
https://*.webpentest.ai/*
https://*.webscan.ai/*
https://*.dastscan.ai/*
https://*.websectest.ai/*
https://*.apiscan.ai/*
https://*.apiscantest.ai/*

For On-Prem setups, this domain should be configured inside your private network DNS. For example, your internal DNS can resolve a supported domain such as:

local.zerothreat.webscan.ai

to the private IP address of your ZeroThreat On-Prem server.

Extension compatibility
The ZeroThreat Chrome Extension will only open or load when the On-Prem instance is bound to a supported domain pattern. We recommend using one of the supported domains listed above.
If you have an exceptional requirement to use a different domain, contact the ZeroThreat support team.

Google and Microsoft SSO Domain Whitelisting

If you want Login with Google or Login with Microsoft to work on your On-Prem domain, you will have to share the final domain name with the ZeroThreat support team.

The domain must be whitelisted by ZeroThreat before Google or Microsoft SSO can work correctly for your On-Prem instance.

Example domain to share:

https://local.zerothreat.webscan.ai
SSO setup requirement
For Google or Microsoft SSO, send your On-Prem domain to ZeroThreat support for whitelisting. Without this step, SSO login may not work even if DNS and HTTPS are configured correctly.

Before You Start

Before binding a domain, make sure your ZeroThreat On-Prem installation is complete and the instance is accessible through the local URL shown by the installer.

You should also have:

  • A supported internal domain or subdomain, such as company.webscan.ai or company.websec.ai
  • Access to your internal DNS system.
  • Server access with sudo privileges.

The local ZeroThreat On-Prem URL or port shown after installation. You will use this value in the Nginx proxy_pass configuration.

Access to update internal firewall rules if required.

Step 1: Install Nginx

Install Nginx on the server where ZeroThreat On-Prem is running.

sudo apt update
sudo apt install nginx

Once installed, verify that Nginx is running:

sudo systemctl status nginx

Nginx supports reverse proxying requests to backend services using proxy_pass, which is what allows the supported domain to route traffic to the local ZeroThreat service.

Step 2: Configure Local Firewall Rules

Allow SSH first so you do not accidentally lock yourself out of the server.

sudo ufw allow OpenSSH

Allow Nginx HTTP traffic:

sudo ufw allow 'Nginx HTTP'

Enable the firewall:

sudo ufw enable

Check firewall status:

sudo ufw status

At this stage, HTTP traffic on port 80 should be allowed on the server.

If your organization uses additional internal firewalls or network ACLs, make sure traffic to ports 80 and 443 is allowed from the intended internal network ranges.

Step 3: Add the Internal DNS Record

In your internal DNS system, create an A record for the supported domain or subdomain you want to use.

Example:

Type: A
Name: company
Value: <zeroThreat-onprem-private-ip>
TTL: Auto or default

For example, this points:

company.webscan.ai

to your ZeroThreat On-Prem server’s private IP address.

After adding the record, verify that the domain resolves correctly from a machine inside the intended network.

dig company.webscan.ai

or:

nslookup company.webscan.ai

Make sure the domain resolves to the expected private IP before continuing.

The domain must resolve correctly from the machines where users will access ZeroThreat On-Prem. If users connect through VPN, verify DNS resolution from a VPN-connected machine as well.

Step 4: Configure Nginx Reverse Proxy

Create an Nginx site configuration for your domain.

sudo nano /etc/nginx/sites-available/zerothreat

Add a configuration similar to the following.

Replace company.webscan.ai with your actual supported domain.

Replace http://127.0.0.1:3203 with the local ZeroThreat URL or port shown after installation.

Increase Upload Size Limit
Some ZeroThreat On-Prem features require uploading project or template files through the portal. For example, Application Journeys / Playwright ZIP upload and Custom Attack Coverage ZIP upload may involve files larger than the default Nginx request body limit.
By default, Nginx limits the client request body size to 1 MB. If an uploaded file exceeds this limit, Nginx can reject the request with a 413 Request Entity Too Large error before it reaches ZeroThreat. Nginx supports increasing this limit using the client_max_body_size directive inside the http, server, or location block. If you are using HTTPS, add the same directive inside the HTTPS server block as well.
Note: If you are using Apache, an internal load balancer, an ingress controller, or another reverse proxy instead of Nginx, configure the equivalent request body or upload size limit there as well. Otherwise, large ZIP uploads may fail even if ZeroThreat itself supports the file size.
server {
    listen 80;

    server_name company.webscan.ai;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:3203;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Nginx reverse proxy configuration uses proxy_pass to forward requests to the backend service, and proxy_set_header can be used to pass the original host, client IP, and protocol details to the proxied service.

Enable the site:

sudo ln -s /etc/nginx/sites-available/zerothreat /etc/nginx/sites-enabled/

Test the Nginx configuration:

sudo nginx -t

Reload Nginx:

sudo systemctl reload nginx

Now open the domain in the browser from inside your network:

http://company.webscan.ai

If DNS and proxy configuration are correct, the domain should route to your ZeroThreat On-Prem instance.

Step 5: Install mkcert

For internal HTTPS, this guide uses mkcert. mkcert creates a local Certificate Authority and generates locally trusted certificates for development or internal domains. The official mkcert project states that it creates and installs a local CA in the system trust store and generates locally trusted certificates, but it does not configure servers automatically.

Install the required NSS tools first:

sudo apt update
sudo apt install libnss3-tools

Install mkcert.

On Ubuntu/Debian systems where mkcert is available from the package repository, you can use:

sudo apt install mkcert

If your package repository does not provide mkcert or provides an older version, install it from the official mkcert GitHub releases according to your OS and architecture.

Verify installation:

mkcert -version

Install the local CA on the server:

mkcert -install
Client trust requirement
Running mkcert -install on the server trusts the mkcert root CA on that server. For browsers on user machines to trust the certificate, the mkcert root CA must also be trusted on those user machines, or your organization should use its own internal CA certificate.
If the CA is not trusted on the user’s machine, the browser may show a certificate warning even though Nginx is correctly configured.

Step 6: Generate a Local HTTPS Certificate

Create a directory to store certificates:

sudo mkdir -p /etc/nginx/ssl/zerothreat

Generate a certificate for your supported domain:

sudo mkcert \
  -key-file /etc/nginx/ssl/zerothreat/company.webscan.ai-key.pem \
  -cert-file /etc/nginx/ssl/zerothreat/company.webscan.ai.pem \
  company.webscan.ai

This creates a certificate and private key for:

company.webscan.ai

Restrict access to the private key:

sudo chmod 600 /etc/nginx/ssl/zerothreat/company.webscan.ai-key.pem
If you need the certificate to support more than one internal hostname, include all required names in the same mkcert command.
Example:
sudo mkcert \
  -key-file /etc/nginx/ssl/zerothreat/zerothreat-key.pem \
  -cert-file /etc/nginx/ssl/zerothreat/zerothreat.pem \
  company.webscan.ai company.websec.ai

Step 7: Configure Nginx for HTTPS

Update the Nginx site configuration:

sudo nano /etc/nginx/sites-available/zerothreat

Replace the existing configuration with the following.

Update company.webscan.ai and http://127.0.0.1:3203 as needed.

server {
    listen 80;
    server_name company.webscan.ai;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name company.webscan.ai;

    ssl_certificate /etc/nginx/ssl/zerothreat/company.webscan.ai.pem;
    ssl_certificate_key /etc/nginx/ssl/zerothreat/company.webscan.ai-key.pem;

    location / {
        proxy_pass http://127.0.0.1:3203;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Nginx HTTPS configuration requires SSL to be enabled on the listening socket and requires the server certificate and private key paths to be specified in the server block.

Test the Nginx configuration:

sudo nginx -t

Reload Nginx:

sudo systemctl reload nginx

Allow HTTPS through UFW:

sudo ufw allow 'Nginx Full'
sudo ufw status

Now open the domain from inside your network:

https://company.webscan.ai

Your ZeroThreat On-Prem instance should now be accessible over HTTPS.

Step 8: Trust the mkcert Root CA on User Machines

For the certificate to appear trusted in user browsers, the CA that issued the certificate must be trusted by those machines.

On the server where you generated the certificate, find the mkcert CA location:

mkcert -CAROOT

This directory contains the local root CA files. The file commonly used for trust distribution is:

rootCA.pem

Your IT team can distribute and trust this CA certificate on the machines that need to access the On-Prem instance.

Protect the root CA private key
Do not distribute the root CA private key. Only distribute the CA certificate required for trust.
If your organization already has an internal certificate authority, using that internal CA is usually preferred for managed environments.

After the CA is trusted on a user machine, restart the browser and open:

https://company.webscan.ai

The certificate should now be trusted.

Common Checks

If the domain does not open correctly, check DNS first:

dig company.webscan.ai

or:

nslookup company.webscan.ai

Check that Nginx configuration is valid:

sudo nginx -t

Check that Nginx is running:

sudo systemctl status nginx

Check that firewall rules allow Nginx traffic:

sudo ufw status

Confirm HTTPS is listening locally:

curl -k https://company.webscan.ai

If the local ZeroThreat URL does not respond from the server, fix the local ZeroThreat service or port configuration before debugging DNS or Nginx.

If the HTTPS page opens with a certificate warning, confirm that the issuing CA is trusted on the client machine.

What’s Next?

After DNS binding and HTTPS setup are complete, users can access ZeroThreat On-Prem through the configured supported domain from the intended internal network.