Deploying the Sensor on Standalone Docker host using a Container Runtime

Prerequisites: Docker engine version: 1.13.0+

Login to the Qualys Cloud Platform > Container Security > Configurations > Sensors and click Download Sensor.
Choose the sensor type (General, Registry, CI/CD) and then the Standalone technology: MacOS, Linux or CoreOS. The Installation Instructions page appears. Pick the DOCKERHUB tab to see installation steps.
Refer to the following sections to install the respective sensor.
General Sensor Installation
Registry Sensor Installation
CI/CD Sensor Installation

The installation command on the Installation Instructions screen contains your Activation ID and Customer ID. Activation ID is like a password, do not share it.

To meet compliance with CIS Benchmark 5.9, you must remove --net=host from
the installation command. Please note, however, that when the sensor is launched without --net=host, it won’t be able to detect its host IP address. Refer to Compliance with CIS Benchmark for Docker for guidance and recommendations.

General Sensor

Linux

sudo docker run -d --restart on-failure -v /var/run/docker.sock:/var/run/docker.sock:ro -v /usr/local/qualys/sensor/data:/usr/local/qualys/qpa/data -e ACTIVATIONID=<Activation id> -e CUSTOMERID=<Customer id> -e POD_URL=<POD URL> --net=host --name qualys-container-sensor qualys/qcs-sensor:latest --storage-driver-type=overlay2

General Sensor Installation using Podman container runtime

Qualys General Sensor with Podman Runtime supports,
- Only Static scan for images
- Containers are not scanned but are listed and sent to your Qualys Enterprise TruRisk™ Platform account

Pre-requisites

Sensor needs Podman.socket. Run the following commands.
- To create a Podman Socket: systemctl --user enable podman.socket
- To start the newly created Podman Socket: systemctl --user start podman.socket

Run the following command
podman run -d --restart on-failure --privileged=true -v /run/podman/podman.sock:/run/podman/podman.sock:ro -v /var/lib/containers/storage:/var/lib/containers/storage:ro -v /etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data -v /home/ubuntu/root_sensor_storage:/usr/local/qualys/qpa/data -e ACTIVATIONID=<Activation ID> -e CUSTOMERID=<Customer ID> -e POD_URL=<POD URL>/ContainerSensor --net=host --name qualys-container-sensor docker.io/qualys/sensor:1.38.1-0 --log-level 5 --container-runtime podman --storage-driver-type overlay --perform-sca-scan

MacOS

sudo mkdir -p /tmp/qualys/sensor/data

sudo chmod -R 777 /tmp/qualys/sensor/data

sudo mkdir /private/etc/qualys/

sudo chmod 777 /private/etc/qualys

sudo docker run -d --restart on-failure -v /var/run/docker.sock:/var/run/docker.sock:ro -v /private/etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data -v /tmp/qualys/sensor/data:/usr/local/qualys/qpa/data -e ACTIVATIONID=<Activation id> -e CUSTOMERID=<Customer id> -e POD_URL=<POD URL> --net=host --name qualys-container-sensor qualys/qcs-sensor:latest

CoreOS

sudo mkdir -p /var/opt/qualys/sensor/data

sudo chmod -R 777 /var/opt/qualys/sensor/data

sudo docker run -d --restart on-failure -v /var/run/docker.sock:/var/run/docker.sock:ro -v /var/opt/qualys/sensor/data:/usr/local/qualys/qpa/data -e ACTIVATIONID=<Activation id> -e CUSTOMERID=<Customer id> -e POD_URL=<POD URL> --net=host --name qualys-container-sensor qualys/qcs-sensor:latest

Registry Sensor

Linux

Registry Sensor Installation using Docker container runtime
sudo docker run -d --restart on-failure -v /var/run/docker.sock:/var/run/docker.sock:ro -v /usr/local/qualys/sensor/data:/usr/local/qualys/qpa/data -e ACTIVATIONID=<Activation id> -e CUSTOMERID=<Customer id> -e POD_URL=<POD URL> --net=host --name qualys-container-sensor qualys/qcs-sensor:latest --storage-driver-type=overlay2 --registry-sensor

Registry Sensor Installation using Podman container runtime

Pre-requisites

Sensor needs Podman.socket
- sudo systemctl enable --now podman.socket
- sudo systemctl start --now podman.socket
Sensor needs to be run as a root (sudo) user
Minimum podman version: 4.9.4 and above

Run the following command
sudo podman run -d --restart on-failure --privileged=true -v /run/podman/podman.sock:/run/podman/podman.sock:ro -v /etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data -v /usr/local/qualys/sensor/data:/usr/local/qualys/qpa/data -v /var/lib/containers/storage:/var/lib/containers/storage:ro -e ACTIVATIONID=<Activation id> -e CUSTOMERID=<Customer id> -e POD_URL=<POD URL> --net=host --name qualys-container-sensor qualys/qcs-sensor:latest --registry-sensor --container-runtime podman --storage-driver-type overlay --insecure-registry

MacOS

sudo mkdir -p /tmp/qualys/sensor/data
sudo chmod -R 777 /tmp/qualys/sensor/data
sudo mkdir /private/etc/qualys/
sudo chmod 777 /private/etc/qualys

sudo docker run -d --restart on-failure -v /var/run/docker.sock:/var/run/docker.sock:ro -v /private/etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data -v /tmp/qualys/sensor/data:/usr/local/qualys/qpa/data -e ACTIVATIONID=<Activation id> -e CUSTOMERID=<Customer id> -e POD_URL=<POD URL> --net=host --name qualys-container-sensor qualys/qcs-sensor:latest --registry-sensor

CoreOS

sudo mkdir -p /var/opt/qualys/sensor/data

sudo chmod -R 777 /var/opt/qualys/sensor/data

CI/CD Sensor

Linux

CI/CD Sensor Installation using Docker container runtime

MacOS

sudo mkdir -p /tmp/qualys/sensor/data

sudo chmod -R 777 /tmp/qualys/sensor/data

sudo mkdir /private/etc/qualys/

sudo chmod 777 /private/etc/qualys

CoreOS

sudo mkdir -p /var/opt/qualys/sensor/data

sudo chmod -R 777 /var/opt/qualys/sensor/data

Volumes used in the above commands

/var/run/docker.sock:/var/run/docker.sock:ro - mounts the Docker socket to the sensor file system. This is mandatory unless user specifies the DOCKER_HOST environment variable if docker daemon is running on TCP port.

/usr/local/qualys/sensor/data:/usr/local/qualys/qpa/data - provides persistent storage for the sensor container. This mapping is mandatory unless “--sensor-without-persistent-storage” option is used. You may change the storage directory. The directory is automatically created if doesn't exist.

Additional environment variables/volumes can be provided:

If proxy is used to communicate with Qualys Cloud Platform, specify:
-e qualys_https_proxy=<IP/ address or FQDN>:<Port#>
If the proxy cert is required, mount volume for proxy certificate by adding:
-v <Proxy_File_Path>:/etc/qualys/qpa/cert/custom-ca.crt
If the Docker daemon is running on TCP port, specify -e DOCKER_HOST=<IPv4 address or FQDN>:<port#>.
Ensure that you remove the docker Unix domain socket volume mount (-v /var/run/docker.sock:/var/run/docker.sock:ro) in this case.
/etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data - HostID search directory to map the marker file created by Qualys Agent or Scanner appliance on the host.
If you want the sensor to communicate with docker daemon over TLS socket, specify the following mandatory environment variables and the volume mount.
Specify TLS docker socket to connect to by setting DOCKER_HOST environment variable:
-e DOCKER_HOST=<docker daemon host's IPv4 address, or FQDN, or hostname>:<port#>
where provided IPv4 address, or FQDN or hostname matches either the CN or the Alternative Subject Name in the docker server certificate.

To enable TLS authentication set:

-e DOCKER_TLS_VERIFY=1

By enabling sensor communication with docker daemon over TLS customer can restrict the sensor's access to docker socket by using docker authorization plugin.

Volume mount the directory on the docker daemon host where docker client certificate, client private key and CA certificate files are available:
-v <docker client certificate directory on the docker daemon host>:/root/.docker

Specify docker client certificate, client private key and CA certificate file names as arguments to sensor:
--tls-cacert <file name of the CA certificate used to sign docker server certificate> --tls-cert <docker client certificate file name> --tls-key <docker client private key file name>

If any of the CA certificate, client certificate or client private key have default file names such as ca.pem, cert.pem, key.pem respectively they can be omitted. For example, if docker daemon is listening on both unix domain socket and TCP TLS sockets you can launch the sensor like this:

docker run -d --restart on-failure --cpus=0.2 -v /var/run/docker.sock:/var/run/docker.sock:ro -v <client cert directory on the docker host>:/root/.docker -v /usr/local/qualys/sensor/data:/usr/local/qualys/qpa/data -e ACTIVATIONID=<Activation id> -e CUSTOMERID=<Customer id> -e POD_URL=<POD URL> -e DOCKER_TLS_VERIFY=1 -e DOCKER_HOST=<IPv4 or FQDN>:<port#> --net=host --name qualys-container-sensor qualys/qcs-sensor:latest --log-level 5 --tls-cacert <file name of the CA certificate used to sign docker server certificate> --tls-cert <docker client certificate file name> --tls-key <docker client private key file name>

Optional Parameters

--cpus

Restrict the CPU usage to a certain value.

--cpus=0.2 # Default CPU usage limit (20% of one core/processor on the host).

You can edit the CPU usage. For example, for limiting the CPU usage to 5%, set --cpus=0.05. This limits the CPU usage to 5% of one core/processor on the host.

If there are multiple processors on a node, setting the cpus value applies the CPU limit to one core/processor only. For example, if you have 4 CPUs on the system and you want to set CPU limit as 20% of overall CPU capacity, then the CPU limit should be set to 0.8 i.e., 80% of one core only which becomes 20% of total CPU capacity.

To disable any CPU usage limit, do not specify the option.

If docker host’s kernel does not support setting the CPU limit on running containers, disable CPU usage limit, otherwise the sensor won't get launched.

--enable-console-logs

Print logs on console. These logs can be retrieved using the docker logs command.

--enable-disk-space-check

(Optional) Checks the availability of free disk space before generating a tar. The available disk space is displayed in Bytes in the log file.

See an example given in the log,
...
BaseImageTarGenerator:: isDiskSpaceAvailableToCreateImgTar Free disk space on host: 42378436608 ...
(Available disk space = 42378436608 bytes)

OR

BaseImageTarGenerator:: isDiskSpaceAvailableToCreateImgTar Free disk space on host: 10058
DiskSpaceisNotAvailableToCreateImageTar:10058

(Available disk space = 10058 bytes)

When the sensor is being launched with below parameters, minimum disk space on the host should be as mentioned below:
a) SCA + Online scan = 1.5GB
b) Any other parameters defined = 500MB

--sensor-without-persistent-storage

Run the sensor without using persistent storage on host. In this case do not provide persistent storage mapping under volumes. It is recommended to use the "--enable-console-logs" option along with "--sensor-without-persistent-storage" to preserve the logs as data is not available on host but stored at the /usr/local/qualys/qpa/data folder relative to the Sensor.

--log-level

Set the logging level for sensor, accepts 0 to 5. Default is 3 (Information).

--log-filesize

Set the maximum size per log file for sensor in bytes. For example, specify “10” for 10 bytes, “10K” for 10 kilobytes, “10M” for 10 megabytes. Default is “10M”.

--log-filepurgecount

Define the number of archived qpa.log files to be generated. Default is 5.

--scan-thread-pool-size

Launch the sensor with scan thread value. Default is 4.

--read-only

Run sensor in read-only mode. In this mode the sensor uses persistent storage on host.

The sensor should be run either with '--sensor-without-persistent-storage' option or with '--read-only' option and not with both options enabled together.

--mask-env-variable

Mask environment variables for images and containers. The environment variables will be masked/removed in sensor logs and in the Container Security UI.

--disableImageScan

This parameter should be passed if you want to disable image scans for General Sensor. Images will not be scanned by sensors deployed with this option. This is available for General sensor type only, and is available for all Runtimes (Docker, CRI-O and Containerd).

--disableContainerScan

Use this parameter to skip container scanning. With this parameter, the inventory of the containers will still be collected but their scanning won't take place.

--disable-log4j-scanning

This parameter should be passed if you want to disable log4j vulnerability scanning for container images. See Log4j vulnerability scanning.

--disable-log4j-static-detection

This parameter should be passed if you want to disable log4j static detection for dynamic/static image scans. See Static log4j detection.

--optimize-image-scans

This parameter should be passed if you want to optimize image scans for General Sensor. By default, the sensor scans every image that it detects on the host. This results in redundant scanning of images. When you install the General sensor with '--optimize-image-scans', the sensor will communicate with the Qualys Cloud Platform and perform informed scans to avoid redundant image scans. The sensor will determine if the images present on the host are already scanned by other sensors for the same manifest and version and will not scan those images again.

--scanning-policy

This parameter should be passed if you want to specify a scanning policy. The scanning policy allows you to select the suitable scan type as per your requirement. The available values are:

DynamicScanningOnly: performs only dynamic scanning.
StaticScanningOnly: performs only static scanning.
DynamicWithStaticScanningAsFallback: (Default value) performs static scanning as a fallback to dynamic scanning for images without shell.
For example, 'scanningPolicy=podman'

--perform-secret-detection

This parameter should be passed if you want to perform secret detection for your container images. You can specify a timeout for secret detection using --sca-scan-timeout-in-seconds={value} parameter. For information about secret detection, see Online Help: Detect Container Secrets.

--perform-malware-detection

This parameter should be passed if you want to perform malware detection for your container images. You can specify a timeout for malware detection using --sca-scan-timeout-in-seconds={value} parameter. For information about malware detection, see Online Help: Malware Detection.

--limit-resource-usage

This parameter can be used to limit usage of resources for SCA or Secret or Malware Scan.

Optional parameters for SCA scanning

The following parameters are optional when the SCA scanning feature is enabled for your subscription. See SCA scanning to learn more.

--perform-sca-scan

(Optional) By default, SCA scanning is not performed. Use this parameter to enable SCA scanning for container images. When specified, the SCA scan will be performed after a standard vulnerability scan (Static or Dynamic). The SCA scan is attempted even when the vulnerability scan is not successful.

--disable-features

This parameter should be passed if you want to disable SBOM generation during an SCA scan. The parameter value is case-sensitive.

Format: --disable-features SBOM

--disallow-internet-access-for-sca

(Optional when --perform-sca-scan is specified) By default, SCA scans run in online mode. Use this parameter to disable Internet access for the SCA scan and run the scan in offline mode.

We recommend you run the SCA scan in online mode. Quality of software package enumeration for Java substantially degrades when the SCA scan is run in offline mode. The remote maven repository may need to be consulted for an accurate package detection. This can affect accuracy of the vulnerability posture of the image.

--sca-scan-timeout-in-seconds={value}

(Optional when --perform-sca-scan is specified) The default SCA scan command timeout is 5 minutes (300 seconds). Use this parameter to overwrite the default timeout with a new value specified in seconds. For example, you may need to increase the SCA scan timeout when scanning large container images to ensure the SCA scan has time to finish.

The --sca-scan-timeout-in-seconds parameter is also used for specifying a timeout for secret and malware detection.

--limit-resource-usage

This parameter can be used to limit usage of resources for SCA or Secret or Malware Scan.

--tag-sensor-profile

This parameter can be used to assign tags to a sensor.
Format: --tag-sensor-profile <Tag name>
Example: --tag-sensor-profile tag1

Use the below syntax to assign a special tag to a sensor.
--tag-sensor-profile=qcs_sensor_profile_<tag_name>

For more information on Sensor Profile tags, refer to Important Points Related to Sensor Tagging.

How to Comply with CIS Benchmark for Docker using Docker Run Commands

Qualys Container Security adheres to the CIS Benchmark for Docker for our Sensor image. Refer to Compliance with CIS Benchmark for Docker for guidance on how to use the Sensor image in a way that complies with the CIS Benchmark for Docker. We’ve provided instructions for a number of controls so you can operate the Sensor in a compliant manner.