Custom Parameters for Containerized Scanner

The following section describes how to customize the parameters for the Containerized Scanner for SCP and PCP users.

SCP (Shared Cloud Platform) Users

Containerized Scanner with Proxy 

Users may need to use a proxy to connect with Qualys Platform Servers. Proxy configuration is supported in QCSA. Using -e https_proxy='<user>:<password>@<proxy ip/fqdn>:<proxy port>' or -e HTTPS_PROXY='<user>:<password>@<proxy ip/fqdn>:<proxy port>' parameters with docker run command, user can configure proxy on containerized scanner.

Sample

[root@localhost ~]# SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; docker run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e HTTPS_PROXY='user:[email protected]:8080' -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com qualys/qcsa
5caa4e9b18d51355573c168056037b92b326513be2b71e6de8c5055fb375bd7d
[root@localhost ~]#

In the above example, the containerized scanner is configured to use proxy IP 10.11.12.13 with port 8080 with proxy user authentication.

Proxy Password with Special Characters

QCSA depends upon the libcurl library for proxy configuration, which also includes the proxy parsing mechanism. With curl, special characters need to be hex encoded and passed with a % sign.

Example,

If you want to pass -e HTTPS_PROXY='user:qu@[email protected]:8080', and the proxy password is qu@lys.  Curl does not accept special characters written in plain text. You need to encode "@". Hex encoded value for special character "@" is 40. This Hex encoded value and a precede replaced with "@". Your password becomes qu%40lys. After encoding, the proxy configuration for user becomes -e HTTPS_PROXY='user:qu%[email protected]:8080'.

Refer the source ASCII Table to hex encode the special characters.

Custom Job Sync Interval

The containerized scanner's default Job Sync Interval is 30 seconds. Every 30 seconds, the containerized scanner syncs with Qualys Platform Servers and checks for Containerized Scanner jobs (scan, shutdown). This default frequency can be changed with the parameter, SCAND_POLL_INTERVAL_SEC, specified in units of seconds. The minimum limit for Job service polling interval is 30 Seconds and maximum limit is 180 seconds.

Use Environment Variables : -e SCAND_POLL_INTERVAL_SEC=<Interval in Seconds>

Sample

[root@localhost ~]# SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; docker run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e SCAND_POLL_INTERVAL_SEC=60 -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com qualys/qcsa
194c380fcc2dedfceb40cd3a6e38654f7dca0275d881512dc01f4b98e09fc41d
[root@localhost ~]#

The above example creates a Containerized Scanner with a Job Sync Interval of 60 Seconds.

Custom Updates Query Frequency

The containerized scanner's default Update service polling interval is 30 minutes. Every 30 minutes, the Containerized Scanner checks for Qualys Scanning Engine Packages updates. If new updates are available, Containerized Scanner downloads and installs them on the Linux host's shared storage for Containerized Scanners. This default frequency can be changed with the parameter, UPDATE_INTERVAL_MIN, specified in units of minutes. The minimum limit for the Update service polling interval is 30 Minutes, and the maximum limit is 240 Minutes.

Use Environment Variables : -e UPDATE_INTERVAL_MIN=<Interval in Minutes>

Sample

[root@localhost ~]# SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; docker run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e UPDATE_INTERVAL_MIN=31 -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com qualys/qcsa
4b6bb82b6bc24494531b0b8f27eddf9f27a9d6fb76fa4c2ef36cf7c5b79bafee
[root@localhost ~]#

The above sample creates a Containerized Scanner with an update service polling interval of 31 Minutes.

Custom Config Sync Interval

Containerized Scanner's default Config Sync Interval is 10 minutes. Every 10 minutes, the Scanner syncs with the Qualys Platform. This is a keep-alive frequency for the scanner. At this frequency, the scanner communicates with the Qualys platform server to stay active and maintain its validity. This default frequency can be changed by the parameter REFRESH_INTERVAL_MIN, which is specified in units of minutes. The minimum limit for Config Sync Interval is 10 Minutes, and the maximum limit is 360 Minutes.

Use Environment Variables: -e REFRESH_INTERVAL_MIN=<Interval in Minutes>

Sample

[root@localhost ~]# SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; docker run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e REFRESH_INTERVAL_MIN=11 -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com qualys/qcsa
baa54f6f307d30d2e0ba77146321ad5c5ad1fe4d72516f1e3b8f58695a62090b
[root@localhost ~]#

In the above example, Containerized Scanner is created with a Config Sync Interval of 11 Minutes.

Containerized Scanner with IPv6

Supports IPv6 Networking on containerized scanners.
For details on IPv6 documentation, refer to the Enable IPv6 support section of the official Docker IPv6 Documentation. Once the IPv6 network is created, it can be assigned to the Container Scanner using --network <IPv6 Network/Subnet name>.

Sample

[root@localhost ~]# docker network ls
NETWORK ID     NAME      DRIVER    SCOPE
ae4f1f41d022   bridge    bridge    local
ee96e6fb83c9   host      host      local
959ceb01ca0e   ip6net    bridge    local
a41e0d5cb73e   none      null      local
[root@localhost ~]#
[root@localhost ~]# SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; docker run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" --network ip6net -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com qualys/qcsa
51a3ac7f05a80f8bffd91d71709edb5078bbeee76e5cf416e0c1849b4ce3baea
[root@localhost ~]#

Scanner in 64-bit Only Mode (Beta)

QCSA containerized scanners in 64-bit only mode can be created/run on a pure 64-bit environment and on a FIPS-enabled Linux host. To run the containerized scanner in 64-bit mode only, users must set the environment variable by including '-e ALLOW_32BIT=no' in the containerized scanner creation command.

Sample

[root@localhost ~]# SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=70631574310463; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; docker run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name $NAME -e ALLOW_32BIT=no -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com qualys/qcsa
9b65d34279e224320f30b39f2d5c57bb6efc47d578d5e5b676ebb59d8c6eacfe
[root@localhost ~]#
  • This feature is in Beta. Containerized scanner in this mode limits support for certain target technologies within its scanning capabilities.
  • Shared resources for 32-bit and 64-bit scanning engines must be kept separate. Users should create dedicated shared directories for containerized scanners based on the ALLOW_32BIT setting (ALLOW_32BIT=no and ALLOW_32BIT=yes).
  • Before re-running an existing containerized scanner in a different mode (for example, switching from standard mode to 64-bit only or vice versa), ensure that all contents of the Shared directory are deleted. This step must be performed before executing the command to restart the containerized scanner. The contents of the Private directory should remain unchanged.

PCP (Private Cloud Platform) Users

PCP users must provide the Root CA when they run the containerized scanner creation command. This ensures the scanner can establish a secure connection with Qualys Enterprise TruRisk™ Platform Servers. If you need assistance with the Root CA, contact Qualys Technical Support.

Containerized Scanner Creation with Custom Root CA (PCP Users)

Follow these steps to create a containerized scanner:

  1. Create a directory on the Linux Host to store the Root CA certificate file.
  2. Rename the Root CA certificate file to rootcert.pem.

    Sample

    [root@localhost ~]# ls -l /root/rootcert/
total 24
-rw-r--r--. 1 root root 22785 Aug  3  2024 rootcert.pem
[root@localhost ~]#

    The above example creates a rootcert directory to store the certificate file. Users can select their preferred directory and file path based on their requirements.

  3. Mount the directory with rootcert.pem while creating a containerized scanner. 
  4. Use the parameter -v ~/<Path to Directory with rootcert.pem with custom Root CA certificate file>:/usr/local/bin.
    Refer the following example, 

    Sample

    SHARED_DIRECTORY=/usr/qualys/shared; PRIVATE_DIRECTORY=usr/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; docker run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -v /root/rootcert:/usr/local/bin:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com qualys/qcsa

    /root/rootcert is the directory where rootcert.pem is present, and /usr/local/bin is where the certificate file with Root CA Certificate file must be mounted on the Containerized Scanner.

 

  • Qualys strongly recommends against running a containerized scanner in rootless mode, as it may impact scan performance and the consistency of vulnerability results.

  • The sample commands utilize Docker Engine as the container runtime, but they can also be executed using Podman.

  • A low cgroups PID limit (total number of processes and threads to run inside a container) on linux host, may prevent the QCSA containerized scanner from executing larger scans. Running Containerized scanner with option '--pids-limit -1' this pids limit can be removed or running Containerized scanner with option '-e DISREGARD_PID_LIMIT=yes' will override the pids limit check.

  • For more details on command options provided by container runtimes (Docker/Podman), refer to the official Docker or Podman documentation.

For detailed information on the QCSA command parameters used in examples, refer to Containerized Command Components.

Next Step

Step 6: Stop and Re-run Containerized Scanner

 

© 2025 Qualys, Inc. All rights reserved. Privacy Policy. Last updated: September, 2025