Create Containerized Scanner

Qualys recommends executing the following command as the 'root' user. Qualys also recommends against running the containerized scanner in rootless mode, as it may impact scan performance and the consistency of vulnerability results.

Sample

SHARED_DIRECTORY=<Absolute Path to Shared Directory>; PRIVATE_DIRECTORY=<Absolute Path to Private Directory>;PERSONALIZATION_CODE=<Personalization code generated from Qualys Subscription>; NAME=<Containerized Scanner Name>; 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 QUALYS_URL=https://<qualysguard endpoint mentioned in Security Operations Center (SOC)> <QCSA IMAGE ID>

QCSA Containerized Scanner Command Components

Refer to the following table for Containerized command components.

Command Components	Description
SHARED_DIRECTORY	The variable in which the absolute path to the shared directory is stored.
PRIVATE_DIRECTORY	The variable in which the absolute path to the private directory is stored.
PERSONALIZATION_CODE	The variable where the personalization code is stored.
NAME	The variable where the name of the containerized scanner is stored.
mkdir -p	A command is used to create directories. In the context of containerized scanner creation, this command ensures the creation of the private directory required for the scanner, including any necessary parent directories.
docker run -d	The command is used to start a container in detached mode.
-v $SHARED_DIRECTORY:/usr/local/qualys:z	This command is used to bind mount a shared directory at /usr/local/qualys on the containerized scanner.
-v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE: /usr/local/qualys/admin/etc:z	This command binds and mounts a private directory at /usr/local/qualys/admin/etc on a containerized scanner.
-e PERSONALIZATION_CODE=$PERSONALIZATION_CODE	This command passes the previously declared PERSONALIZATION_CODE variable as an environment variable to the containerized scanner.
--name "$NAME"	The previously declared variable NAME is passed to the containerized scanner creation command using the --name option.
-e QUALYS_URL	The environment variable is declared with the first endpoint mentioned in the Security Operations Center (SOC).

When the QCSA containerized scanner creation command executes successfully, Docker or Podman generates an alphanumeric ID to confirm the container's creation. If the command fails, an error message is typically displayed instead.

The scanning capacity of a containerized scanner depends on the memory and CPUs assigned to it. Based on the resource assignment, a containerized scanner can be categorized as unlimited or limited.

Unlimited Containerized Scanner
The Containerized Scanner can use all available resources on the docker host if resource preferences such as memory, swap, and CPUs are not provided. Such a Scanner is termed an Unlimited Containerized Scanner.

Limited Containerized Scanner
You can allocate preferred resources to the Containerized Scanner, which is called a Limited Containerized Scanner.

Unlimited Containerized Scanner

When memory, swap and CPU preferences are not provided, Containerized Scanner uses all the resources available on the docker host.

Use the following example of a command to create an Unlimited Containerized Scanner. After execution of the command, the container ID is printed, and the containerized scanner is launched in detached mode.

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 PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com 6715167e4412
babd3b78c598417dfc07a701dbd20d318afc82af524a41e67b3af5932f41c1be
[root@localhost ~]#

Look up the QUALYS_URL required to execute the command and see Prerequisites for Creating Containerized Scanner for detailed steps. Contact your Qualys Technical Account Manager (TAM) if you need help verifying the POD URL.
Refer to QCSA Image Configuration in Docker Host to retrieve the QCSA IMAGE ID.

Limited Scanner

You can provide resource preferences for the Containerized Scanner, including memory, swap, and the number of CPUs. The user can divide the Linux host's resources and create multiple Containerized Scanners.

The following parameters can be used to provide preferred resources:

Parameter	Description
--memory	Memory (RAM) is to be allocated to the containerized scanner.
--memory-swap	The total value of the memory + swap is to be allocated to the containerized scanner. If memory is provided with 1024M and memory-swap is supplied with 2048M, then Containerized Scanner gets 1024M of Swap.
--cpus	The total number of CPUs is to be allocated to the containerized scanner.

Use the following sample command to create a Limited Containerized Scanner. After executing the command, a Container ID is printed, and the containerized scanner is launched in detached mode.

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 PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" --memory 1024M --memory-swap 2048M --cpus 1 -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com 6715167e4412
2e6a4c0c0479e9bab8232c71f4be21aedcbcb025809125b80788d500d304031e
[root@localhost ~]#

Containerized Scanner Scanning Capacity is calculated based on the total memory, swap and CPUs allocated to Containerized Scanner.

The resources allocated to all containerized scanners must not exceed the total resources available on the Linux Host.
Directory paths /usr/qualys/shared and /usr/qualys/private are arbitrary; users can define other directory paths of choice.
Do not overcommit the resources. Overcommitting may cause the Container or the host to malfunction. For example, a lack of sufficient swap on the Linux host could lead to guest user operating systems being forcibly shut down, leaving the guests inoperable.

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 can also be executed using Podman.
A low cgroups PID limit (total number of processes and threads to run inside a container) on a 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 detailed information on the QCSA command parameters used in examples, refer to Containerized Command Components.

Next Step

Step 5: Custom Parameters for Containerized Scanner