Qualys Container Security Sensor Deployment Guide

Container Security

Sensor Deployment Guide

Version 1.33.0

July 09, 2024

Qualys and the Qualys logo are registered trademarks of Qualys, Inc. All other trademarks

are the property of their respective owners.

Qualys, Inc.

919 E Hillsdale Blvd

4th Floor

Foster City, CA 94404

1 (650) 801 6100

Table of Contents

About this Guide ............................................................................................... 5

About Qualys ........................................................................................................................... 5

Qualys Support ........................................................................................................................ 5

About Container Security Documentation ........................................................................... 5

Container Security Overview......................................................................... 6

Qualys Container Sensor ........................................................................................................ 6

Sensor Modes ........................................................................................................................... 7

What data does Container Security collect? ........................................................................ 8

Get Started .........................................................................................................9

Qualys Subscription and Modules required ......................................................................... 9

System support ........................................................................................................................ 9

Deploying Container Sensor ................................................................................................. 10

Installsensor.sh script command line parameters ............................................................ 13

Proxy Support ......................................................................................................................... 18

Qualys Platform (POD URL) your hosts need to access ..................................................... 19

Sensor network configuration .............................................................................................. 19

Static scanning of container images ................................................................................... 20

Log4j vulnerability scanning ................................................................................................ 20

Static log4j detection ............................................................................................................. 20

SCA scanning ......................................................................................................................... 21

Secrets Detection ................................................................................................................... 22

Malware Detection ................................................................................................................ 23

Events that lead to Docker asset scanning ......................................................................... 24

Storage Requirements for Sensor Scans ............................................................................. 24

Installing the sensor on MacOS ...................................................................26

Installing the sensor on Linux ......................................................................28

Installing the sensor on CoreOS..................................................................29

Installing the sensor from Docker Hub..................................................... 30

Deploying the sensor on standalone docker host using docker compose ...................... 30

Deploying the sensor on standalone docker host using docker run ................................ 37

Deploying the sensor using Docker Hub on Kubernetes ................................................... 44

Installing the CI/CD Sensor in Docker-in-Docker Environment ..........56

Step 1: Have the CS Sensor image inside a Docker-in-Docker Container ....................... 56

Step 2: Launch the Container Security Sensor ................................................................... 57

Deploying sensor in Kubernetes .................................................................59

How to Detect the Container Runtime in your Kubernetes Cluster Environment ......... 60

Obtain the Container Sensor Image .................................................................................... 60

Deploy in Azure Kubernetes Service (AKS) ......................................................................... 63

Deploy in Kubernetes - Docker Runtime ............................................................................ 63

Deploy in Kubernetes - Containerd Runtime ..................................................................... 81

Deploy in Kubernetes - CRI-O Runtime ............................................................................... 92

Deploy in Kubernetes - OpenShift with CRI-O Runtime ................................................. 104

Deploy in Kubernetes with TKGI - Docker Runtime ........................................................ 114

Deploy in Kubernetes with TKGI - Containerd Runtime ................................................. 125

Deploy in Kubernetes with RKE1 - Docker Runtime ........................................................ 139

Deploy in Kubernetes with RKE2 - Containerd Runtime ................................................. 146

Deploy in Google Kubernetes Engine (GKE) with multi-node clusters .......................... 150

Deploy in Kubernetes using Helm Charts ......................................................................... 152

Collection of Kubernetes Cluster Attributes ..................................................................... 158

Update the sensor deployed in Kubernetes ...................................................................... 159

Deploying sensor in Docker Swarm ......................................................... 163

Deploying sensor in AWS ECS Cluster.................................................... 167

Scan Container Images in AWS Fargate (ECS)......................................172

Compliance with CIS Benchmark for Docker......................................... 180

Administration............................................................................................... 186

Sensor updates ..................................................................................................................... 186

How to uninstall the sensor ............................................................................................... 186

Troubleshooting............................................................................................ 188

Check sensor logs ................................................................................................................ 188

Sensor health status ............................................................................................................ 188

Diagnostic script .................................................................................................................. 188

Sensor crashes during upgrade .......................................................................................... 189

What if sensor restarts? ...................................................................................................... 189

Duplicate Kubernetes containers ...................................................................................... 191

Get container runtime details ............................................................................................ 191

About this Guide

About Qualys

About this Guide

Welcome to Qualys Container Security! We’ll help you get acquainted with the Qualys

solutions for securing your Container environments like Images, Containers and Docker

Hosts using the Qualys Cloud Security Platform.

About Qualys

Qualys, Inc. (NASDAQ: QLYS) is a pioneer and leading provider of cloud-based security and

compliance solutions. The Qualys Cloud Platform and its integrated apps help businesses

simplify security operations and lower the cost of compliance by delivering critical

security intelligence on demand and automating the full spectrum of auditing,

compliance and protection for IT systems and web applications.

Founded in 1999, Qualys has established strategic partnerships with leading managed

service providers and consulting organizations including Accenture, BT, Cognizant

Technology Solutions, Deutsche Telekom, Fujitsu, HCL, HP Enterprise, IBM, Infosys, NTT,

Optiv, SecureWorks, Tata Communications, Verizon and Wipro. The company is also

founding member of the Cloud Security Alliance (CSA). For more information, please visit

www.qualys.com

Qualys Support

Qualys is committed to providing you with the most thorough support. Through online

documentation, telephone help, and direct email support, Qualys ensures that your

questions will be answered in the fastest time possible. We support you 7 days a week,

24 hours a day. Access online support information at www.qualys.com/support/.

About Container Security Documentation

This document provides information on deploying the sensor on MAC, CoreOS, and

various orchestrators and cloud environments.

For information on using the Container Security UI and API, refer to:

Qualys Container Security User Guide

Qualys Container Runtime Security User Guide

Qualys Container Security API Guide

Qualys Container Runtime Security API Guide

For information on deploying the sensor in CI/CD environments, refer to:

Qualys Container Scanning Connector for Jenkins

Qualys Container Scanning Connector for Bamboo

Qualys Container Scanning Connector for Azure DevOps

Container Security Overview

Qualys Container Sensor

Container Security Overview

Qualys Container Security provides discovery, tracking, and continuously protecting

container environments. This addresses vulnerability management and policy compliance

for images and containers in their DevOps pipeline and deployments across cloud and on-

premise environments.

With this version, Qualys Container Security supports

- Discovery, inventory, and near-real time tracking of container environments

- Vulnerability analysis for images and containers

- Vulnerability analysis for registries

- Compliance assessment for images and containers

- Integration with CI/CD pipeline using APIs (DevOps flow)

- Uses ‘Container Sensor’ - providing native container support, distributed as docker image

Qualys Container Sensor

The sensor from Qualys is designed for native support of Docker environments. Sensor is

packaged and delivered as a Docker Image. Download the image and deploy it as a

Container alongside with other application containers on the host.

The sensor is docker based, can be deployed on hosts in your data center or cloud

environments like AWS ECS. Sensor currently is only supported on Linux Operating

systems and requires docker daemon of version 1.12 and higher to be available.

Container Security Overview

Sensor Modes

Since they are docker based, the sensor can be deployed into orchestration tool

environments like Kubernetes, Mesos or Docker Swarm just like any other application

container.

Upon installation, the sensor does automatic discovery of Images and Containers on the

deployed host, provides a vulnerability analysis of them, and additionally it monitors and

reports on the docker related events on the host. The sensor lists and scans registries for

vulnerable images. The sensor also performs compliance assessments. The sensor

container runs in non-privileged mode. It requires a persistent storage for storing and

caching files.

Currently, the sensor only scans Images and Containers. To get a vulnerability posture on

the Host, you would require Qualys Cloud Agents or a scan through Qualys Virtual

Scanner Appliance.

Sensor Modes

A sensor can only be deployed in a single mode on a single container’s host/cluster node.

General

The General mode sensor is installed on your container nodes/hosts. It provides

vulnerability and compliance assessments for your running containers and locally cached

images. The general sensor performs demand driven assessments based on container

events like containers instantiated and images pulled. There is no on demand scan or

scheduled scan assessments; the sensor reacts to the container environment changes in

real time. The general mode sensor must be deployed separately from the Registry or CICD

sensor.

Registry

Registry mode provides inventory and vulnerability assessment for images stored in

registries. The sensor, in registry mode, will not inventory or perform vulnerability

assessments of the images or containers on the host where the sensor is deployed. The

sensor in registry mode must have network access to the registry URL. The registry mode

sensor will not discover registries automatically. The images inventoried and assessed are

scoped by the registry connector scan jobs. These scan jobs are either automatic

(scheduled) or on demand. Log into the Container Security UI to configure a registry

connector and scan job. Refer to the online help for guidance. The registry mode sensor

must be deployed separately from the General or CICD sensor.

CICD

CICD mode is for sensors running on CI Pipeline workers. It is demand driven assessment

based on specific events. The sensor in CICD mode does not inventory or assess other

images or containers running on the host/node. The sensor in CICD mode performs

vulnerability assessments on specifically tagged images and the assessment results are

put into a priority processing queue with a faster SLA specifically for CI Pipeline

assessments. The CICD sensor must be deployed separately from the General or Registry

sensor.

Container Security Overview

What data does Container Security collect?

The Qualys Container Security sensor fetches the following information about Images and

Containers in your environment:

Inventory of Images and Containers in your environment from commands, such as

docker ps that lists all containers.

Metadata information about Images and Containers from commands, such as docker

inspect and docker info that fetches low level information on docker objects.

Event information about Images and Containers from the docker host for docker events

like created, started, killed, push, pull, etc.

Vulnerabilities found on Images and Containers. This is the output of the vulnerability

management manifests run for identifying vulnerability information in Images and

Containers. This is primarily software package listing, services running, ports, etc. For

example, package manager outputs like rpm -qa, npm. This is supported across various

Linux distributions (CentOS, Ubuntu, CoreOS, etc) and across images like Python, NodeJS,

Ruby, and so on.

Compliance configurations for OCI compliant images, running containers. We are

supporting a subset of controls from CIS Docker benchmarks, which are applicable to

running containers and container images. Customers can assess configuration risks in

their running containers and images and remediate them accordingly based on the Qualys

finding. The compliance scans of containers, images will be transparent to customers and

will function in a similar real-time cloud native manner like the vulnerability scanning

feature.

Get Started

Qualys Subscription and Modules required

Get Started

Qualys Subscription and Modules required

You need the “Container Security” (CS) module enabled for your account. Additionally, in

order to get vulnerabilities for the hosts that run the containers, you would need to enable

Vulnerability Management (VM), either via Scanner Appliance or Cloud Agent.

System support

The Container Security Sensor can be run on any Operating System that has Docker

version 1.12 or later. We’ve verified the Sensor on the following systems:

- CentOS Linux 7.3, 7.4, 7.5, 7.6, 7.7

- CoreOS 1855.4.0

- Debian Linux 8 (Jessie)

- Fedora Release 28

- Kali Linux

- Mac OS 10.13

- Red Hat Enterprise Linux 7.4

- Red Hat Enterprise Linux Atomic Host 7.5, 7.7

- Ubuntu 14.04, 16.04, 18.04, 20.04

The Container Security Sensor can scan container images based on the following

Operating Systems:

- AlmaLinux

- Alpine Linux

- Amazon Linux

- CBL-Mariner Linux

- CentOS

- Debian

- Fedora

- Google Distroless (Debian Linux)

- OpenSUSE

- Oracle Enterprise Linux

- Red Hat Enterprise Linux Server

- Rocky Linux

- SUSE Linux Enterprise Server

- Ubuntu

Get Started

Deploying Container Sensor

The Container Security Sensor can be installed in either of the following ways:

- download the sensor tar file from Qualys Cloud Platform and then install it on the host.

- install the sensor from Docker Hub. See Installing the sensor from Docker Hub.

To download the sensor from Qualys Cloud Platform, log into your Qualys portal with your

user credentials. Select Container Security from the module picker. As a first time user,

you’ll land directly into the Home page.

Go to Configurations > Sensors, and click Download Sensor.

The Download and Deploy Qualys Container Sensor window will appear, as shown below.

Get Started

Deploying Container Sensor

Pick the type of sensor you want to deploy.

IMPORTANT: Sensor deployment is one sensor in one mode on one host/node. Deploying

more than one sensor or more than one sensor in another mode is not supported.

Sensor modes:

General (Host) Sensor: Scan any image and container on the host where sensor is

running. General Sensor is installed by default if parameters for Registry or CI/CD are not

provided.

Registry Sensor: Scan images in a registry (public / private). For Registry you need to

append the install command with --registry-sensor or -r

Build (CI/CD) Sensor: Scan images on CI/CD pipeline (Jenkins / Bamboo). For CI/CD you

need to append the install command with --cicd-deployed-sensor or -c

To deploy on a standalone host, pick the host’s operating system: MacOS, Linux or CoreOS.

In the window that appears, choose DOCKERHUB or BINARY(TAR.XZ) for how you want to

install the sensor. Then simply follow the steps on the screen. For Tar, you’ll download the

tar file and run the install commands on the screen. For Docker Hub, you’ll run the docker

commands on the screen.

Get Started

Deploying Container Sensor

To deploy to a cluster, first pick from the cluster options: Kubernetes, Openshift, AWS ECS,

or Docker Swarm.

In the window that appears, choose the runtime. In the example below for General sensor

being deployed in Kubernetes, you’ll see DOCKER, CONTAINERD and CRI-O runtime

options. After making your selection, follow the steps on the screen. The installation yaml

file will already be pre-filled with your Activation ID, Customer ID and POD URL.

Be sure to note the System Requirements for installing the sensor. The sensor needs a

minimum of 1 GB persistent storage on the host.

Get Started

Installsensor.sh script command line parameters

Here’s a quick overview of the “installsensor.sh” script command line parameters.

Note: Only a few of the parameters have default values. Default values can be changed

during sensor installation. However, the default values (e.g., LogLevel) once set may get

overridden by a config update. If you want to change any default value post sensor

installation, you must rerun the “installsensor.sh” script with new values.

Parameter Description

ActivationId (Required) The Activation Id for the container sensor, auto-

generated based on your subscription.

CustomerId (Required) The Qualys subscription’s customer Id, auto-

generated based on your subscription.

--cicd-deployed-sensor or -c (Optional) Run the sensor in a CI/CD environment. This allows

you to scan images on CI/CD pipeline (Jenkins, Bamboo).

--registry-sensor or -r (Optional) Run the sensor to list and scan registry assets. This

allows you to scan images in a public or private registry.

Storage (Optional) Directory where the sensor would store the files.

Default value: /usr/local/qualys/sensor/data.

Create this directory if not already available or specify a

custom directory location.

--sensor-without-

persistent-storage

(Optional) Use this option to run the sensor without using

persistent storage on the host.

Note: The sensor should be run either with the “--sensor-

without-persistent-storage” option OR with the “--read-only”

option and not with both options enabled together.

To install the sensor without persistent storage, exclude the

“Storage” option, and include the “--sensor-without-persistent-

storage” option in the installer script. We recommend you 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.

As the sensor is running with “--sensor-without-persistent-

storage”, upon auto-update the updated sensor is a completely

new instance of sensor container hence data from the old

sensor is not available in the new sensor. Thus, the new sensor

rescans existing already scanned assets.

If the sensor is installed without any persistent storage, the

Container Summarypage may not display any sensor details,

and instead, it may show the error "There is no sensor activity

recorded".

Get Started

Installsensor.sh script command line parameters

--read-only (Optional) Use this option to run the sensor in read-only mode.

In this mode the sensor uses persistent storage on the host.

Note: The sensor should be run either with the “--sensor-

without-persistent-storage” option OR with the “--read-only”

option and not with both options enabled together.

ConcurrentScan (Optional) Number of docker/registry asset scans to run in

parallel. A valid range is between 1-20. Default value is 4.

CpuShares (Optional) Define CPU shares for the sensor container. A valid

value is a non-zero, positive integer other than 1024.

CpuUsageLimit (Optional) CPU usage limit in percentage for sensor. A valid

range is between 0-100. Default is 0.2, i.e. 20% per core on the

host.

The installsensor script has intelligence to find the number of

CPU cores present on the host and apply the CPU limit based

on the CpuUsageLimit input value and number of CPU cores

available. For example, when CpuUsageLimit=30, it’s

considered as 30% CPU of overall CPU capacity of the host. If

the host has 8 CPU cores, the total CPU limit applied to sensor

container would be 0.30 * 8 = 2.4 CPU cores.

--disable-auto-update (Optional) Do not let sensor update itself automatically.

--disableImageScan (Optional) 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).

ScanningPolicy (Optional) Specifies the scanning policy, which 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: performs

static scanning as a fallback to dynamic scanning for images

without shell.

--disable-log4j-scanning (Optional) This parameter should be passed if you want to

disable log4j vulnerability scanning for container images.

See Log4j vulnerability scanning.

--disable-log4j-static-

detection

(Optional) This parameter should be passed if you want to

disable log4j static detection for dynamic/static image scans.

See Static log4j detection.

DockerHost (Optional) The address on which the docker daemon is

configured to listen. This option is mandatory if

DOCKER_TLS_VERIFY=1 is defined.

DockerHost format: <Docker daemon host’s IPv4 address, or

FQDN, or hostname>:<port#>

Parameter Description

Get Started

Installsensor.sh script command line parameters

DockerSocketDirectory (Optional) Docker socket directory path. The default value is

Default: /var/run

DOCKER_TLS_VERIFY (Optional) This parameter enables the TLS authentication. The

value should be 0 or 1.

Note: If DOCKER_TLS_VERIFY=1 is defined, then ensure that

the provided IPv4 address or FQDN or hostname in DockerHost

matches either the CN or the Alternative Subject Name in the

docker server certificate.

Note: By enabling sensor communication with docker daemon

over TLS, customer can restrict the sensor’s access to docker

socket by using docker authorization plugin.

TLS_CERT_PATH (Optional) Provide client certificate directory path. This is

mandatory if DOCKER_TLS_VERIFY=1 is defined.

tlscacert=<Name of CA (default "ca.pem")> tlscert=<Name of

TLS certificate file (default "cert.pem")> tlskey=<Name of TLS

key file (default "key.pem")>

Note: 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.

--enable-console-logs (Optional) Print logs on console. These logs can be retrieved

using the docker logs command.

HostIdSearchDir (Optional) Directory to map the marker file created by Qualys

Agent or Scanner appliance on the host, update if modified.

Default value is /etc/qualys

ImageFile (Optional) Location of the Sensor ImageFile. This defaults to

the local directory.

LogFilePurgeCount (Optional) Integer value that specifies the maximum number of

archived log files. Default value is 5.

LogFileSize (Optional) Configuration 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

value is "10M".

LogLevel (Optional) Configuration to set the logging level for sensor,

accepts 0 to 5. Default value is 3 (Information).

--mask-env-variable (Optional) Use this parameter to mask environment variables

for images and containers. The environment variables will be

masked/removed in sensor logs and in the Container Security

UI.

Parameter Description

Get Started

Installsensor.sh script command line parameters

MemoryUsageLimit (Optional) Define the memory usage limit for the sensor

container. The value should be formatted as <digit><unit>

where unit can be any of the following: b (bytes), k (kilobytes),

m (megabytes), g (gigabytes). The recommended value is 500m

for 500 megabytes.

--optimize-image-scans (Optional) This parameter should be passed if you want to

optimize Image scans for General Sensor. This is available for

General sensor type only.

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.

PidLimit (Optional) Define the PID limit for the sensor container. The

value provided must be a positive integer.

Proxy (Optional) IPv4/IPv6 address or FQDN of the proxy server.

ProxyCertFile (Optional) Proxy certificate file path. ProxyCertFile is applicable

only if Proxy has valid certificate file. If this option is not

provided, then Sensor will try to connect to the server with

given https Proxy settings only.

If only ProxyCertFile is provided without Proxy then Sensor

would simply ignore the ProxyCertFile and it would try to

connect to the server without any https proxy settings.

--silent or -s (Optional) Run installsensor.sh in non-interactive mode.

--perform-secret-detection (Optional) Use this parameter to enable secret detection for

container images. You can specify a timeout for this command

using the SCAScanTimeoutInSeconds={value} parameter.

Note: Secret detection is supported only on:

- CICD and registry sensors

- Linux operating system

- Docker, Containerd, and CRI-O runtimes

--limit-resource-usage (Optional) Use this parameter to limit usage of resources for

SCA/Secret/Malware Scan

Parameter Description

Get Started

Installsensor.sh script command line parameters

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.

Parameter Description

--perform-sca-scan (Optional when SCA scanning is enabled for your subscription)

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.

--disallow-internet-access-

for-sca

(Optional when --perform-sca-scan is specified) By default,

Internet access is enabled for the SCA scan and the SCA scan is

performed in online mode because in online mode, the package

collection is more accurate than compared to scans performed

in offline mode. Use this parameter to disable Internet access

for the SCA scan and run the scan in offline mode instead.

Note: 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. The sensor must be able to reach the URL

“http://search.maven.org” and “https://ghcr.io”.

SCAScanTimeoutInSeconds

={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.

Note: This parameter is also used for specifying a

timeout for secret detection.

--limit-resource-usage (Optional) Use this parameter to limit usage of resources for

SCA/Secret/Malware Scan

Get Started

Proxy Support

Docker Hub

For information on installing the sensor from Docker Hub, see:

Installing the sensor from Docker Hub

CI/CD Environments

For information on deploying the sensor in CI/CD environments, refer to:

Qualys Container Scanning Connector for Jenkins

Qualys Container Scanning Connector for Bamboo

Qualys Container Scanning Connector for Azure DevOps

Note: 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.

How to Comply with CIS Benchmark for Docker using Installsensor.sh

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.

Proxy Support

The install script asks for proxy configuration. You need to provide the IP Address/FQDN

and port number along with the proxy certificate file path. For example:

Do you want connection via Proxy [y/N]: y

Enter Https Proxy settings [<IP Address>:<Port #>]: 10.xxx.xx.xx:3xxx

Enter Https Proxy certificate file path: /etc/qualys/cloud-

agent/cert/ca-bundle.crt

Your proxy server must provide access to the Qualys Cloud Platform (or the Qualys Private

Cloud Platform) over HTTPS port 443. See Qualys Platform (POD URL) your hosts need to

access.

Get Started

Qualys Platform (POD URL) your hosts need to access

The Qualys URL you use depends on the Qualys platform where your account is located.

Click here to identify your Qualys platform and get the Container Security Server URL

POD URL value

The “Container Security Server URL” for your platform is the URL you’ll need to provide for

the POD_URL variable in Container Security Sensor commands and in configuration yaml

files when deploying the sensor.

Sensor network configuration

The sensor is pre-configured with the Qualys URL and subscription details it needs to

communicate to Qualys. In order for the sensor to communicate to Qualys, the network

configuration and firewall need to provide accessibility to Qualys domain over port 443.

After successful installation of the sensor, the sensor is listed in the Container Security UI

under Configurations > Sensors where you can see its version, status, etc, and access

details. Additionally, you can Download the sensor from the link under Configurations >

Sensors.

Get Started

Static scanning of container images

Static scanning is supported for deployments on standalone Docker hosts and

deployments in Kubernetes with Docker Runtime and Containerd Runtime.

The sensor will perform static scanning for container images as a fallback mechanism to

current dynamic scanning in case container image does not have a shell. Static scanning

will also be performed for Google distroless images without shell. Static scanning will not

be performed on container or container images having a shell.

Static scanning collects the list of installed software from the container image file system

to find vulnerabilities in the container images. The installed software list is retrieved from

the Package manager metadata files. Package managers supported are RPM, DPKG and

Alpine.

If you have large images without shell on the host where sensor is running, the

requirement for disk space may exceed the minimum requirement of 1GB.

Log4j vulnerability scanning

The sensor can detect Log4j Remote Code Execution (RCE) Vulnerability QIDs. It can detect

the presence of vulnerable log4j packages on your container images and running

containers. The sensor will automatically perform a file system search to detect log4j

vulnerabilities on your container images, and this can have a performance impact. To

disable log4j vulnerability scanning, specify --disable-log4j-scanning as a command line

parameter for “installsensor.sh” script or provide it as a command or args parameter when

deploying a sensor.

Static log4j detection

Static log4j detection is enabled by default for dynamic/static image scans. Static log4j

detection is implemented by executing the log4j detection command for each image layer

and then merging the results. You have the option to disable static log4j detection for

dynamic/static image scans using the parameter --disable-log4j-static-detection.

For static scans, static log4j detection will always be invoked unless the --disable-log4j-

static-detection parameter is specified. The log4j commands are read from the VM

manifest.

For dynamic scans, static log4j detection will only be invoked when the following is true:

- The parameter --disable-log4j-scanning is not used.

- The parameter --disable-log4j-static-detection is not used.

- The primary log4j detection command was unsuccessful in collecting log4j data points.

To disable the static log4j detection, specify --disable-log4j-static-detection as a command

line parameter for “installsensor.sh” script or provide it as a command or args parameter

when deploying a sensor.

Get Started

SCA scanning

Qualys Container Security Sensor supports Software Composition Analysis (SCA) scanning

of container images. An SCA scan discovers installed open source software and libraries,

as well as associated vulnerabilities, present in your container images.

While evaluating security posture of container images it is important to identify all

software packages present in the image. The SCA scan can be used to identify

programming language-based software packages inside the image. In addition, metadata

information for each image layer is also provided. The SCA scan detects packages for these

programming languages: Java, Python, Go, Node.js, .NET, PHP, Ruby, and Rust.

SCA scanning is supported for all sensor types – General, Registry and CI/CD. It’s

supported for Docker, ContainerD, and CRI-O runtimes. SCA scanning is only supported

when scanning container images. SCA scanning is not supported for Mac OS.

Note: For CRI-O runtime to support SCA, it is required to launch the sensor with privilege

rights.To do that, in the ‘cssensor-crio-ds.yml’ file, the following parameter must be set to

true.

securityContext:

privileged: true

If your environment is restricted and you are using a proxy for sensor provisioning with

the SCA enabled flag, then you need to use two different proxy variables. There are two

proxy settings needed for our sensor:

1. to communicate with Qualys Cloud platform

2. to communicate with the outside world. These are controlled by the following variables.

In case of K8s environment,

To perform the SCA scanning with Proxy setting, uncomment the below section and

provide the given values to the yaml file.

- name: qualys_https_proxy

value:http://proxy_URL

- name: https_proxy

value: http://proxy_URL

In case of standalone Docker environment,

To perform the SCA scanning with Proxy setting, provide the given values in the

installsensor.sh file.

-e qualys_https_proxy=https://proxy_URL

-e https_proxy=http://proxy_URL

Prerequisites

• By default, the SCA Scanning feature is enabled for all new subscriptions. Contact

Qualys Support to have this feature enabled.

• Sensor version 1.23 or later.

Get Started

Secrets Detection

• Below URLs are accessible to the Sensor.

- https://ghcr.io

- https://pkg-containers.githubusercontent.com

• Relaunch your sensors with the parameter --perform-sca-scan to perform SCA

scanning.

• Additional storage on the host to store SCA scan metadata. Refer to Storage

Requirements for Sensor Scans.

How it Works

SCA scanning is not performed by default. Users must enable SCA scanning using the

parameter --perform-sca-scan. When enabled, an SCA scan is performed after a standard

vulnerability scan (Static or Dynamic) on your container images. When the SCA scan

completes, the sensor uploads the metadata information collected by the scan to the

Qualys backend where posture evaluation is performed. You can view SCA scan data

findings in the Container Security UI and API as part of image details. Vulnerability

detections found by the SCA scan are presented as QIDs. Filters are provided so you can

identify the type of scan (SCA, Dynamic or Static) used to detect a particular vulnerability.

Internet access is enabled for the SCA scan and the SCA scan is performed in online mode

by default. Make sure the sensor can reach the URL “http://search.maven.org/” and

“https://ghcr.io”.

During an SCA scan, the following files are scanned for the language-specific software

packages:

Secrets Detection

Container secrets are digital credentials providing identity authentication and authorizing

access to privileged accounts, applications, and services. They can include passwords, API

keys, and other credentials that are needed for applications to function properly.

Language Files

Python egg package

wheel package

Node.js package.json

.NET packages.lock.json

packages.config

*.deps.json

Java JAR/WAR/PAR/EAR

Go Binaries built by Go

PHP Composer.lock

Ruby gemspec

Rust Cargo.lock and Binaries built with cargo-auditable

Get Started

Malware Detection

If these secrets are not properly secured, they can be accessed by unauthorized users,

leading to malicious attacks. Therefore, discovering secrets is one of the important aspects

of container security that organizations must prioritize to protect their sensitive data,

meet compliance requirements, and reduce the risk of security incidents.

Container Security Sensor can detect secrets for container images enabling you to

mitigate potential security risks associated with the accidental or intentional exposure of

secrets within containers.

To enable secret detection, you need to use the --perform-secret-detection

parameter.

Secret detection involves scanning the filesystem. It does not detect secrets that are stored

as environment variables or passed as arguments within the image. Therefore, the

performance of secret detection depends on the number of files present in the image.

For optimal performance in secret detection, it is recommended to allocate a higher CPU

count to the sensor container. Ensure that at least two CPUs of the host are specifically

utilized for the sensor container.

For instance:

- When using the InstallSensor.sh script, by default only 20% of the host's CPUs are

utilized by the sensor container.

- When using dockerrun, by default all CPUs of the host are fully utilized for the sensor

container

Note: Secret detection is supported only on:

- Sensors: CICD and registry

- OS: Linux

- Runtimes: Docker, Containerd, and CRI-O

For more information about secret detection, see Online Help: Detect Container Secrets.

Malware Detection

You can scan your container images for the presence of malware or any malicious files.

Malware detection ensures that malicious container images are not deployed into the

production environment. This prevents potential breaches, data theft, or unauthorized

access that could result from running malicious containers.

To enable malware detection, you need to use the --perform-malware-detection

parameter while installing the sensor.

For efficient malware scanning, it is recommended to allocate 1 CPU core for the sensor.

For instance:

- When using the InstallSensor.sh script, by default 20% of the host's CPUs are utilized by

the sensor container. If the host has 8 CPU cores, the total CPU limit applied to the sensor

container would be 0.2 * 8 = 1.6 CPU cores.

Get Started

Events that lead to Docker asset scanning

- When using dockerrun, by default all CPUs of the host are fully utilized for the sensor

container.

- In Kubernetes, to allocate 1 CPU core for the sensor container, regardless of the number

of cores available on the host system, set the CPU limit value to 1.

Example:

resources:

limits:

cpu: "1"

Note: Malware detection is supported only on:

- Sensors: Registry sensor (x86_64 architecture only)

- OS: Linux

- Runtimes: Docker, Containerd, and CRI-O

For more information about malware detection, see Online Help: Malware Detection.

Events that lead to Docker asset scanning

A new asset scan is launched when any of the following events occur.

- Events on images: load, pull, import, tag

- Events on containers: start, create, unpause

- Scan is launched when there’s a new manifest.

- Scan is launched every 48 hours on containers (i.e. 48 hours after the last successful

scan).

Storage Requirements for Sensor Scans

If you want to enable all types of scans, Qualys recommends the following server

requirements.

• CPU Cores: 6

• RAM: 5GB

See the sections below to understand storage requirements for different scan types.

Dynamic Scan

Applicable to Registry Sensor only.

The Registry sensor pulls the Docker image on the host for scanning. Storage required on

the partition where Docker is installed is based on the size of the image. The dynamic scan

is performed on the cached image.

For an average image size of 4GB, the maximum storage requirement would be 16GB:

Get Started

Storage Requirements for Sensor Scans

4GB image * 4 scan threads = 16GB

Static Scan

Applicable to General (Host) Sensor, Registry Sensor and Build (CI/CD) Sensor.

Additional storage is required on persistent storage to scan the image if the image does

not have a shell. The static scan is performed on the container image. The storage

requirement is approximately 3 times the size of the image.

For an average image size of 4GB where 4 scan threads are performing the image scan on

images with no shell, the maximum storage requirement would be 48GB:

(4GB image * 3) * 4 scan threads = 48GB

SCA Scan

Applicable to General (Host) Sensor, Registry Sensor and Build (CI/CD) Sensor.

When the CS Sensor is running with --perform-sca-scan, it will require additional storage

on the host to accommodate the image tar, which is usually the size of the image plus

100MB additional disk space used to store SCA scan metadata. The storage required is the

image size plus 100MB times the number of threads performing the Docker image scan.

For an average image size of 4GB where 4 scan threads are performing the image scan, the

maximum storage requirement is approximately 16.4GB:

(4GB image + 100MB) * 4 scan threads = 16.4GB

Static Log4j Detection

If static detection is triggered for images having shell, then additional space is required.

This needs 3 times the size of the image.

For an average image size of 4GB, the additional storage requirement would be 12GB:

4GB image * 3 = 12GB

Installing the sensor on MacOS

Note: If you are running the sensor on MacOS Catalina version 10.15 or above, please use

sensor version 1.8.0 or above.

You can install the Qualys Container Sensor on MacOS. Download the

QualysContainerSensor.tar.xz file using the “Download Container Sensor” button on the

Home page or from the Configurations > Sensors tab on Qualys Cloud Platform.

Copy the file to the target MAC host. Then run the following commands in sequence.

This command extracts the tar file:

sudo tar -xvf QualysContainerSensor.tar.xz

This command creates the directory where the sensor data like configuration, manifest,

logs, and setup is stored:

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

This command provides required permissions to the directory to run the installer script:

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

If you want to specify a custom location for storage, ensure that the Docker's File Sharing

is enabled for the same. On your MAC host, go to Docker > Preferences > File Sharing, add

the custom path e.g. /usr/local/qualys/sensor/data, then click Apply & Restart.

Enabling file sharing is required only if the custom location is NOT from /Users, /Volumes,

/private or /tmp.

To avoid this step, we recommend using Storage=/tmp/qualys/sensor/data and

HostIdSearchDir=/private/etc/qualys during sensor install. That way you can leverage the

existing shared location with docker, without the need of additional configuration to

launch the CS Sensor. If you are using a custom location, provide permissions to the

directory to run the installer script. For example:

sudo chmod -R 777 /usr/local/qualys/sensor/data

Installing the sensor on MacOS

Make sure CS Sensor has permissions to write to hostid file in /private/etc/qualys/

directory. To provide the sufficient permissions, execute:

sudo mkdir /private/etc/qualys/

sudo chmod 777 /private/etc/qualys

The following commands install the sensor. Notice that the command includes the

Activation ID and your Customer ID, both generated based on your subscription. The

Storage parameter specifies where to install the sensor. Ensure that the HostIdSearchDir

exists, otherwise the installer script will throw an error.

Use the following command to install a General Sensor:

sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

HostIdSearchDir=/private/etc/qualys Storage=/tmp/qualys/sensor/data -s

Use the following command to install a Registry Sensor:

sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

HostIdSearchDir=/private/etc/qualys Storage=/tmp/qualys/sensor/data -s -

-registry-sensor

Use the following command to install a CI/CD Sensor:

sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

HostIdSearchDir=/private/etc/qualys Storage=/tmp/qualys/sensor/data -s -

-cicd-deployed-sensor

Notes:

- If you want to install the Sensor without persistent storage, exclude the “Storage” option,

and include the “--sensor-without-persistent-storage” option in the installer script. 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.

- Secrets and malware detection is not supported on MacOS.

Installing the sensor on Linux

You can install the Qualys Container Sensor on Linux. Download the

QualysContainerSensor.tar.xz file using the “Download Container Sensor” button on the

Home page or from the Configurations > Sensors tab on Qualys Cloud Platform.

Copy the file to the target host. Then run the following commands in sequence.

This command extracts the tar file:

sudo tar -xvf QualysContainerSensor.tar.xz

This command creates the directory where the sensor data like configuration, manifest,

logs, and setup is stored:

sudo mkdir -p /usr/local/qualys/sensor/data

This command adds the required permissions to storage:

sudo chmod 777 /usr/local/qualys/sensor/data

The following commands install the sensor. Notice that the command includes the

Activation ID and your Customer ID, both generated based on your subscription. The

Storage parameter specifies where to install the sensor.

Use the following command to install a General Sensor:

sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

Storage=/usr/local/qualys/sensor/data -s

Use the following command to install a Registry Sensor:

sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

Storage=/usr/local/qualys/sensor/data -s -r

Use the following command to install a CI/CD Sensor:

sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

Storage=/usr/local/qualys/sensor/data -s -c

Note: To install the Sensor without persistent storage, exclude the “Storage” option, and

include the “--sensor-without-persistent-storage” option in the installer script. 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.

Installing the sensor on CoreOS

You can install the Qualys Container Sensor on CoreOS. Download the

QualysContainerSensor.tar.xz file using the “Download Container Sensor” button on the

Home page or from the Configurations > Sensors tab on Qualys Cloud Platform.

Copy the file to the target host. Then run the following commands in sequence.

This command extracts the tar file:

sudo tar -xvf QualysContainerSensor.tar.xz

This command creates the directory where the sensor data like configuration, manifest,

logs, and setup is stored:

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

Note: You need to set the directory path /var/opt/qualys/sensor/data to Storage which is

writable on CoreOS.

This command provides required permissions to the directory to run the installer script:

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

The following commands install the sensor. Notice that the command includes the

Activation ID and your Customer ID, both generated based on your subscription. The

Storage parameter specifies where to install the sensor.

Use the following command to install a General Sensor:

Sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

Storage=/var/opt/qualys/sensor/data/ -s

Use the following command to install a Registry Sensor:

Sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

Storage=/var/opt/qualys/sensor/data/ -s --registry-sensor

Use the following command to install a CI/CD Sensor:

Sudo ./installsensor.sh ActivationId=d5814d5f-5fd2-44ec-8969-

e03cc58a4ef5 CustomerId=6f35826e-4430-d75e-8356-c444a0abbb31

Storage=/var/opt/qualys/sensor/data/ -s --cicd-deployed-sensor

Note: To install the Sensor without persistent storage, exclude the “Storage” option, and

include the “--sensor-without-persistent-storage” option in the installer script. 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.

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker compose

Installing the sensor from Docker Hub

This section provides information on deploying the sensor through Docker Hub. Please

note that the Docker Hub sensor image is not supported for customers on a Private Cloud

Platform (PCP).

On standalone docker host:

Deploying the sensor on standalone docker host using docker compose

Deploying the sensor on standalone docker host using docker run

On Kubernetes:

Deploying the sensor using Docker Hub on Kubernetes

The Container Security Sensor on Docker Hub is available as:

qualys/qcs-sensor:<tag>

qualys/qcs-sensor:latest

Look up the most recent tag in Docker Hub.

Deploying the sensor on standalone docker host using docker

compose

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

Create a new yml file containing the following information. You can name the file

qualys_cs_sensor_docker_compose.yml.

Note: 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.

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker compose

# 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>

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.

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker compose

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).

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 ‘resources:limits:cpu’ option, or

comment it out.

Note: 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"]

Note: 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).

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker compose

"--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.

"--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. Note that

secret detection is supported only on CICD and registry sensors.

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker compose

"--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.

Note: 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.

Note: 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

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker compose

- /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

Note: 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>

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

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker compose

Note: The docker-compose does not provide an option to delete the persistent storage. You

must delete the persistent storage files manually.

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker run

Deploying the sensor on standalone docker host using docker

run

Prerequisites: Docker engine version: 1.13.0+

Run the following commands to install the sensor. 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 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.

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.

Note: 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

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

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker run

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:

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

--registry-sensor

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

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

CI/CD 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

--cicd-deployed-sensor

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker run

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

--cicd-deployed-sensor

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

--cicd-deployed-sensor

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:

1) If proxy is used to communicate with Qualys Cloud Platform, specify:

-e qualys_https_proxy=<IP/ address or FQDN>:<Port#>

2) If the proxy cert is required, mount volume for proxy certificate by adding:

-v <Proxy_File_Path>:/etc/qualys/qpa/cert/custom-ca.crt

3) 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.

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker run

4) /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.

5) 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

Note: 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

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>

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker run

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).

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 ‘resources:limits:cpu’ option, or

comment it out.

Note: 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.

--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.

Note: The sensor should be run either with "--sensor-without-persistent-storage" option or

with "--read-only" option and not with both options enabled together.

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker run

--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).

--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: performs static scanning as a fallback to

dynamic scanning for images without shell.

--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.

Installing the sensor from Docker Hub

Deploying the sensor on standalone docker host using docker run

--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.

--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.

Note: 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.

Note: 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.

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.

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

Prerequisites:

- Kubernetes setup should be up and running

- K8S nodes should be able to communicate with the Docker hub/private registry

- The container sensor image should be available in the private registry if you are

installing from there.

Modify the cssensor-ds.yml file

Create a new yml file containing the following information and name it cssensor-ds.yml

or download the yml file directly from https://github.com/Qualys/cs_sensor

Note: The field alignment in the yml file is very important. Please make sure to honor the

formatting provided in the below template.

kind: List

apiVersion: v1

items:

- kind: Namespace

apiVersion: v1

metadata:

# Service Account

- kind: ServiceAccount

apiVersion: v1

metadata:

namespace: qualys

# Role for read/write/delete permission to qualys namespace

- kind: Role

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

namespace: qualys

rules:

- apiGroups: ["","batch"]

resources: ["pods","jobs"]

verbs: ["get", "list", "watch","create", "delete",

"deletecollection"]

- apiGroups: [""]

resources: ["pods/status"]

verbs: ["get"]

- apiGroups: [""]

resources: ["pods/attach", "pods/exec"]

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

verbs: ["create"]

- kind: ClusterRole

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

rules:

- apiGroups: [""]

resources: ["nodes", "pods/status",

"replicationcontrollers/status", "nodes/status"]

verbs: ["get"]

- apiGroups: ["apps"]

resources: ["replicasets/status", "daemonsets/status",

"deployments/status", "statefulsets/status"]

verbs: ["get"]

- apiGroups: ["batch"]

resources: ["jobs/status", "cronjobs/status"]

verbs: ["get"]

# RoleBinding to assign permissions in qualys-reader-role to qualys-

service-account

- kind: RoleBinding

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

namespace: qualys

subjects:

- kind: ServiceAccount

namespace: qualys

roleRef:

kind: Role

apiGroup: rbac.authorization.k8s.io

- kind: ClusterRoleBinding

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

subjects:

- kind: ServiceAccount

namespace: qualys

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

roleRef:

kind: ClusterRole

apiGroup: rbac.authorization.k8s.io

# Qualys Container Sensor pod with

- apiVersion: apps/v1

kind: DaemonSet

metadata:

namespace: qualys

labels:

k8s-app: qualys-cs-sensor

spec:

selector:

matchLabels:

updateStrategy:

type: RollingUpdate

template:

metadata:

labels:

spec:

#tolerations:

# this toleration is to have the daemonset runnable on master

nodes

# remove it if want your masters to run sensor pod

#- key: node-role.kubernetes.io/master

# effect: NoSchedule

serviceAccountName: qualys-service-account

containers:

- name: qualys-container-sensor

image: qualys/qcs-sensor:latest

imagePullPolicy : IfNotPresent

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for

sensor.

args: ["--k8s-mode"]

env:

- name: CUSTOMERID

value: __customerId

- name: ACTIVATIONID

value: __activationId

- name: POD_URL

value:

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

- name: QUALYS_SCANNING_CONTAINER_LAUNCH_TIMEOUT

value: "10"

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- name: DOCKER_TLS_VERIFY

# value: "1"

# uncomment(and indent properly) below section if proxy is required to

connect Qualys Cloud

#- name: qualys_https_proxy

# value: <proxy FQDN or Ip address>:<port#>

- name: QUALYS_POD_NAME

valueFrom:

fieldRef:

fieldPath: metadata.name

- name: QUALYS_POD_NAMESPACE

valueFrom:

fieldRef:

fieldPath: metadata.namespace

volumeMounts:

- mountPath: /var/run/docker.sock

readOnly: true

- mountPath: /usr/local/qualys/qpa/data

- mountPath: /usr/local/qualys/qpa/data/conf/agent-data

# uncomment(and indent properly) below section if proxy(with CA cert)

required to connect Qualys Cloud

#- mountPath: /etc/qualys/qpa/cert/custom-ca.crt

# name: proxy-cert-path

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- mountPath: /root/.docker

# name: tls-cert-path

securityContext:

allowPrivilegeEscalation: false

volumes:

- name: socket-volume

hostPath:

path: /var/run/docker.sock

type: Socket

- name: persistent-volume

hostPath:

path: /usr/local/qualys/sensor/data

type: DirectoryOrCreate

- name: agent-volume

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

hostPath:

path: /etc/qualys

type: DirectoryOrCreate

# uncomment(and indent properly) below section if proxy(with CA cert)

required to connect Qualys Cloud

#- name: proxy-cert-path

# hostPath:

# path: <proxy certificate path>

# type: File

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- name: tls-cert-path

# hostPath:

# path: <Path of directory of client certificates>

# type: Directory

hostNetwork: true

Qualys Container Sensor DaemonSet should be deployed in 'qualys' namespace as a part

of ServiceAccount with adequate permission to communicate with Kubernetes API Server.

The Role, ClusterRole, RoleBinding and ClusterRoleBinding are used to assign the

necessary permissions to the ServiceAccount. If you already have Qualys Container

Sensor running in a different namespace other than 'qualys', you’ll need to first uninstall

Qualys Container Sensor from the other namespace and then deploy it fresh in 'qualys'

namespace.

You’ll need these permissions:

get, list, watch - to monitor the resources in 'qualys' namespace

create, delete, deletecollection - to spawn containers for image vulnerability assessment

in 'qualys' namespace then clean up after itself

Modify parameters in the yaml file

Copy the cssensor-ds.yml file to Kubernetes cluster’s master node then modify it by

providing values for the following parameters. In order for the yaml file to work properly,

ensure you only update the parameters/sections specified below. Note that you can

download the yaml file directly from https://github.com/Qualys/cs_sensor

Uncomment the tolerations section under spec if you want Sensor daemonset to be

deployed on master nodes.

spec:

#tolerations:

# this toleration is to have the daemonset runnable on master nodes

# remove it if want your masters to run sensor pod

#- key: node-role.kubernetes.io/master

# effect: NoSchedule

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

If you want to prioritize Qualys Sensor PODs:

Locate and Uncomment the below lines of code in the .yml file. And change the

PriorityClass value mentioned under kind: PriorityClass as per your requirement.

#- kind: PriorityClass

# apiVersion: scheduling.k8s.io/v1

# metadata:

# name: qualys-priority-class

# value: 0

# preemptionPolicy: PreemptLowerPriority

# description: Priority class for daemonset

Also, locate the PriorityClass name present below and Uncomment it.

#priorityClassName: qualys-priority-class

In order for the yml file to work properly, ensure that you do not remove/comment the

respective sections mentioned below. Ensure that from all Kubernetes nodes the Docker

hub/private registry (where the CS Sensor image is published) is accessible.

containers:

- name: qualys-container-sensor

image: <CS Sensor image name in the private/docker hub registry>

args: ["--k8s-mode"]

Note: Make sure all nodes that will be running sensor pod have access to private or docker

hub registry where sensor image is stored.

If you want to deploy the sensor for CI/CD environment provide the args value as:

args: ["--k8s-mode","--cicd-deployed-sensor"]

If you want to deploy a Registry Sensor provide the args value as: args:

["--k8s-mode","--registry-sensor"]

If you want print logs on the console, provide "--enable-console-logs" as an additional

value in args.

If you want to change the log level, provide "--log-level", "<a number between 0 and 5>" as

an additional value in args, e.g if you want logs in trace provide:

args: ["--k8s-mode", "--log-level", "5"]

If you want to launch the sensor with scan thread value other than default 4, provide

"-- scan-thread-pool-size", "<number of threads>" as an additional value in args.

args: ["--k8s-mode", "--scan-thread-pool-size", "6"]

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

If you want to define the number of archived qpa.log files to be generated provide "--log-

filepurgecount", "" as an additional value in args. The default, "--logfilepurgecount", "5" is

applied via config. Note that there will always be current qpa.log file in log/ directory.

If you want to define the number of archived qpa.log files to be generated and size per log

file, provide "--log-filesize", "" where "K" means kilobyte and "M" means megabyte, and

"--log-filepurgecount", "" as an additional value in args. Default is "--log-filesize": "10M" and

"--log-filepurgecount": "5" applied via config.

args: ["--k8s-mode", "--log-filesize", "5M", "--logfilepurgecount", "4"]

If you want image scanning pods to be instantiated using kubernetes native `kubectl run`

command provide "--use-kubectl" as an additional value in args. In this case sensor uses

native kubernetes facilities to launch image scans. When this argument is omitted image

containers are launched using docker run.

args: ["--k8s-mode", "--use-kubectl"]

If TLS authentication is enabled specify docker client certificate, client private key and CA

certificate names in the args,

args: ["--k8s-mode", "--tls-cacert","<file name of the CA certificate

that was used to sign docker server certificate>", "--tls-cert",

"<docker client certificate file name>", "--tls-key", "<docker client

private key file name>"]

Note: 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.

If you want to mask environment variables for images and containers in sensor logs and in

the Container Security UI, add the "--mask-env-variable" parameter to args:

args: ["--k8s-mode", "--mask-env-variable"]

If you want to disable image scans for General Sensor (supported for all Runtimes), add

the "--disableImageScan" parameter to args:

args: ["--k8s-mode", "--disableImageScan"]

If you want to specify a scanning policy, add the "--scanning-policy" parameter to args.

The available values for the scanning policy are: “DynamicScanningOnly”,

“StaticScanningOnly”, and “DynamicWithStaticScanningAsFallback”.

args: ["--k8s-mode", "--scanning-policy", “StaticScanningOnly”]

If you want to disable log4j vulnerability scanning on your container images, add the

"--disable-log4j-scanning" parameter to args:

args: ["--k8s-mode", "--disable-log4j-scanning"]

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

If you want to disable log4j static detection for dynamic/static image scans, add the

"--disable-log4j-static-detection" parameter to args:

args: ["--k8s-mode", "--disable-log4j-static-detection"]

If you want to optimize image scans for General Sensor, add the "--optimize-image-scans"

parameter to args:

args: ["--k8s-mode", "--optimize-image-scans"]

If you want to enable secret detection for container images, add the "--perform-secret-

detection" parameter to args:

args: ["--k8s-mode", “--container-runtime”, “containerd”, "--perform-

secret-detection"]

If you want to enable malware detection for container images, add the "--perform-

malware-detection" parameter to args:

args: ["--k8s-mode", “--registry-sensor”, "--perform-malware-detection"]

If you want to limit the memory usage of sensor container, add the "--limit-resource-

usage" parameter to args.

args: ["--k8s-mode", "--limit-resource-usage"]

Under resources specify the following:

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for sensor.

For example, for limiting the CPU usage to 5%, set resources:limits:cpu: "0.05". This limits

the CPU usage to 5% of one core on the host.

If there are multiple processors on a node, setting the resources:limits:cpu value applies

the CPU limit to one core 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 ‘resources:limits:cpu’ option, or

comment it out.

Optionally, if you want to specify the memory resources for Container Sensor, you can

specify it under resources. Recommended values for the Container Sensor’s memory

requests and memory limits are:

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for sensor

memory: "500Mi"

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

requests:

memory: "300Mi"

If you want to specify the memory resources for SCA Scan, or Secret Scan, or Malware

Scan you can specify it under resources. It is recommended to use "--limit-resource-

usage" argument while installing the sensor.

Recommended values for the Container Sensor’s memory requests and memory limits for

above mentioned scan types are:

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for sensor

memory: "3.5Gi"

requests:

memory: "1.5Gi"

Disclaimer: The above recommendation is based on the average image size of 1.5GB, if the

image sizes are more, please increase the memory limit accordingly.

When either of the memory resource values (limits or requests) is specified for Container

Sensor and “--use-kubectl” is supplied in args, we automatically apply both memory

requests and memory limits to image scanning containers. Default values are 200Mi and

700Mi, respectively.

Additionally, you could overwrite one or both values by specifying the following variables

under env. In this example, the values were changed to 300Mi and 800Mi.

- name: QUALYS_SCANNING_CONTAINER_MEMORYREQUESTMB

value: "300Mi"

- name: QUALYS_SCANNING_CONTAINER_MEMORYLIMITMB

value: "800Mi"

Under env specify the following:

Activation ID (Required)

- name: ACTIVATIONID

value: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Customer ID (Required)

- name: CUSTOMERID

value: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Specify POD_URL when using docker hub image. Otherwise, remove it.

- name: POD_URL

value: <Specify POD URL>

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

Specify the scanning container launch timeout in minutes. If this env variable is not

present, then 10 minutes is the default.

- name: QUALYS_SCANNING_CONTAINER_LAUNCH_TIMEOUT

value: "10"

With each scan, we check the node status to see if the node is schedulable or not, and

launch the scan only if the node is schedulable. If the node status indicates that the node

is unschedulable, then we retry the scan after a default interval of 15 minutes. You can

increase or decrease the time the sensor waits before retrying the scan by specifying a

different scan retry interval in minutes.

- name: UNSCHEDULABLE_NODE_SCAN_RETRY_INTERVAL

value: "30"

To enable TLS authentication uncomment the following 2 lines.

- name: DOCKER_TLS_VERIFY

value: "1"

Note: To disable TLS use DOCKER_TLS_VERIFY=""(empty string) or remove or keep it

commented in yml file.

Note: By enabling sensor communication with docker daemon over TLS customer can

restrict the sensor's access to docker socket by using docker authorization plugin.

Note: When TLS authentication is enabled and DOCKER_HOST is not specified the sensor

will automatically detect the FQDN of the worker node it is running on and set

DOCKER_HOST environment variable inside the sensor to <worker node's FQDN>:<2376>

where 2376 is the default TLS TCP port for docker daemon

Note: You can set DOCKER_HOST yourself to 127.0.0.1:<port#> or localhost:<port#> by

adding:

- name: DOCKER_HOST

value: "<loopback IPv4 address or hostname>:<port#>"

Note: Please make sure that FQDN, or hostname, or IPv4 address set in the DOCKER_HOST

matches the CN or Subject Alternative Name in the docker server certificate on each

worker node.

Uncomment and indent properly the proxy information, or keep it as is if not required:

- For the communication between the sensor and the backend (Container Management

Service):

#- name: qualys_https_proxy

# value: <proxy FQDN or Ip address>:<port#>

- For a registry sensor version 1.21.0 or later used for a public registry:

#- name: https_proxy

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

# value: <proxy FQDN or Ip address>:<port#>

Uncomment tls-cert-path under volumes if TLS authentication needs to be enabled and

provide directory path for client certificates, or keep it as is if not required:

#- name: tls-cert-path

# hostPath:

# path: <Path of directory of client certificates>

# type: Directory

Uncomment proxy-cert-path under volumes, or keep it as is if not required:

#- name: proxy-cert-path

# hostPath:

# path: /root/cert/proxy-certificate.crt

# type: File

Activation ID and Customer ID are required. Use the Activation ID and Customer ID 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.

If you are using an https proxy, ensure that all Kubernetes nodes have a valid certificate

file for the sensor to communicate with the Container Management Server.

If you are not using a proxy and you have kept the above-mentioned parts commented,

you can keep the following part commented from volumeMounts as well:

#- mountPath: /etc/qualys/qpa/cert/custom-ca.crt

# name: proxy-cert-path

If you are not using TLS and you have kept the above-mentioned parts commented, you

can keep the following part commented from volumeMounts as well:

#- mountPath: /root/.docker

# name: tls-cert-path

Remove hostNetwork: true when IP identification is not necessary

Remove/comment out the hostNetwork: true option to follow the security best practice of

least privilege, where host IP address identification is not necessary.

hostNetwork: true

The hostNetwork: true option provides the sensor the ability to detect the Docker host’s IP

address. The user can remove/comment out the hostNetwork: true line in the yaml file,

however a drawback is that the UI will show the docker bridge network IP address as the

Installing the sensor from Docker Hub

Deploying the sensor using Docker Hub on Kubernetes

host IP address. To aid with host identification, the hostname appears in the UI so

customers can identify the Docker host by hostname. We also recommend that the

hostname be unique within the environment.

Deploying the Container Sensor DaemonSet

Once you have created the cssensor-ds.yml file, run the following command on

Kubernetes master to create a DaemonSet:

kubectl create -f cssensor-ds.yml

Removing the Container Sensor DaemonSet

If you need to uninstall Qualys Container Sensor, run the following command on

Kubernetes master:

kubectl delete -f cssensor-ds.yml

Upgrading the Container Sensor DaemonSet

Perform the following steps on Kubernetes master for updating the Container Sensor

DaemonSet to a new version.

Note: Ensure that the Container Sensor DaemonSet is running in the Kubernetes

environment.

1) Get the name of the Container Sensor DaemonSet

kubectl get ds -n kube-system

2) Update the image for the DaemonSet to use new qualys/sensor image

kubectl set image ds/<daemonset-name> -n kube-system <container-

name>=<container-new-image>

3) Monitor Rollout status - this may take a while depending on the number of nodes

kubectl rollout status daemonset <daemonset-name> -n kube-system

4) If something goes wrong during rollout, rollback the DaemonSet to use the last image

kubectl rollout undo daemonset <daemonset-name> -n kube-system

Installing the CI/CD Sensor in Docker-in-Docker Environment

Step 1: Have the CS Sensor image inside a Docker-in-Docker Container

Installing the CI/CD Sensor in Docker-in-Docker

Environment

In this section we’ll describe how to install the CS Sensor in a CI/CD pipeline build for a

Docker-in-Docker environment. This will allow you to scan images inside the Docker-in-

Docker container.

Step 1: Have the CS Sensor image inside a Docker-in-Docker

Container

There are two ways to do this: 1) You can pull the CS Sensor image from the registry and

launch the sensor when the container is spun up, or 2) you can bake the Docker-in-Docker

container image with the CS Sensor tar in it.

Pull the CS Sensor image from the registry and launch the sensor

Benefits:

- No need to have pre-baked Docker-in-Docker container image with CS Sensor image/tar.

- You can easily use CS sensor image hosted on Docker hub registry

Disadvantages:

- All Docker-in-Docker containers need to have access to the registry.

- An image is pulled each time a Docker-in-Docker container is spun up and that would be

overhead.

Pre-baked Docker-in-Docker container image with CS sensor tar in it

Benefits:

- No need to have access to the registry from Docker-in-Docker container.

- The execution of a few commands and installsensor.sh script is enough to launch the CS

Sensor.

Disadvantages:

- The Docker-in-Docker container image size will be increased.

- You’ll need to re-bake the Docker-in-Docker image for each new sensor release.

Installing the CI/CD Sensor in Docker-in-Docker Environment

Step 2: Launch the Container Security Sensor

There are two ways to do this: 1) You can launch the sensor when the Docker-in-Docker

container boots up, or 2) launch the sensor from a build job. We’ll describe both methods.

Launch sensor on Docker-in-Docker container bootup

Benefits:

- No need to modify the build pipeline configuration to launch the CS Sensor.

Disadvantages:

- The credentials (Activation ID/Customer ID) need to be stored in the init script.

- Only predefined persistent storage path can be provided.

Launch init script inside the Docker-in-Docker container

Use the init script to launch the sensor. The init script will have following command:

docker run -d --restart on-failure --cpus=0.2 -v

/etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data -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 CS Sensor image

name from registry> --scan-thread-pool-size 4 --cicd-deployed-sensor

Use installsensor.sh script

Use the installsensor.sh script to launch the sensor on Docker-in-Docker bootup.

tar –xvf QualysContainerSensor.tar.xz

docker load -i qualys-sensor.tar

./installsensor.sh ActivationId=<Activation id> CustomerId=<Customer id>

HostIdSearchDir=/private/etc/qualys Storage=/tmp/qualys/sensor/data

--cicd-deployed-sensor -s

Launch sensor from build job

Benefits:

- Credentials (AI/CI) and sensor parameters can be passed from build job configuration.

- The persistent storage can be defined during launch.

- It’s easy to have a unique directory for each job (using Job ID) and using it as persistent

storage.

Disadvantages:

- You’ll need to modify the build job configuration to launch the CS Sensor.

Installing the CI/CD Sensor in Docker-in-Docker Environment

Step 2: Launch the Container Security Sensor

Launch CS Sensor using docker run command to pull image from registry

Launch the CS Sensor using the docker run command in order to pull the CS Sensor image

from the registry.

docker run -d --restart on-failure --cpus=0.2 -v

/etc/qualys:/usr/local/qualys/qpa/data/conf/agent-data -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 CS Sensor image

name from registry> --scan-thread-pool-size 4 --cicd-deployed-sensor

Launch CS Sensor as part of a build job using pre-baked Docker-in-Docker image

This command will launch the CS Sensor as part of a build job using a pre-baked Docker-

in-Docker container image with the CS Sensor tar in it. It will launch the CS Sensor as part

of the job.

<path>/installsensor.sh ActivationId=<Activation id>

CustomerId=<Customer id> HostIdSearchDir=/private/etc/qualys

Storage=/tmp/qualys/sensor/data --cicd-deployed-sensor -s

Persistent storage for CS sensor running in Docker-in-Docker build

container

Please provide the appropriate persistent storage for CS sensor so that the logs can be

retrieved in case of CS sensor failure or container image scan failure.

Deploying sensor in Kubernetes

This section provides steps for deploying the container sensor in Kubernetes.

Jump to a section:

How to Detect the Container Runtime in your Kubernetes Cluster Environment

Obtain the Container Sensor Image

Deploying the sensor using Docker Hub on Kubernetes

Deploy in Azure Kubernetes Service (AKS)

Deploy in Kubernetes - Docker Runtime

Deploy in Kubernetes - Containerd Runtime

Deploy in Kubernetes - CRI-O Runtime

Deploy in Kubernetes - OpenShift with CRI-O Runtime

Deploy in Kubernetes with TKGI - Docker Runtime

Deploy in Kubernetes with TKGI - Containerd Runtime

Deploy in Kubernetes with RKE1 - Docker Runtime

Deploy in Kubernetes with RKE2 - Containerd Runtime

Deploy in Google Kubernetes Engine (GKE) with multi-node clusters

Deploy in Kubernetes using Helm Charts

Collection of Kubernetes Cluster Attributes

Update the sensor deployed in Kubernetes

Deploying sensor in Kubernetes

How to Detect the Container Runtime in your Kubernetes Cluster Environment

How to Detect the Container Runtime in your Kubernetes

Cluster Environment

Before installing the sensor image, it’s important to know which container runtime is

installed in your Kubernetes Cluster environment. Knowing this will help you determine

what kind of sensor needs to be running in your environment.

You can get details about the container runtime by executing the following command:

kubectl get nodes -o wide

Use this command to get additional information about the cluster with details for each

node like name, status, roles, age, version, internal and external IP addresses, OS image,

kernel version. See the example below.

Obtain the Container Sensor Image

The first step for any Kubernetes deployment is to obtain the sensor image. You can

download QualysContainerSensor.tar.xz from the Container Security UI. Or you can use

the latest Qualys Container Sensor image - qualys/qcs-sensor:latest - from Docker Hub.

Download from UI

Download the sensor from the UI on a Linux computer with Docker installed on it.

Deploying sensor in Kubernetes

Obtain the Container Sensor Image

You can download sensor deployment templates either from the UI or from GitHub

directly at https://github.com/Qualys/cs_sensor. To get details on how to use the sensor

templates, follow the deployment steps outlined in the sections that follow.

Note: CRI-O Runtime are supported by the General (host) sensor and Registry sensor. It is

not supported by Build CI/CD sensor.

After downloading the file, untar the sensor package using this command:

sudo tar -xvf QualysContainerSensor.tar.xz

To load the images in Docker Runtime environment:

Push the Qualys sensor image to a repository common to all nodes in the Kubernetes

cluster using these commands:

sudo docker load -i qualys-sensor.tar

sudo docker tag <IMAGE NAME/ID> <URL to push image to the repository>

sudo docker push <URL to push image to the repository>

For example:

sudo docker load -i qualys-sensor.tar

sudo docker tag c3fa63a818df mycloudregistry.com/container-

Orchestration Platform Container Runtime Sensor Template

AWS ECS Docker cssensor-aws-ecs.json

Kubernetes (Cloud, On-Prem) Docker cssensor-ds.yml

Kubernetes (Cloud, On-Prem) Docker cssensor-ds_pv_pvc.yml

Kubernetes (Cloud, On-Prem) Containerd cssensor-containerd-ds.yml

Kubernetes (Cloud, On-Prem) CRI-O cssensor-crio-ds.yml

Docker Swarm Docker cssensor-swarm-ds.yml

Red Hat OpenShift Docker cssensor-openshift-ds.yml

Red Hat OpenShift CRI-O cssensor-openshift-crio-ds.yml

Deploying sensor in Kubernetes

Obtain the Container Sensor Image

sensor:qualys-sensor-xxx

sudo docker push mycloudregistry.com/container-sensor:qualys-sensor-xxx

Note: Do not use these examples as is. Replace the registry/image path with your own.

To load the images in Containerd Runtime environment:

Push the Qualys sensor image to a repository common to all nodes in the Kubernetes

cluster using these commands:

ctr -n=k8s.io images import qualys-sensor.tar

ctr images tag <IMAGE NAME/ID> <URL to push image to the repository>

ctr images push <URL to push image to the repository>

For example:

ctr -n=k8s.io images import qualys-sensor.tar

ctr images tag c3fa63a818df mycloudregistry.com/container-sensor:qualys-

sensor-xxx

ctr images push mycloudregistry.com/container-sensor:qualys-sensor-xxx

Note: Do not use these examples as is. Replace the registry/image path with your own.

To load the images in CRI-O Runtime environment:

Push the Qualys sensor image to a repository common to all nodes in the Kubernetes

cluster using these commands:

podman load -i qualys-sensor.tar

podman tag <IMAGE NAME/ID> <URL to push image to the repository>

podman push <URL to push image to the repository>

For example:

podman load -i qualys-sensor.tar

podman tag c3fa63a818df mycloudregistry.com/container-sensor:qualys-

sensor-xxx

podman push mycloudregistry.com/container-sensor:qualys-sensor-xxx

Note: Do not use these examples as is. Replace the registry/image path with your own.

Deploying sensor in Kubernetes

Deploy in Azure Kubernetes Service (AKS)

Get image from Docker Hub

Use the latest Qualys Container Sensor image - qualys/qcs-sensor:latest - from Docker

Hub. The Container Security Sensor on Docker Hub is available as:

qualys/qcs-sensor:<tag>

qualys/qcs-sensor:latest

Look up the most recent tag in Docker Hub. The Docker Hub Qualys Container Sensor

image can either be pushed to your private registry or used directly. Ensure that from all

Kubernetes nodes the Docker Hub/private registry (where the CS Sensor image is

published) is accessible.

Deploy in Azure Kubernetes Service (AKS)

The steps you take to deploy a sensor in Azure Kubernetes Service (AKS) clusters depends

on the Kubernetes version and the container runtime.

When deploying a sensor in AKS clusters using Kubernetes version 1.18 and older, and the

container runtime is Docker runtime, please see: Deploy in Kubernetes - Docker Runtime.

When deploying a sensor in AKS clusters using Kubernetes version 1.19, and the container

runtime is Containerd runtime, please see: Deploy in Kubernetes - Containerd Runtime.

Deploy in Kubernetes - Docker Runtime

This section assumes you have the sensor image: Obtain the Container Sensor Image

Integrate the Container Sensor into the DaemonSet like other application containers and

set the replication factor to 1 to ensure there is always a sensor deployed on the Docker

Host. This information is applicable for Amazon Elastic Container Service for Kubernetes

(Amazon EKS), Google Kubernetes Engine (GKE), and Azure Kubernetes Service (AKS).

Perform the following steps for creating a DaemonSet for the Qualys sensor to be deployed

in Kubernetes.

Note: Ensure that the Container Sensor has read and write access to the persistent storage

and the docker daemon socket.

Modify the cssensor-ds.yml file

Below is the Kubernetes DaemonSet deployment template that can be used to deploy the

Qualys Container Sensor. For customers' convenience, this template is available in the

QualysContainerSensor.tar.xz as cssensor-ds.yml file. Note that you can download the

yaml file directly from https://github.com/Qualys/cs_sensor

IMPORTANT: The field alignment in the yaml file is very important. Please make sure to

honor the formatting provided in the template.

kind: List

apiVersion: v1

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

items:

- kind: Namespace

apiVersion: v1

metadata:

# Service Account

- kind: ServiceAccount

apiVersion: v1

metadata:

namespace: qualys

# Role for read/write/delete permission to qualys namespace

- kind: Role

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

namespace: qualys

rules:

- apiGroups: ["","batch"]

resources: ["pods","jobs"]

verbs: ["get", "list", "watch","create", "delete",

"deletecollection"]

- apiGroups: [""]

resources: ["pods/status"]

verbs: ["get"]

- apiGroups: [""]

resources: ["pods/attach", "pods/exec"]

verbs: ["create"]

- kind: ClusterRole

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

rules:

- apiGroups: [""]

resources: ["nodes", "pods/status",

"replicationcontrollers/status", "nodes/status"]

verbs: ["get"]

- apiGroups: ["apps"]

resources: ["replicasets/status", "daemonsets/status",

"deployments/status", "statefulsets/status"]

verbs: ["get"]

- apiGroups: ["batch"]

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

resources: ["jobs/status", "cronjobs/status"]

verbs: ["get"]

# RoleBinding to assign permissions in qualys-reader-role to qualys-

service-account

- kind: RoleBinding

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

namespace: qualys

subjects:

- kind: ServiceAccount

namespace: qualys

roleRef:

kind: Role

apiGroup: rbac.authorization.k8s.io

- kind: ClusterRoleBinding

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

subjects:

- kind: ServiceAccount

namespace: qualys

roleRef:

kind: ClusterRole

apiGroup: rbac.authorization.k8s.io

# Qualys Container Sensor pod with

- apiVersion: apps/v1

kind: DaemonSet

metadata:

namespace: qualys

labels:

k8s-app: qualys-cs-sensor

spec:

selector:

matchLabels:

updateStrategy:

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

type: RollingUpdate

template:

metadata:

labels:

spec:

#tolerations:

# this toleration is to have the daemonset runnable on master

nodes

# remove it if want your masters to run sensor pod

#- key: node-role.kubernetes.io/master

# effect: NoSchedule

serviceAccountName: qualys-service-account

containers:

- name: qualys-container-sensor

image: qualys/qcs-sensor:latest

imagePullPolicy : IfNotPresent

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for

sensor.

args: ["--k8s-mode"]

env:

- name: CUSTOMERID

value: __customerId

- name: ACTIVATIONID

value: __activationId

- name: POD_URL

value:

- name: QUALYS_SCANNING_CONTAINER_LAUNCH_TIMEOUT

value: "10"

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- name: DOCKER_TLS_VERIFY

# value: "1"

# uncomment(and indent properly) below section if proxy is required to

connect Qualys Cloud

#- name: qualys_https_proxy

# value: <proxy FQDN or Ip address>:<port#>

- name: QUALYS_POD_NAME

valueFrom:

fieldRef:

fieldPath: metadata.name

- name: QUALYS_POD_NAMESPACE

valueFrom:

fieldRef:

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

fieldPath: metadata.namespace

volumeMounts:

- mountPath: /var/run/docker.sock

readOnly: true

- mountPath: /usr/local/qualys/qpa/data

- mountPath: /usr/local/qualys/qpa/data/conf/agent-data

# uncomment(and indent properly) below section if proxy(with CA cert)

required to connect Qualys Cloud

#- mountPath: /etc/qualys/qpa/cert/custom-ca.crt

# name: proxy-cert-path

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- mountPath: /root/.docker

# name: tls-cert-path

securityContext:

allowPrivilegeEscalation: false

volumes:

- name: socket-volume

hostPath:

path: /var/run/docker.sock

type: Socket

- name: persistent-volume

hostPath:

path: /usr/local/qualys/sensor/data

type: DirectoryOrCreate

- name: agent-volume

hostPath:

path: /etc/qualys

type: DirectoryOrCreate

# uncomment(and indent properly) below section if proxy(with CA cert)

required to connect Qualys Cloud

#- name: proxy-cert-path

# hostPath:

# path: <proxy certificate path>

# type: File

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- name: tls-cert-path

# hostPath:

# path: <Path of directory of client certificates>

# type: Directory

hostNetwork: true

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

Qualys Container Sensor DaemonSet should be deployed in 'qualys' namespace as a part

of ServiceAccount with adequate permission to communicate with Kubernetes API Server.

The Role, ClusterRole, RoleBinding and ClusterRoleBinding are used to assign the

necessary permissions to the ServiceAccount. If you already have Qualys Container

Sensor running in a different namespace other than 'qualys', you’ll need to first uninstall

Qualys Container Sensor from the other namespace and then deploy it fresh in 'qualys'

namespace.

You’ll need these permissions:

get, list, watch - to monitor the resources in 'qualys' namespace

create, delete, deletecollection - to spawn containers for image vulnerability assessment

in 'qualys' namespace then clean up after itself

Modify parameters in the yaml file

Copy the cssensor-ds.yml file to Kubernetes cluster’s master node then modify it by

providing values for the following parameters. In order for the yaml file to work properly,

ensure you only update the parameters/sections specified below. Note that you can

download the yaml file directly from https://github.com/Qualys/cs_sensor

Uncomment the tolerations section under spec if you want Sensor daemonset to be

deployed on master nodes.

spec:

#tolerations:

# this toleration is to have the daemonset runnable on master nodes

# remove it if want your masters to run sensor pod

#- key: node-role.kubernetes.io/master

# effect: NoSchedule

containers:

- name: qualys-container-sensor

image: <CS Sensor image name in the private/docker hub registry>

args: ["--k8s-mode"]

Note: Make sure all nodes that will be running sensor pod have access to private or docker

hub registry where sensor image is stored.

If you want to deploy the sensor for CI/CD environment provide the args value as:

args: ["--k8s-mode","--cicd-deployed-sensor"]

If you want to deploy a Registry Sensor provide the args value as:

args: ["--k8s-mode","--registry-sensor"]

If you want print logs on the console, provide "--enable-console-logs" as an additional

value in args.

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

If you want to change the log level, provide "--log-level", "<a number between 0 and 5>" as

an additional value in args, e.g if you want logs in trace provide:

args: ["--k8s-mode", "--log-level", "5"]

If you want to launch the sensor with scan thread value other than default 4, provide

"--scan-thread-pool-size", "<number of threads>" as an additional value in args.

args: ["--k8s-mode", "--scan-thread-pool-size", "6"]

If you want to define the number of archived qpa.log files to be generated provide

"--log-filepurgecount", "<digit>" as an additional value in args. The default, "--log-

filepurgecount", "5" is applied via config. Please note that there will always be current

qpa.log file in log/ directory.

If you want to define the number of archived qpa.log files to be generated and size per log

file, provide "--log-filesize", "<digit><K/M/>" where "K" means kilobyte and "M" means

megabyte, and "--log-filepurgecount", "<digit>" as an additional value in args. Default is

"--log-filesize": "10M" and "--log-filepurgecount": "5" applied via config.

args: ["--k8s-mode", "--log-filesize", "5M", "--log-

filepurgecount", "4"]

If you want image scanning pods to be instantiated using kubernetes native `kubectl run`

command provide "--use-kubectl" as an additional value in args. In this case sensor uses

native kubernetes facilities to launch image scans. When this argument is omitted image

containers are launched using `docker run`.

args: ["--k8s-mode", "--use-kubectl"]

If TLS authentication is enabled, specify docker client certificate, client private key and CA

certificate names in the args

args: ["--k8s-mode", "--tls-cacert","<file name of the CA

certificate that was used to sign docker server certificate>", "--

tls-cert", "<docker client certificate file name>", "--tls-key",

"<docker client private key file name>"]

Note: 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.

If you want to mask environment variables for images and containers in sensor logs and in

the Container Security UI, add the "--mask-env-variable" parameter to args:

args: ["--k8s-mode", "--mask-env-variable"]

If you want to disable image scans for General Sensor, add the "--disableImageScan"

parameter to args:

args: ["--k8s-mode", "--disableImageScan"]

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

If you want to specify a scanning policy, add the "--scanning-policy" parameter to args.

The available values for the scanning policy are: “DynamicScanningOnly”,

“StaticScanningOnly”, and “DynamicWithStaticScanningAsFallback”.

args: ["--k8s-mode", "--scanning-policy", “StaticScanningOnly”]

If you want to disable log4j vulnerability scanning on your container images, add the

"--disable-log4j-scanning" parameter to args:

args: ["--k8s-mode", "--disable-log4j-scanning"]

If you want to disable log4j static detection for dynamic/static image scans, add the

"--disable-log4j-static-detection" parameter to args:

args: ["--k8s-mode", "--disable-log4j-static-detection"]

If you want to optimize Image scans for General Sensor, add the "--optimize-image-scans"

parameter to args:

args: ["--k8s-mode", "--optimize-image-scans"]

If you have the SCA scanning feature, then you can enable SCA scanning for container

images by adding the "--perform-sca-scan" parameter to args:

args: ["--k8s-mode", "--perform-sca-scan"]

By default, SCA scans run in online mode. You can choose to disable Internet access for

the SCA scan and run the scan in offline mode. Note - 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.

args: ["--k8s-mode", "--perform-sca-scan" "--disallow-internet-

access-for-sca"]

The default SCA scan command timeout is 5 minutes (300 seconds). You can 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.

Note: The --sca-scan-timeout-in-seconds=600 parameter also applies to secret and

malware detection.

args: ["--k8s-mode", "--perform-sca-scan", "--sca-scan-timeout-in-

seconds=600"]

If you want to enable secret detection for container images, add the "--perform-secret-

detection" parameter to args. Note that secret detection is supported only on CICD and

registry sensors.

args: ["--k8s-mode", “--container-runtime”, “containerd”, "--

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

perform-secret-detection"]

If you want to enable malware detection for container images, add the "--perform-

malware-detection" parameter to args. Note that malware detection is supported only on

the registry sensor.

args: ["--k8s-mode", “--registry-sensor”, "--perform-malware-

detection"]

Under resources specify the following:

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for sensor.

For example, for limiting the CPU usage to 5%, set resources:limits:cpu: "0.05". This limits

the CPU usage to 5% of one core on the host.

If there are multiple processors on a node, setting the resources:limits:cpu value applies

the CPU limit to one core 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 ‘resources:limits:cpu’ option, or

comment it out.

Optionally, if you want to specify the memory resources for Container Sensor, you can

specify it under resources. Recommended values for the Container Sensor’s memory

requests and memory limits are:

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for sensor

memory: "500Mi"

requests:

memory: "300Mi"

When either of the memory resource values (limits or requests) is specified for Container

Sensor and “--use-kubectl” is supplied in args, we automatically apply both memory

requests and memory limits to image scanning containers. Default values are 200Mi and

700Mi, respectively.

Additionally, you could overwrite one or both values by specifying the following variables

under env. In this example, the values were changed to 300Mi and 800Mi.

- name: QUALYS_SCANNING_CONTAINER_MEMORYREQUESTMB

value: "300Mi"

- name: QUALYS_SCANNING_CONTAINER_MEMORYLIMITMB

value: "800Mi"

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

Under env specify the following:

Activation ID (Required)

- name: ACTIVATIONID

value: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Customer ID (Required)

- name: CUSTOMERID

value: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Specify POD_URL when using docker hub image. Otherwise, remove it.

- name: POD_URL

value: <Specify POD URL>

Specify the scanning container launch timeout in minutes. If this env variable is not

present, then 10 minutes is the default.

- name: QUALYS_SCANNING_CONTAINER_LAUNCH_TIMEOUT

value: "10"

To enable TLS authentication uncomment the following 2 lines.

- name: DOCKER_TLS_VERIFY

value: "1"

Note: To disable TLS use DOCKER_TLS_VERIFY=""(empty string) or remove it or keep it

commented in yml file.

Note: By enabling sensor communication with docker daemon over TLS customer can

restrict the sensor's access to docker socket by using docker authorization plugin.

Note: When TLS authentication is enabled and DOCKER_HOST is not specified the sensor

will automatically detect the FQDN of the worker node it is running on and set

DOCKER_HOST environment variable inside the sensor to <worker node's FQDN>:<2376>

where 2376 is the default TLS TCP port for docker daemon

Note: You can set DOCKER_HOST yourself to 127.0.0.1:<port#> or localhost:<port#> by

adding:

- name: DOCKER_HOST

value: "<loopback IPv4 address or hostname>:<port#>"

Note: Please make sure that FQDN, or hostname, or IPv4 address set in the DOCKER_HOST

matches the CN or Subject Alternative Name in the docker server certificate on each

worker node

Uncomment tls-cert-path under volumes if TLS authentication needs to be enabled and

provide directory path for client certificates, or keep it as is if not required:

#- name: tls-cert-path

# hostPath:

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

# path: <Path of directory of client certificates>

# type: Directory

With each scan, we check the node status to see if the node is schedulable or not, and

launch the scan only if the node is schedulable. If the node status indicates that the node

is unschedulable, then we retry the scan after a default interval of 15 minutes. You can

increase or decrease the time the sensor waits before retrying the scan by specifying a

different scan retry interval in minutes.

- name: UNSCHEDULABLE_NODE_SCAN_RETRY_INTERVAL

value: "30"

Uncomment below part under volumeMounts as well if you are using TLS. Otherwise,

keep it commented out.

#- mountPath: /root/.docker

#name: tls-cert-path

Uncomment and indent properly the proxy information, or keep it as is if not required:

- For the communication between the sensor and the backend (Container Management

Service):

#- name: qualys_https_proxy

# value: <proxy FQDN or Ip address>:<port#>

- For a registry sensor version 1.21.0 or later used for a public registry:

#- name: https_proxy

# value: <proxy FQDN or Ip address>:<port#>

Uncomment proxy-cert-path under volumes, or keep it as is if not required:

#- name: proxy-cert-path

# hostPath:

# path: /root/cert/proxy-certificate.crt

# type: File

Activation ID and Customer ID are required. Use the Activation ID and Customer ID 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.

If you are using an https proxy, ensure that all Kubernetes nodes have a valid certificate

file for the sensor to communicate with the Container Management Server.

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

If you are not using a proxy and you have kept the above-mentioned parts commented,

you can keep the following part commented from volumeMounts as well:

#- mountPath: /etc/qualys/qpa/cert/custom-ca.crt

# name: proxy-cert-path

Once you have modified the cssensor-ds.yml file, run the following command on

Kubernetes master to create a DaemonSet:

kubectl create -f cssensor-ds.yml

If you need to uninstall Qualys Container Sensor, run the following command on

Kubernetes master:

kubectl delete -f cssensor-ds.yml

Note: The persistent storage will need to be removed manually on each worker node.

Using Persistent Volume Claims

You can use PersistentVolumeClaim (PVC) to request for storage of specific size from the

gross Persistent Volume you have specified.

Modify the cssensor-ds_pv_pvc.yml file

Below is the cssensor-ds_pv_pvc.yml. For customers' convenience, the cssensor-

ds_pv_pvc.yml file can be extracted from QualysContainerSensor.tar.xz. Note that you

can download the yaml file directly from https://github.com/Qualys/cs_sensor

IMPORTANT: The field alignment in the yaml file is very important. Please make sure to

honor the formatting provided in the template.

kind: List

apiVersion: v1

items:

- kind: Namespace

apiVersion: v1

metadata:

- kind: PersistentVolume

apiVersion: v1

metadata:

labels:

type: local

spec:

storageClassName: manual

capacity:

storage: 5Gi

accessModes:

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

- ReadWriteOnce

hostPath:

path: "/mnt/data/"

- kind: PersistentVolumeClaim

apiVersion: v1

metadata:

namespace: qualys

spec:

storageClassName: manual

accessModes:

- ReadWriteOnce

resources:

requests:

storage: 1Gi

# Service Account

- kind: ServiceAccount

apiVersion: v1

metadata:

namespace: qualys

# Role for read/write/delete permission to qualys namespace

- kind: Role

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

namespace: qualys

rules:

- apiGroups: ["","batch"]

resources: ["pods","jobs"]

verbs: ["get", "list", "watch","create", "delete",

"deletecollection"]

- apiGroups: [""]

resources: ["pods/status"]

verbs: ["get"]

- apiGroups: [""]

resources: ["pods/attach", "pods/exec"]

verbs: ["create"]

- kind: ClusterRole

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

rules:

- apiGroups: [""]

resources: ["nodes", "pods/status",

"replicationcontrollers/status", "nodes/status"]

verbs: ["get"]

- apiGroups: ["apps"]

resources: ["replicasets/status", "daemonsets/status",

"deployments/status", "statefulsets/status"]

verbs: ["get"]

- apiGroups: ["batch"]

resources: ["jobs/status", "cronjobs/status"]

verbs: ["get"]

# RoleBinding to assign permissions in qualys-reader-role to qualys-

service-account

- kind: RoleBinding

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

namespace: qualys

subjects:

- kind: ServiceAccount

namespace: qualys

roleRef:

kind: Role

apiGroup: rbac.authorization.k8s.io

- kind: ClusterRoleBinding

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

subjects:

- kind: ServiceAccount

namespace: qualys

roleRef:

kind: ClusterRole

apiGroup: rbac.authorization.k8s.io

# Qualys Container Sensor pod with

- apiVersion: apps/v1

kind: DaemonSet

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

metadata:

namespace: qualys

labels:

k8s-app: qualys-cs-sensor

spec:

selector:

matchLabels:

updateStrategy:

type: RollingUpdate

template:

metadata:

labels:

spec:

#tolerations:

# this toleration is to have the daemonset runnable on master

nodes

# remove it if want your masters to run sensor pod

#- key: node-role.kubernetes.io/master

# effect: NoSchedule

serviceAccountName: qualys-service-account

containers:

- name: qualys-container-sensor

image: qualys/qcs-sensor:latest

imagePullPolicy : IfNotPresent

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for

sensor.

args: ["--k8s-mode"]

env:

- name: CUSTOMERID

value: __customerId

- name: ACTIVATIONID

value: __activationId

- name: POD_URL

value:

- name: QUALYS_SCANNING_CONTAINER_LAUNCH_TIMEOUT

value: "10"

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- name: DOCKER_TLS_VERIFY

# value: "1"

# uncomment(and indent properly) below section if proxy is required to

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

connect Qualys Cloud

#- name: qualys_https_proxy

# value: <proxy FQDN or Ip address>:<port#>

- name: QUALYS_POD_NAME

valueFrom:

fieldRef:

fieldPath: metadata.name

- name: QUALYS_POD_NAMESPACE

valueFrom:

fieldRef:

fieldPath: metadata.namespace

volumeMounts:

- mountPath: /var/run/docker.sock

readOnly: true

- mountPath: /usr/local/qualys/qpa/data

- mountPath: /usr/local/qualys/qpa/data/conf/agent-data

# uncomment(and indent properly) below section if proxy(with CA cert)

required to connect Qualys Cloud

#- mountPath: /etc/qualys/qpa/cert/custom-ca.crt

# name: proxy-cert-path

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- mountPath: /root/.docker

# name: tls-cert-path

securityContext:

allowPrivilegeEscalation: false

volumes:

- name: socket-volume

hostPath:

path: /var/run/docker.sock

type: Socket

- name: persistent-volume

persistentVolumeClaim:

claimName: qualys-sensor-pv-claim

- name: agent-volume

hostPath:

path: /etc/qualys

type: DirectoryOrCreate

# uncomment(and indent properly) below section if proxy(with CA cert)

required to connect Qualys Cloud

#- name: proxy-cert-path

# hostPath:

# path: <proxy certificate path>

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

# type: File

# uncomment(and indent properly) below section if using Docker HTTP

socket with TLS

#- name: tls-cert-path

# hostPath:

# path: <Path of directory of client certificates>

# type: Directory

hostNetwork: true

Modify parameters in the yaml file

Modify the cssensor-ds_pv_pvc.yml file to provide values for the following parameters. In

order for the yml file to work properly, ensure that you do not remove/comment the

respective sections mentioned below. Note that you can download the yml file directly

from https://github.com/Qualys/cs_sensor

- kind: PersistentVolume

apiVersion: v1

metadata:

labels:

type: local

spec:

storageClassName: manual

capacity:

storage: 5Gi

accessModes:

- ReadWriteOnce

hostPath:

path: "/mnt/data/"

- kind: PersistentVolumeClaim

apiVersion: v1

metadata:

namespace: qualys

spec:

storageClassName: manual

accessModes:

- ReadWriteOnce

resources:

requests:

storage: 1Gi

Here a PVC of 1Gi is made on a Persistent Volume to 5Gi. Click here for a list of supported

Persistent Volume Types.

Add the name of the PVC under volumes:

Deploying sensor in Kubernetes

Deploy in Kubernetes - Docker Runtime

- name: persistent-volume

persistentVolumeClaim:

claimName: qualys-sensor-pv-claim

Launch sensor without persistent storage

You can run the sensor without using persistent storage on host. In this case data is not

stored on host but stored at the /usr/local/qualys/qpa/data folder relative to the Sensor.

To launch sensor without persistent storage, modify the cssensor-ds.yml file and provide

"--sensor-without-persistent-storage" as an additional value in args.

args: ["--k8s-mode","--sensor-without-persistent-storage"]

It is recommended to use the "--enable-console-logs" option along with "--sensor-without-

persistent-storage" to preserve the logs.

Under volumeMounts remove/comment the persistent-volume section.

volumeMounts:

- mountPath: /usr/local/qualys/qpa/data

Under volumes remove/comment the persistent-volume section.

volumes:

- name: persistent-volume

hostPath:

path: /usr/local/qualys/sensor/data

type: DirectoryOrCreate

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

This section assumes you have the sensor image: Obtain the Container Sensor Image

Modify the cssensor-containerd-ds.yml file

Below is the Kubernetes DaemonSet deployment template that can be used to deploy the

Qualys Container Sensor. For customers' convenience this template is available in the

QualysContainerSensor.tar.xz. Note that you can download the yml file directly from

https://github.com/Qualys/cs_sensor

IMPORTANT: The field alignment in the yml file is very important. Please make sure to

honor the formatting provided in the template.

kind: List

apiVersion: v1

items:

# Create custom namespace qualys

- kind: Namespace

apiVersion: v1

metadata:

# Service Account

- kind: ServiceAccount

apiVersion: v1

metadata:

namespace: qualys

# Role for all permission to qualys namespace

- kind: Role

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

namespace: qualys

rules:

- apiGroups: ["","batch"]

resources: ["pods","jobs"]

verbs: ["get", "list", "watch","create", "delete",

"deletecollection"]

- apiGroups: [""]

resources: ["pods/attach", "pods/exec"]

verbs: ["create"]

# ClusterRole for read permission to whole cluster

- kind: ClusterRole

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

apiVersion: rbac.authorization.k8s.io/v1

metadata:

rules:

- apiGroups: [""]

resources: ["pods/exec"]

verbs: ["create"]

- apiGroups: [""]

resources: ["nodes", "pods", "pods/status",

"replicationcontrollers/status", "nodes/status"]

verbs: ["get"]

- apiGroups: ["apps"]

resources: ["replicasets/status", "daemonsets/status",

"deployments/status", "statefulsets/status"]

verbs: ["get"]

- apiGroups: ["batch"]

resources: ["jobs/status", "cronjobs/status"]

verbs: ["get"]

# RoleBinding to assign permissions in qualys-reader-role to qualys-

service-account

- kind: RoleBinding

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

namespace: qualys

subjects:

- kind: ServiceAccount

namespace: qualys

roleRef:

kind: Role

apiGroup: rbac.authorization.k8s.io

# ClusterRoleBinding to assign permissions in qualys-cluster-reader-

role to qualys-service-account

- kind: ClusterRoleBinding

# if k8s version is 1.17 and earlier then change apiVersion to

"rbac.authorization.k8s.io/v1beta1"

apiVersion: rbac.authorization.k8s.io/v1

metadata:

subjects:

- kind: ServiceAccount

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

namespace: qualys

roleRef:

kind: ClusterRole

apiGroup: rbac.authorization.k8s.io

# Qualys Container Sensor pod with

- apiVersion: apps/v1

kind: DaemonSet

metadata:

namespace: qualys

labels:

k8s-app: qualys-cs-sensor

spec:

selector:

matchLabels:

updateStrategy:

type: RollingUpdate

template:

metadata:

labels:

spec:

#tolerations:

# this toleration is to have the daemonset runnable on master

nodes

# remove it if want your masters to run sensor pod

#- key: node-role.kubernetes.io/master

# effect: NoSchedule

serviceAccountName: qualys-service-account

containers:

- name: qualys-container-sensor

image: qualys/qcs-sensor:latest

imagePullPolicy : IfNotPresent

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for

sensor.

args: ["--k8s-mode", "--container-runtime", "containerd"]

env:

- name: CUSTOMERID

value: __customerId

- name: ACTIVATIONID

value: __activationId

- name: POD_URL

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

value:

- name: QUALYS_SCANNING_CONTAINER_LAUNCH_TIMEOUT

value: "10"

# uncomment(and indent properly) below section if proxy is required to

connect Qualys Cloud

#- name: qualys_https_proxy

# value: <proxy FQDN or Ip address>:<port#>

- name: QUALYS_POD_NAME

valueFrom:

fieldRef:

fieldPath: metadata.name

- name: QUALYS_POD_NAMESPACE

valueFrom:

fieldRef:

fieldPath: metadata.namespace

volumeMounts:

- mountPath: /var/run/containerd/containerd.sock

readOnly: true

- mountPath: /usr/local/qualys/qpa/data

- mountPath: /usr/local/qualys/qpa/data/conf/agent-data

# uncomment(and indent properly) below section if proxy(with CA cert)

required to connect Qualys Cloud

#- mountPath: /etc/qualys/qpa/cert/custom-ca.crt

# name: proxy-cert-path

securityContext:

allowPrivilegeEscalation: false

volumes:

- name: socket-volume

hostPath:

path: /var/run/containerd/containerd.sock

type: Socket

- name: persistent-volume

hostPath:

path: /usr/local/qualys/sensor/data

type: DirectoryOrCreate

- name: agent-volume

hostPath:

path: /etc/qualys

type: DirectoryOrCreate

# uncomment(and indent properly) below section if proxy(with CA cert)

required to connect Qualys Cloud

#- name: proxy-cert-path

# hostPath:

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

# path: <proxy certificate path>

# type: File

hostNetwork: true

Qualys Container Sensor DaemonSet should be deployed in 'qualys' namespace as part of

ServiceAccount with adequate permission to communicate with Kubernetes API Server.

The Role, ClusterRole, RoleBinding and ClusterRoleBinding are used to assign the

necessary permissions to ServiceAccount. If you already have Qualys Container Sensor

running in a different namespace other than 'qualys', you’ll need to uninstall Qualys

Container Sensor from the other namespace and deploy it fresh in the 'qualys' namespace.

You’ll need these permissions:

get, list, watch - to monitor the resources to be scanned for vulnerabilities across the

cluster

create, delete, deletecollection - to spawn containers for image vulnerability assessment

in 'qualys' namespace, scan pods across the cluster and then clean up after itself

Note: Ensure that the Container Sensor has read and write access to the persistent storage

and the containerd daemon socket.

Modify parameters in the yaml file

Copy the cssensor-containerd-ds.yml file to Kubernetes cluster's master node then

modify it by providing values for the following parameters. In order for the yaml file to

work properly, ensure you only update the parameters/sections specified below. Note that

you can download the yml file directly from https://github.com/Qualys/cs_sensor

General Sensor is assumed here. Uncomment the tolerations section under spec if you

want Sensor daemonset to be deployed on master nodes.

spec:

#tolerations:

# this toleration is to have the daemonset runnable on master nodes

# remove it if want your masters to run sensor pod

#- key: node-role.kubernetes.io/master

# effect: NoSchedule

If you want to prioritize Qualys Sensor PODs:

Locate and Uncomment the below lines of code in the .yml file. And change the

PriorityClass value mentioned under kind: PriorityClass as per your requirement.

#- kind: PriorityClass

# apiVersion: scheduling.k8s.io/v1

# metadata:

# name: qualys-priority-class

# value: 0

# preemptionPolicy: PreemptLowerPriority

# description: Priority class for daemonset

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

Also, locate the PriorityClass name present below and Uncomment it.

#priorityClassName: qualys-priority-class

containers:

- name: qualys-container-sensor

image: <CS Sensor image name in the private/docker hub registry>

args: ["--k8s-mode", "--container-runtime", "containerd"]

If you want to deploy a Registry Sensor provide the args value as:

args: ["--k8s-mode","--container-runtime", "containerd", "--

registry-sensor"]

If you want to deploy a CICD Sensor provide the args value as:

args: ["--k8s-mode","--container-runtime", "containerd", "--cicd-

deployed-sensor"]

If you want to change the log level, provide "--log-level", "<a number between 0 and 5>" as

an additional value in args, e.g if you want logs in trace provide:

args: ["--k8s-mode", "--container-runtime", "containerd", "--log-

level", "5"]

If you want to launch the sensor with scan thread value other than default 4, provide

"--scan-thread-pool-size", "<number of threads>" as an additional value in args.

args: ["--k8s-mode", "--container-runtime", "containerd", "--scan-

thread-pool-size", "6"]

If you want to define the number of archived qpa.log files to be generated and size per log

file, provide "--log-filesize", "<digit><K/M/>" where "K" means kilobyte and "M" means

megabyte, and "--log-filepurgecount", "<digit>" as an additional value in args. Default is

"--log-filesize": "10M" and "--log-filepurgecount": "5" applied via config.

"--log-filesize": can be used to define the maximum size per log file. For example, "10K"

(kilobytes), "10M" (megabytes) or "10" (bytes).

"--log-filepurgecount": can be used to define the number of archived log files to be

generated, please note that there will always be current qpa.log file in log/ directory.

args: ["--k8s-mode", "--container-runtime", "containerd", "--log-

filesize", "5M", "--log-filepurgecount", "4"]

If you want to mask environment variables for images and containers in sensor logs and in

the Container Security UI, add the "--mask-env-variable" parameter to args:

args: ["--k8s-mode", "--container-runtime", "containerd", "--mask-

env-variable"]

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

If you want to disable image scans for General Sensor, add the "--disableImageScan"

parameter to args:

args: ["--k8s-mode", "--container-runtime", "containerd", "--

disableImageScan"]

If you want to specify a scanning policy, add the "--scanning-policy" parameter to args.

The available values for the scanning policy are: “DynamicScanningOnly”,

“StaticScanningOnly”, and “DynamicWithStaticScanningAsFallback”.

args: ["--k8s-mode", "--scanning-policy", “StaticScanningOnly”]

If you want to disable log4j vulnerability scanning on your container images, add the

"--disable-log4j-scanning" parameter to args:

args: ["--k8s-mode", "--container-runtime", "containerd", "--

disable-log4j-scanning"]

If you want to disable log4j static detection for dynamic/static image scans, add the

"--disable-log4j-static-detection" parameter to args:

args: ["--k8s-mode", "--container-runtime", "containerd", "--

disable-log4j-static-detection"]

If you want to optimize Image scans for General Sensor, add the "--optimize-image-scans"

parameter to args:

args: ["--k8s-mode", "--container-runtime", "containerd", "--

optimize-image-scans"]

If you want to enable secret detection for container images, add the "--perform-secret-

detection" parameter to args. Note that secret detection is supported only on CICD and

registry sensors.

args: ["--k8s-mode", "--container-runtime", "containerd", "--

perform-secret-detection"]

If you want to enable malware detection for container images, add the "--perform-

malware-detection" parameter to args. Note that malware detection is supported only on

registry sensor.

args: ["--k8s-mode", "--registry-sensor", "--perform-malware-

detection"]

If you want to scan the secured private registry (HTTPS) having a self-signed certificate,

you can either provide the certificate through the yaml file or use the "--insecure-registry"

argument to ignore the certificate check.

In case you provide both - the certificate through the yaml file and you use "--insecure-

registry" argument - you will be able to login to the secured private registry.

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

args: ["--k8s-mode", “--container-runtime”, “containerd”, "--

registry-sensor", "--insecure-registry"]

If you want to use the Storage Driver,

1. Provide the following arguments

args: ["--k8s-mode", "--container-runtime", "containerd","--

storage-driver-type","overlay"]

2. Uncomment the below sections.

#- mountPath: /var/lib/containerd

# name: containerd-root-dir

# readOnly: true

and

#- name: containerd-root-dir

# hostPath:

# path: /var/lib/containerd # if root directory of containerd is different then

update actual containerd root directory path

Note: Currently, CS Sensor supports ’Overlay’ storage driver only.

To provide self-signed certificate through the Yaml file, follow the steps mentioned below.

1. Open the .yaml file, and search "volumeMounts:".

2. Uncomment the following lines from the code.

# name: registry-cert-volume

# subPath: ca.crt

# readOnly: true

3. Similarly, uncomment the following lines and save the file.

# - name: registry-cert-volume

# secret:

# secretName: cert-config

If you want to limit the memory usage of sensor container, add the "--limit-resource-

usage" parameter to args.

args: ["--k8s-mode", "--limit-resource-usage"]

Deploying sensor in Kubernetes

Deploy in Kubernetes - Containerd Runtime

Under resources specify the following:

resources:

limits:

cpu: 0.2 # Default CPU usage limit (20% of one core on the host).

For example, for limiting the cpu usage to 5%, set resources:limits:cpu: "0.05". This limits

the cpu usage to 5% of one core on the host.

If there are multiple processors on a node, setting the resources:limits:cpu value applies

the CPU limit to one core 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 ‘resources:limits:cpu’ option, or

comment it out.

Optionally, if you want to specify the memory resources for Container Sensor, you can

specify it under resources.

Recommended values for the Container Sensor’s memory requests and memory limits for

a VM Scan are:

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for sensor

memory: "500Mi"

requests:

memory: "300Mi"

If you want to specify the memory resources for SCA Scan, or Secret Scan, or Malware

Scan you can specify it under resources. It is recommended to use "--limit-resource-

usage" argument while installing the sensor.

Recommended values for the Container Sensor’s memory requests and memory limits for

above mentioned scan types are:

resources:

limits:

cpu: "0.2" # Default CPU usage limit on each node for sensor

memory: "3.5Gi"

requests:

memory: "1.5Gi"

Disclaimer: The above recommendation is based on the average image size of 1.5GB, if the

image sizes are more, please increase the memory limit accordingly.

When either of the memory resource values (limits or requests) is specified for Container

Sensor, we automatically apply both memory requests and memory limits to image

scanning containers. Default values are 200Mi and 700Mi, respectively.