Troubleshooting

When creating a Containerized Scanner, you can encounter the following errors. This troubleshooting section can help fix these errors.

QCSA Containerized Scanner UID Mode

Qualys strongly recommends against running the containerized scanner in rootless mode, as it can impact scan performance and affect the consistency of vulnerability results. New log messages have been added to warn users when the containerized scanner is run in rootless mode.

Warning messages

It is strongly recommended to run this container in rootfull mode. Current UID=0 maps to external UID=1000
Heads up: running in rootless container mode can impact scan performance and the consistency of vulnerability results
That’s because the network stack is emulated and NAT happens in user space
If you understand the risks and still want to go ahead, add: -e AUTHORIZE_ROOTLESS=yes

If users understand the risks and still choose to proceed, they must explicitly authorize it by adding the environment variable: -e AUTHORIZE_ROOTLESS=yes.

Authorizing rootless mode

user@localhost:~$ SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; podman run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e DISREGARD_PID_LIMIT=yes --cap-add=net_raw -e AUTHORIZE_ROOTLESS=yes -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com abecffadebed
52e801a85ab8c838d9e28928b121695e3a16b03f166fa8bc6814d18d91a9da5c
user@localhost:~$

Rootless Mode with Host Networking – Restricted Operation Warning

Vulnerability scanning requires RAW sockets. Containerized scanner in rootless mode with host networking configured, may affect vulnerability scanning abilities, as it cannot access RAW sockets due to insufficient privileges. To prevent this configuration, an intentional check has been introduced to block the use of rootless mode with host networking.

Restricted Operation Detection

Vulnerability scannning requires use of RAW sockets, but the socket() call test has failed. It may happen when a container runs in rootless mode while configured to use host networking.

Handling Low cgroups PID Limit on Linux Hosts

A low cgroups PID limit on a Linux host, may prevent the QCSA containerized scanner from executing larger scans. New log messages have been introduced to alert users when this limit is detected and to offer options on either removing the PID restriction or bypassing the check by overriding it.

Log Warning: PID Limit Too Low for Scan Execution

cgroups pids.max value is set and it's too low (2048) for even a moderately sized scan job.
Use --pids-limit -1 option to remove the limit, or -e DISREGARD_PID_LIMIT=yes option to override the check.

You can remove the PID limit by using the --pids-limit -1 option in your podman run command. Example:

root@localhost:~$ SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; podman run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" --pids-limit -1 --cap-add=net_raw -e AUTHORIZE_ROOTLESS=yes -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com abecffadebed
9f4d3bc78e2a1f643c7de082adfe1296b0c8a17d5e32fac96147b20dce85b47a
root@localhost:~$

If you understand the risks and still want to proceed, you can override the PID limit check using the -e DISREGARD_PID_LIMIT=yes environment variable. Example:

root@localhost:~$ SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; podman run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e DISREGARD_PID_LIMIT=yes --cap-add=net_raw -e AUTHORIZE_ROOTLESS=yes -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com abecffadebed
52e801a85ab8c838d9e28928b121695e3a16b03f166fa8bc6814d18d91a9da5c
root@localhost:~$

SELinux Blocking Bind Mount

[root@localhost ~]# PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p /usr/qualys/private/$PERSONALIZATION_CODE; docker run -d -v /usr/qualys/common:/usr/local/qualys -v  /usr/qualys/private/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com 6715167e4412 5c27fbb12cdbbfe97da68300ace95fe4e426cb997a83c5f37dcf87fc63e34a1b
[root@localhost ~]# docker logs -f Qualys_Container
Shared store is not writable. If host SELinux is in enforcing mode, use -v  <host_dir>:/usr/local/qualys:z mount option To see embedded manual, run container with 'help' parameter
[root@localhost ~]#

Labeling systems like SELinux require proper labels placed on volume content mounted into a container. Without a label, the security system might prevent the processes running inside the container from using the content. By default, Docker does not change the labels set by the OS.
To change a label in the container context, the user must add the suffix :z to the volume mounts. This suffix tell Podman to relabel file objects on the shared volumes. The z option tells Podman that containers share the volume content. As a result, Podman labels the content as shared content. Shared volume labels allow all containers to read/write content.
If SELinux is enabled on the linux host & if the :z suffix with bind mount is not used, the user might run into the following error. 

root@localhost:~$ SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; podman run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e DISREGARD_PID_LIMIT=yes --cap-add=net_raw -e AUTHORIZE_ROOTLESS=yes -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com abecffadebed
52e801a85ab8c838d9e28928b121695e3a16b03f166fa8bc6814d18d91a9da5c
root@localhost:~$

Seccomp Errors

Example error.

[root@localhost ~]# PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p /usr/qualys/private/$PERSONALIZATION_CODE; docker run -d -v /usr/qualys/common:/usr/local/qualys:z 
-v /usr/qualys/private/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com 6715167e4412
Error: runc: container_linux.go:370: starting container process caused: error adding seccomp filter rule for syscall bdflush: permission denied: OCI permission denied
[root@localhost ~]

If you encounter errors related to Seccomp, there is a chance the error stems from a bug in your Docker Podman version. To bypass this error, the user can use the parameter --security-opt seccomp=unconfined with docker run command.

root@localhost:~# SHARED_DIRECTORY=/root/qualys/shared; PRIVATE_DIRECTORY=/root/qualys/private; PERSONALIZATION_CODE=xxx5xxx1xxx0xx; NAME=Qualys_Container; mkdir -p $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE; docker run -d -v $SHARED_DIRECTORY:/usr/local/qualys:z -v $PRIVATE_DIRECTORY/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e DISREGARD_PID_LIMIT=yes --security-opt seccomp=unconfined -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com abecffadebed 62e281d9c1b463e2da82c85f09fcc0df57611bc1f7fd41b6b404179d844ade01 root@localhost:~#

Qualys Platform Server Connection Errors

Could Not Resolve Host

Check the following errors,

user.notice curl: * Could not resolve host: qualysxxx.xxx.xxx.xxx.qualys.com; Unknown error user.notice curl: * Closing connection 0 user.notice curl: user.notice curl: curl: (6) Could not resolve host: qualysxxx.xxx.xxx.xxx.qualys.com; Unknown

Users can face this error when Linux Host's DNS Nameservers can not resolve the Qualys Platform's SOC user is using the Containerized Scanner creation command. We recommend that the user check the DNS Nameservers on the Linux Host.

Connection Timed Out

Check the following errors,

user.notice curl: * About to connect() to qualysxxx.xxx.xxx.xxx.qualys.com port 443 (#0)
user.notice curl: *   Trying qualysxxx.xxx.xxx.xxx.qualys.com...
user.notice curl: * Connection timed out
user.notice curl: * Failed connect to qualysxxx.xxx.xxx.xxx.qualys.com:443; Connection timed out
user.notice curl: * Closing connection 0
user.notice curl:
user.notice curl: curl: (7) Failed connect to qualysxxx.xxx.xxx.xxx.qualys.com:443; Connection timed out

You may face this error when Linux Host can not reach or connect to the Qualys Enterprise TruRisk™ Platform's SOC the user is using in the Containerized Scanner creation command. This can happen if a network firewall is blocking the connection from Linux Host to Qualys Platform's SOC. We recommend that the user Qualys Enterprise TruRisk™ Platform's SOC.. We recommend the user to check the network traffic rules.

Containerized Scanner Activation Errors

Generic Error

Check the following errors,

Most likely your perscode has already been used. This generic error message is intentional to prevent abuse and bruteforcing.

Users can face this error in the following cases.

  • If the Personalization or Activation code used in the docker run command is wrong.
  • If the Personalization/Activation code is from the Virtual Scanner workflow and is used in the Containerized Scanner,
  • If QUALYS URL used in option '-e QUALYS_URL' is wrong.
  • At startup, the QCSA containerized scanner checks for its private directory contents. An empty dir or missing perscode, token, scanner_ID files triggers fresh personalization. Empty private dir or missing files is possible in two cases, either this is new container or the remounting of the private dir failed at container restart/rerun. New log messages have been added to indicate when the personalization process starts, with the personalization code and the contents of the private directory mounted inside the container at /usr/local/qualys/admin/etc/. 
    2025-06-09T08:55:24+43411542 bbd916e0405d user.notice init: No saved perscode in /usr/local/qualys/admin/etc directory, going to start personalization process with 70698763039178 code
2025-06-09T08:55:24+43411542 bbd916e0405d user.notice init: Content of /usr/local/qualys/admin/etc:
2025-06-09T08:55:24+43411542 bbd916e0405d user.notice init: total 12
2025-06-09T08:55:24+43411542 bbd916e0405d user.notice init: drwx--x--- 2 www www 4096 Jun  9 08:31 .
2025-06-09T08:55:24+43411542 bbd916e0405d user.notice init: drwx--x--- 8 www www 4096 Jun  9 05:16 ..
2025-06-09T08:55:24+43411542 bbd916e0405d user.notice init: -rw------- 1 www www  111 Jun  6 13:29 .rpmmacros

    Missing api_token

    2025-06-09T09:09:35 f58e88272d05 user.notice init: Personalization code: 70698763039178
2025-06-09T09:09:35 f58e88272d05 user.notice init: Required /usr/local/qualys/admin/etc/api_token file is missing
2025-06-09T09:09:35 f58e88272d05 user.notice init: Content of /usr/local/qualys/admin/etc:
2025-06-09T09:09:35 f58e88272d05 user.notice init: total 24
2025-06-09T09:09:35 f58e88272d05 user.notice init: drwx--x--- 2 www www 4096 Jun  9 08:58 .
2025-06-09T09:09:35 f58e88272d05 user.notice init: drwx--x--- 8 www www 4096 Jun  9 05:16 ..
2025-06-09T09:09:35 f58e88272d05 user.notice init: -rw------- 1 www www  111 Jun  6 13:29 .rpmmacros
2025-06-09T09:09:35 f58e88272d05 user.notice init: -rw-r--r-- 1 www www   45 Jun  9 08:58 api_url
2025-06-09T09:09:35 f58e88272d05 user.notice init: -rw-r--r-- 1 www www   15 Jun  9 05:16 perscode
2025-06-09T09:09:35 f58e88272d05 user.notice init: -rw------- 1 www www 3243 Jun  9 08:55 pkey.pem

    Missing scanner_id

    2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: Personalization code: 70698763039178
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: Qualys POD URL: https://qualysguard.p06.eng.sjc01.qualys.com
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: Required /usr/local/qualys/admin/etc/scanner_id file is missing
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: Content of /usr/local/qualys/admin/etc:
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: total 28
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: drwx--x--- 2 www www 4096 Jun  9 09:11 .
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: drwx--x--- 8 www www 4096 Jun  9 05:16 ..
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: -rw------- 1 www www  111 Jun  6 13:29 .rpmmacros
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: -rw-r--r-- 1 www www   35 Jun  9 05:16 api_token
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: -rw-r--r-- 1 www www   45 Jun  9 08:58 api_url
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: -rw-r--r-- 1 www www   15 Jun  9 05:16 perscode
2025-06-09T09:11:23+21915553 325268cf6059 user.notice init: -rw------- 1 www www 3243 Jun  9 08:55 pkey.pem

    In the above examples, /usr/qualys/private/ Docker Host's Private Space for QCSA and directories named after the personalization code are Containerized Scanner's private directories.

Containerized Scanner Name Conflict

Check the following errors.

docker: Error response from daemon: Conflict. The container name "Qualys_Container" is already in use by container "5b1216507d1483b4b3618091c937694d532fbebb200884a646fd3e9544b7765d". 
You have to remove (or rename) that container to be able to reuse that name. See 'docker run --help'.

You may face this error when another Containerized Scanner with the same name is already running or in an exited state on Linux Host. Use the docker container ls -a command to list all containers on Linux Host.

Containerized Scanner Personalization or Activation Code Conflict

Check the following errors.

Error: another instance of PERSONALIZATION_CODE=xx6xxx7xx5xxx1 is running
user.notice init: To see the embedded manual, run the container with the 'help' parameter

You may face this error when another Containerize Scanner is already running with the same Personalization or Activation Code. 

Personalization or Activation Code for Deleted Containerized Scanner Appliance in User Portal

Check the following errors,

user.error iscan_bind: Error: [This scanner_id does not exist]

Users can face this error when the Personalization or Activation code for deleted Containerized Scanner Appliance is used while creating or re-creating Containerized Scanner.

Personalization or Activation Code for Disabled Containerized Scanner Appliance

Check the following errors,

 user.error iscan_bind: Error: [This Scanner is disabled]

Users can face this error when Personalization or Activation code for disabled Containerized Scanner Appliance is used while creating or re-creating Containerized Scanner.

Containerized Scanner Starting Errors

Check following error.

/usr/bin/scand: cannot execute binary file

You may face this error when IA32 Emulation is disabled in the Kernel Configuration. For QCSA scanning to function, Linux Host's Linux kernel should support ELF 32-bit LSB executables.

Containerized Scanner Scanning Errors

Check the following error,

Katana process for jobid xxxxxx:x generated Error message "sudo: unable to send audit message: Operation not permitted

Possible linux host restrictions & resolutions:

  1. logs are needed to be written in Kernel Auditing Logs. Use --cap-add=CAP_AUDIT_WRITE option with docker run command to create Containerized Scanner.
  2. Docker container is by default unprivileged and does not have all capabilities as host. Refer Runtime privilege and Linux capabilities for more details. Use --privileged option with docker run command to create Containerized Scanner.

CAP_NET_RAW Capability Requirement

Missing CAP_NET_RAW - RAW and PACKET sockets capability. This capability is required for vulnerability scanning. Use --cap-add=net_raw option with the docker run command to create a Containerized Scanner.

root@localhost:~# PERSONALIZATION_CODE=70663003600012; NAME=Qualys_Container; mkdir 
-p /root/qualys/private/$PERSONALIZATION_CODE; podman run --cap-add=net_raw -d -v /root/qualys/common:/usr/local/qualys:z 
-v /root/qualys/private/$PERSONALIZATION_CODE:/usr/local/qualys/admin/etc:z -e PERSONALIZATION_CODE=$PERSONALIZATION_CODE
 --name "$NAME" -e ALLOW_32BIT=no -e QUALYS_URL=https://qualysguard.p06.eng.sjc01.qualys.com 77ad0fe1702e
9a9aa0c2a6c443157f2eb4e4edbaf55918b24bac2ea57eb7ca3b9cae1bc62a60
root@localhost:~#

Contact Qualys Support if your issue is not listed here or if you need more help.

 

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

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

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

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

© 2025 Qualys, Inc. All rights reserved. Privacy Policy.