On-Premises Deployment of Web App Scanning - Web Server

Objective

In this article, we provide a practical guide to set up and install the web server of F5® Distributed Cloud Web App Scanning in an on-premises environment using Docker.

Prerequisites

To deploy and run F5® Distributed Cloud Web App Scanning in an on-premises environment, you need the following prerequisites:

• Access to F5® Distributed Cloud Web App Scanning's Docker images. There is one for our web server and one for the scanner itself. Please contact your Technical Account Manager at F5 to get access to these.
  • Name of web server image: europe-docker.pkg.dev/heyhack/on-prem/web
  • Name of scanner core image: europe-docker.pkg.dev/heyhack/on-prem/scanner-core
• A virtual machine running Linux (x64) with the latest version of the Docker runtime installed. You also need the Docker Compose utility to use the configuration provided in this guide.
  • We recommend at least 4 vCPUs (based on a CPU architecture equivalent to Intel Skylake, AMD Zen, or later), 16 GB RAM, and at least 1 TB available disk space.
• A Microsoft Entra ID tenant with an app registration for F5® Distributed Cloud Web App Scanning.
• A Microsoft Entra ID security group. Members of your chosen security group will be able to access your F5® Distributed Cloud Web App Scanning instance.
• A valid TLS certificate for your desired hostname (to be used by the web server).

Additionally, you need SSH access to your virtual machine and the necessary permissions to create folders and run Docker containers.

Configuration of Microsoft Entra ID

The on-premises edition of F5® Distributed Cloud Web App Scanning makes use of Microsoft Entra ID for authentication and authorization of users. You must create an app registration in your Microsoft Entra ID tenant with the following API permissions:

• User.Read (Microsoft Graph)
  • Type: Delegated
  • Requires User consent.
• User.ReadBasic.All (Microsoft Graph)
  • Type: Application
  • Requires User consent.
• GroupMember.Read.All (Microsoft Graph)
  • Type: Application
  • Requires Admin consent.

Token Configuration

You must add a groups claim on the Token configuration page in the Microsoft Entra ID management portal. Select Security groups and set the ID, Access, and SAML token properties to Group ID. Click on Save.

Authentication

On the Authentication page, you must add a Web platform and include the following redirect URI:

• https://<YOUR_HOSTNAME>/callback-ad

Replace <YOUR_HOSTNAME> with the hostname of the virtual machine running the web server of F5® Distributed Cloud Web App Scanning.

Under Implicit grant and hybrid flows, the option ID tokens must be checked and Supported account types should be set to Accounts in this organizational directory only (MSFT only - Single tenant).

Directory ID, Client ID, and Client Secret

Finally, you must create a client secret on the Certificates & secrets page. Select Client secrets and click on New client secret. Provide a suitable name for the secret and choose an expiry date that complies with your organization's policy on key management/rotation. Create the secret and note down the value, which is to replace <AZURE_AD_SECRET> in the Docker Compose configuration outlined below.

Also, note down the Application (client) ID (which is to replace <AZURE_AD_CLIENT_ID>) and the Directory (tenant) ID (which is to replace <AZURE_AD_TENANT_ID>) on the Overview page.

Authorizing Users

To enable access to F5® Distributed Cloud Web App Scanning for certain users in your organization, you must create a security group in your Microsoft Entra ID tenant. Members of this security group will be able to log into the web interface of F5® Distributed Cloud Web App Scanning. Note down the ID of the security group (which is to replace <AZURE_AD_GROUP_ID>).

Hostname and TLS Certificate

You must assign a hostname and a valid TLS certificate for the virtual machine. The TLS certificate must be stored in the PKCS #12 format (as a .pfx file) with a password. Both the path to the certificate and its password must be provided to the web server of F5® Distributed Cloud Web App Scanning as environment variables.

It is recommended to create a folder named /https on the virtual machine hosting the web server. Make sure that the Docker daemon has read access to files in this folder. Place the .pfx file inside the folder. In the Docker Compose configuration, replace <PATH_TO_PFX> with the full path of the .pfx file (e.g., /https/mycertificate.pfx). Replace <PFX_PASSWORD> with the password of the .pfx file.

Data

F5® Distributed Cloud Web App Scanning requires two drives/folders to be mounted into the web application server. The first folder should be called /https and must contain the .pfx file that holds the TLS certificate to be used by the server. The second folder should be called /data and will hold all data generated by the scanner in F5® Distributed Cloud Web App Scanning. Ideally, this folder should be a network drive that is continuously backed up in line with your organization's backup policy.

Both folders will be mounted into the container running the web server. The Docker daemon must have read access to the /https folder and full access to the /data folder.

Docker Compose

Starting and running the web server of F5® Distributed Cloud Web App Scanning can be done with one single command:

• sudo docker compose up -d

This command will start Docker containers for the web server of F5® Distributed Cloud Web App Scanning, a PostgreSQL server, a Redis server, and a pgAdmin server. The Docker containers will automatically be restarted in case the host VM is rebooted.

The Docker Compose command relies on the following docker-compose.yaml file:

services:
  heyhack:
    image: europe-docker.pkg.dev/heyhack/on-prem/web
    container_name: onprem-was
    restart: always
    ports:
      - '80:80'
      - '443:443'
    depends_on:
      - postgres
      - redis
    environment:
      - ASPNETCORE_URLS=https://+:443;http://+:80
      - ASPNETCORE_Kestrel__Certificates__Default__Password=<PFX_PASSWORD>
      - ASPNETCORE_Kestrel__Certificates__Default__Path=<PATH_TO_PFX>
      - AzureAdAuthority=https://login.microsoftonline.com/<AZURE_AD_TENANT_ID>
      - AzureAdClientId=<AZURE_AD_CLIENT_ID>
      - AzureAdSecret=<AZURE_AD_SECRET>
      - AzureAdSecurityGroup=<AZURE_AD_GROUP_ID>
      - ApiKey=<WAS_API_KEY>
      - "App:BaseUrl=https://<HOSTNAME>"
    volumes:
      - /https:/https:ro
      - /data:/data

  postgres:
    image: postgres:14
    container_name: onprem-postgres
    restart: always
    environment:
      - POSTGRES_USER=heyhack
      - POSTGRES_PASSWORD=rainmaking
      - POSTGRES_DB=heyhack
    ports:
      - '5432:5432'
    volumes: 
      - /data/postgres:/var/lib/postgresql/data

  pgadmin:
    image: dpage/pgadmin4
    container_name: onprem-pgadmin
    restart: always
    ports:
      - "5050:80"
    environment:
      PGADMIN_DEFAULT_EMAIL: heyhack@heyhack.com
      PGADMIN_DEFAULT_PASSWORD: admin
    volumes:
      - /data/pgadmin:/var/lib/pgadmin

  redis:
    image: redis:7
    container_name: onprem-redis
    restart: always
    ports:
      - "6379:6379"
    command: redis-server --save 20 1 --loglevel warning
    volumes: 
      - /data/redis:/data

Replace the following placeholders with appropriate values in the Docker Compose file:

Refer to Docker's documentation for more information about how to define and run Docker Compose.

First Use

Once the web server has been set up and is confirmed to be running, you can access the web interface at the hostname you provided. You must ensure that you are a member of the Microsoft Entra ID security group to access the web interface.

We recommend you invite your colleagues by:

• Adding them to your Microsoft Entra ID security group,
• Reviewing the members of your team on the Members page at https://<HOSTNAME>/members (replace <HOSTNAME> with the hostname of the virtual machine running the web server), and
• Configuring their global roles and their group memberships in F5® Distributed Cloud Web App Scanning.

Make sure that you have set up at least one scanner instance before starting your first penetration test. Please refer to our article on setting up the scanner in F5® Distributed Cloud Web App Scanning.

Limitations

The on-premises version of F5® Distributed Cloud Web App Scanning operates the same as the cloud-hosted version available in F5® Distributed Cloud Services, with one notable exception: the Recon service is disabled. It is not available in the user interface or via the APIs. Any request sent to Recon-related API endpoints will result in a 403 Forbidden response.

The Recon service makes thousands of DNS requests and communicates with third-party services when conducting a Recon job on a given domain. Issuing these requests from a single IP address on your corporate network is not recommended, as DNS servers and third-party services may eventually block your corporate network, leading to disruptions for users.

If you need to run Recon jobs, we recommend using the cloud-hosted version of F5® Distributed Cloud Services in parallel with your on-premises environment. For further assistance, please contact your F5 Technical Account Manager.

Support

For any questions regarding the installation of F5® Distributed Cloud Web App Scanning in an on-premises environment, please contact our support team.