Troubleshooting

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

Root Access

You need root access to Docker Host to create a containerized scanner. You can face the following errors when containerized scanner creation is attempted from a non-root user profile.

[jon_doe@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
-e PERSONALIZATION_CODE=$PERSONALIZATION_CODE --name "$NAME" -e QUALYS_URL=https://qualysxxx.xxx.xxx.xxx.qualys.com 6715167e4412
WARN[0000] The cgroupv2 manager is set to systemd, but there is no systemd user session available
WARN[0000] For using systemd, you may need to log in using a user session
WARN[0000] Alternatively, you can enable lingering with: `loginctl enable-linger 1000` (possibly as root)
WARN[0000] Falling back to --group-manager=cgroupfs
WARN[0000] The cgroupv2 manager is set to systemd but there is no systemd user session available
WARN[0000] For using systemd, you may need to log in using a user session
WARN[0000] Alternatively, you can enable lingering with: `loginctl enable-linger 1000` (possibly as root)
WARN[0000] Falling back to --group-manager=cgroupfs 07420bcaa7665364844299e678cced60a85d888ae0b95bc7cece19634579285c
WARN[0000] Failed to add pause process to systemd sandbox group: exec: "dbus-launch": executable file not found in $PATH
[jon_doe@localhost ~]$

It is recommended to use the root user to create a containerized scanner.

SELinux Blocking Bind Mount

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 docker host & if the :z suffix with bind mount is not used, the user might run into the following 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 -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 ~]#

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.

Podman Default PID Limit

The default PID limit (total number of processes and threads to run inside a container) for Podman is 2048. This limit may prevent the QCSA containerized scanner from running larger scans. Upon reaching this limit, the containerized scanner could also stop and go into an excited state.

Check the following errors,

Host logs:

Mar 24 09:11:50 saqaoel8 kernel: cgroup: fork rejected by pids controller in /machine.slice/libpod-24709174ed6695d641ac92356bb9a98750f4b7f8c6157e121b06546e6849a92c.scope

Containerized scanner logs:

2025-03-24T09:16:30+39490243 24709174ed66 daemon.info ScanD[1251]: Sending heartbeat message (capacity=2763&session_id=25299235&session_seq=205) to jobd/SJMS URL https://scanservice1.p01.eng.sjc01.qualys.com:443
2025-03-24T09:16:32+39490243 24709174ed66 daemon.info ScanD[1251]: Received response to heartbeat message from JobD/SJMS
/dev/shm/55a4afc1: fork: retry: Resource temporarily unavailable
/dev/shm/55a4afc1: fork: retry: Resource temporarily unavailable
/dev/shm/55a4afc1: fork: retry: Resource temporarily unavailable
/dev/shm/55a4afc1: fork: Interrupted system call
2025-03-24T09:16:44+39490243 24709174ed66 user.notice init: Processing SIGINT
2025-03-24T09:16:44+39490243 24709174ed66 user.notice init: Sending SIGQUIT to PID=1251
2025-03-24T09:16:44+39490243 24709174ed66 daemon.info ScanD[1251]: ScanD: Processing received SIGTERM signal
2025-03-24T09:16:44+39490243 24709174ed66 daemon.error ScanD[1251]: ScanD shutting down

Solution: To avoid this restriction when using Podman, we recommend running the QCSA containerized scanner with the '--pid-limit -1' option.

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 Docker 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 Docker 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 Docker 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 Docker 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 the Containerized Scanner's private directory is deleted. In such a case, check if the Containerized scanner's private directory is present or not. The containerized scanner's private directory is created and named after the Personalization or Activation code and stored in Docker Host's Private Space.
Use the following example.
```
[root@localhost ~]# ls /usr/qualys/private/
xx6xxx0xx1xxx7  xx6xxx0xx1xxx7
[root@localhost ~]#
```

In the above example,/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 Docker Host. Use the docker container ls -a command to list all containers on Docker 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, Docker 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 docker host restrictions & resolutions:

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

Example error

root@localhost:~# PERSONALIZATION_CODE=70663003600012; NAME=Qualys_Container; mkdir -p /root/qualys/private/$PERSONALIZATION_CODE; podman run -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
686b88e1ee6db100cd445f14eeb91e5500b4e7793561de54b8d77f93ade30573
root@localhost:~#
root@localhost:~# podman logs 686b88e1ee6db100cd445f14eeb91e5500b4e7793561de54b8d77f93ade30573
cap[cap_net_raw] not permitted
Missing CAP_NET_RAW - RAW and PACKET sockets capability, required for vulnerability scanning. Use --cap-add=net_raw option
Current: cap_chown,cap_dac_override,cap_fowner,cap_fsetid,cap_kill,cap_setgid,cap_setuid,cap_setpcap,cap_net_bind_service,cap_sys_chroot,cap_setfcap=ep
Bounding set =cap_chown,cap_dac_override,cap_fowner,cap_fsetid,cap_kill,cap_setgid,cap_setuid,cap_setpcap,cap_net_bind_service,cap_sys_chroot,cap_setfcap
Ambient set =
Current IAB: !cap_dac_read_search,!cap_linux_immutable,!cap_net_broadcast,!cap_net_admin,!cap_net_raw,!cap_ipc_lock,!cap_ipc_owner,
!cap_sys_module,!cap_sys_rawio,!cap_sys_ptrace,!cap_sys_pacct,!cap_sys_admin,!cap_sys_boot,!cap_sys_nice,!cap_sys_resource,!cap_sys_time,
!cap_sys_tty_config,!cap_mknod,!cap_lease,!cap_audit_write,!cap_audit_control,!cap_mac_override,
!cap_mac_admin,!cap_syslog,!cap_wake_alarm,!cap_block_suspend,!cap_audit_read,!cap_perfmon,!cap_bpf,!cap_checkpoint_restore
Securebits: 00/0x0/1'b0 (no-new-privs=0)
 secure-noroot: no (unlocked)
 secure-no-suid-fixup: no (unlocked)
 secure-keep-caps: no (unlocked)
 secure-no-ambient-raise: no (unlocked)
uid=0(root) euid=0(root)
gid=0(root)
groups=
Guessed mode: UNCERTAIN (0)
To see embedded manual, run container with 'help' parameter
root@localhost:~#

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.

Example error

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.

The sample commands utilize Docker Engine as the container runtime, but they can also be executed using Podman.
The default PID limit (total number of processes and threads to run inside a container) for Podman is 2048. If the Docker host already has active processes, this limit may prevent the QCSA containerized scanner from running larger scans. To avoid this restriction when using Podman, we recommend running the QCSA containerized scanner with the '--pid-limit -1' option.

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