Deploying the Sensor on Standalone Docker Host using Docker Compose
This topic explains how you can deploy the sensor using a yml file, remove and upgrade the sensor.
Prerequisites
- Docker engine version: 1.13.0+
- Docker-compose file format version: 2.2
- Docker host should be able to communicate with the Docker Hub
Creating a yml File
Create a new yml file containing the following information. You can name the file qualys_cs_sensor_docker_compose.yml.
The field alignment in the yml file is very important. Please make sure to honor the formatting provided in the below template.
version: '2.2'
services:
cs_sensor:
container_name: qualys-container-sensor
image: qualys/qcs-sensor:latest
restart: on-failure
# Uncomment the below security option if SELinux is enabled with enforcing mode on docker host
# security_opt:
# - label:disable
# Enable the flag if you want to launch CS sensor in read-only mode.
# read_only: true
network_mode: host
cpus: 0.2
command: ["--scan-thread-pool-size", "4"]
environment:
- ACTIVATIONID=<Activation id>
- CUSTOMERID=<Customer id>
- POD_URL=<POD URL>
# Define TCP socket if sensor will be communicating with docker daemon listening on TCP port
# - DOCKER_HOST=<IPv4 address or FQDN>:<port#>
# Enable TLS authentication if sensor will be communicating with docker daemon over TCP TLS socket
# - DOCKER_TLS_VERIFY=1
# Define the proxy if required
# - qualys_https_proxy=<IP address or FQDN>:<Port#>
volumes:
# Provide host Id search directory path
- /etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data
# Mount volume for docker socket
- /var/run/docker.sock:/var/run/docker.sock:ro
# Mount volume for persistent storage
- /usr/local/qualys/sensor/data:/usr/local/qualys/qpa/data
# Mount volume proxy certificate if required
# - <Proxy certificate path on host>:/etc/qualys/qpa/cert/custom-ca.crt
# Mount volume for docker client cert directory path
# - <Client certificate directory on the docker host>:/root/.docker
Parameters used in the yml file
container_name
set to qualys-container-sensor
image_name
set to qualys/qcs-sensor:<tag>
OR
set to qualys/qcs-sensor:latest
The image will get pulled from the Docker Hub by docker-compose.
restart
Defines the sensor restart policy and should be set to on-failure.
security_opt
This parameter should be used only when SELinux is enabled with enforcing mode on the docker host.
security_opt:
- label:disable
read-only
Set to true when launching the sensor in read-only mode.
network_mode
Set to host specifying that the sensor needs to be launched with host's network stack.
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 CPU 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, set CPUs value to 0 or remove/comment it out.
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.
command
If you want to deploy the sensor for CI/CD environment provide the command value as:
command: ["--cicd-deployed-sensor"]
If you want to deploy a Registry Sensor provide the command value as:
command: ["--registry-sensor"]
The General Sensor gets installed by default if the parameters for Registry or CI/CD are not provided.
Additional Values you can provide in the 'command' Parameter
"--enable-console-logs" to print logs on console. These logs can be retrieved using the docker logs command.
"--log-level" to set the logging level for sensor, accepts 0 to 5. Default is 3 (Information).
"--log-filesize" to set the maximum size per log file for sensor in bytes. Accepts "<digit><K/M/>" where K is kilobytes and M is megabytes. For example, specify "10" for 10 bytes, "10K" for 10 kilobytes, "10M" for 10 megabytes. Default is "10M".
"--log-filepurgecount" to define the number of archived qpa.log files to be generated. Default is 5.
"--scan-thread-pool-size" to launch the sensor with scan thread value. Default is 4.
"--sensor-without-persistent-storage" to 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.
Example,
command: ["--cicd-deployed-sensor", "--sensor-without-persistent-storage", "--enable-console-logs"]
volumes:
# mount volume for persistent storage
# -/usr/local/qualys/qpa/data
"--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 the sensor will be communicating with the docker daemon over TLS. If any of the three files have a default name such as ca.pem,cert.pem, key.pem respectively the corresponding argument can be omitted.
"--mask-env-variable" to mask environment variables for images and containers. The environment variables will be masked/removed in sensor logs and in the Container Security UI.
"--disableImageScan" 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).
"--disable-log4j-scanning" to disable log4j vulnerability scanning for container images. See Log4j Vulnerability Scanning.
"--disable-log4j-static-detection" to disable log4j static detection for dynamic/static image scans. See Static log4j detection.
"--qlys-disable-default-logging-to-file" to disable the default log generation in qpa.log file.
--qlys-disable-default-logging-to-file parameter is applicable only when the logs are enabled using --enable-console-logs.
"--optimize-image-scans" 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.
"--perform-secret-detection" to enable secrets detection for container images.
Secret detection is supported only on CI/CD and Registry sensors.
"--perform-malware-detection" to enable malware detection for container images. Note that malware detection is supported only on registry sensor.
environment
Provide the ACTIVATIONID, CUSTOMERID, and POD_URL from your subscription. To get the Activation ID and Customer ID, login to the Container Security UI, go to Configurations > Sensors, click Download, and then click any sensor type. 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.
Your hosts must be able to reach your Qualys Cloud Platform (or the Qualys Private Cloud Platform) over HTTPS port 443. See Qualys Platform (POD URL) your hosts need to access.
Specify DOCKER_HOST if sensor will be communicating with docker daemon listening on TCP port either with or without TLS enabled.
DOCKER_HOST=<IPv4 address, or FQDN, or hostname>:<Port#>
If TLS is enabled for the TCP socket specified please make sure that the provided IP, FQDN or hostname matches either the CN or Alternative Subject Name in the docker server certificate.
If sensor is listening on TCP socket without TLS do not provide unix domain socket directory mapping. Under 'volumes' comment out the following part:
volumes:
# mount volume for docker socket
# - /var/run/docker.sock:/var/run/docker.sock:ro
Specify DOCKER_TLS_VERIFY=1 to enable TLS authentication.
By enabling sensor communication with docker daemon over TLS customer can restrict the sensor's access to docker socket by using docker authorization plugin.
Specify qualys_https_proxy if a proxy is required for the sensor to communicate with the Qualys Cloud Platform.
- qualys_https_proxy=<IP/ address or FQDN>:<Port#>
volumes
Specify the persistent storage mapping to launch the sensor with persistent storage. The persistent storage directory is automatically created if doesn't exist.
volumes:
# mount volume for persistent storage
-/usr/local/qualys/sensor/data:/usr/local/qualys/qpa/data
Specify hostid directory location if you want to use the same hostid used in the previous installation.
# Provide host Id search directory path
- /etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data
Map the Unix socket file to sensor file system if the Docker daemon on the Docker host is communicating over Unix socket.
# mount volume for docker socket
- /var/run/docker.sock:/var/run/docker.sock:ro
If the Docker daemon is communicating over TCP port specify the DOCKER_HOST parameter under environment and DO NOT provide mapping for docker unix socket file under volumes.
Specify the proxy certificate (if required):
- <Proxy certificate path on host>:/etc/qualys/qpa/cert/custom-ca.crt
Specify docker client certificate directory mapping if the sensor will be communicating with docker daemon over TLS:
# mount volume for docker client certificate directory
- <docker client certificate directory on the docker daemon host>:/root/.docker
Launching the Sensor
Once the yml file is created, use the following command to launch the sensor:
docker-compose -f <path to qualys_cs_sensor_docker_compose.yml file> up -d
Upgrading the Sensor
The Qualys Container Sensor image hosted on Docker Hub does not support auto update. Perform the following steps to update the sensor installed from Docker Hub:
1. Update the image name in the yml file:
Set to qualys/qcs-sensor:<tag>
OR
Set to qualys/qcs-sensor:latest
2. Run the command to recreate the sensor:
docker-compose -f <path to qualys_cs_sensor_docker_compose.yml file> up -d
Removing the Sensor
Run the following command to remove the sensor.
docker-compose -f <path to qualys_cs_sensor_docker_compose.yml file> rm -s
The docker-compose does not provide an option to delete the persistent storage. You must delete the persistent storage files manually.