On-Premises Deployment of Web App Scanning - Scanner

Objective

In this article, we will provide a practical guide to set up and run scanner instances of F5® Distributed Cloud Web App Scanning in an on-premises environment using Docker.

Prerequisites

To deploy and run a scanner instance of 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 (equivalent to Intel Skylake, AMD Zen, or later), 16 GB RAM, and at least 100 GB available disk space.

Moreover, you need SSH access to your virtual machines and the necessary permissions to run Docker containers.

Certificates

If the TLS certificate used by the web server F5® Distributed Cloud Web App Scanning is not issued by a trusted Certificate Authority, the root certificate(s) of the internal CA(s) must be placed in a folder accessible by Docker. The folder must mounted to /etc/ssl/certs in the Docker container running the scanner instance.

Docker Compose

Starting and running the scanner instance can be done with one single command:

• sudo docker compose up -d

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

services:
  heyhack:
    image: europe-docker.pkg.dev/heyhack/on-prem/scanner-core
    container_name: heyhack-scan
    restart: always
    network_mode: "host"
    environment:
      - WebApiHost=https://<HOSTNAME>
      - WebApiToken=<HEYHACK_API_KEY>
      - RunForever=True
      - EnableRecon=False
      - IsOffline=True
      - IsOnPrem=True
      - MaxScanWorkers=<MAX_SCAN_WORKERS>
      - DisableStrictTLSValidation=False
    volumes:
      - <PATH_TO_ROOT_CERT>:/etc/ssl/certs:ro

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.

Deployment

The scanner instance should be deployed in a network configuration that allows the scanner to access the target web applications that you would like to scan. It must also be able to make HTTP(S) requests to the web server of F5® Distributed Cloud Web App Scanning in order to collect and store scanning results (e.g., found vulnerabilities, screenshots, videos, etc.).

To test that your network configuration has been set up correctly, you can log into the virtual machine of the scanner instance via SSH and make requests to both your target web application(s) and the web server of F5® Distributed Cloud Web App Scanning using a tool like curl. If you get successful responses from such requests, the scanner will be able to fetch scan jobs, scan targets, and store results.

Support

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