.. SPDX-FileCopyrightText: 2026 Univention GmbH
..
.. SPDX-License-Identifier: AGPL-3.0-only

.. _conf-self-service-malware-scan:

Malware scan of uploaded files in *End User Self Service*
=========================================================

This section is for operators
who want the *End User Self Service* to scan uploaded files for malware,
such as profile pictures.

The *End User Self Service* sends each uploaded file
to an *ICAP* service over TCP,
for example :program:`c-icap` with :program:`ClamAV`.
The scan applies to the following actions:

* Users change their profile on the *Your profile* page.

* Users create an account on the *Create an account* page.

If the *ICAP* service finds malware,
the *End User Self Service* rejects the file
and doesn't save the changes.
The user sees the message
*Upload rejected: malware was detected in the file.*

If the *ICAP* service isn't available or can't scan the file,
the *End User Self Service* also rejects the file.
The user sees the message
*Upload failed: Malware scan not currently possible.
Please try again later or contact an administrator.*

In the default configuration of Nubus for Kubernetes,
the malware scan is inactive.

.. _conf-self-service-malware-scan-requirements:

Requirements
------------

You need an *ICAP* service that the *UMC Server* pod can reach over the network.
Nubus for Kubernetes doesn't include an *ICAP* service.

The URL must point to the malware scan service of the *ICAP* server.
If you configure the wrong ICAP service, or a scanner that skips some files,
uploads are accepted without a scan, and produce no error.

Some *ICAP* services only scan specific file types.
For :program:`c-icap`, make sure that the setting ``virus_scan.ScanFileTypes``
includes the file types that users can upload,
for example ``JPEG`` and ``PNG`` for profile pictures.

.. _conf-self-service-malware-scan-configure:

Configure the malware scan
--------------------------

To activate the malware scan,
use the following steps:

#. Add the lines in :numref:`conf-self-service-malware-scan-listing`
   to your :file:`custom_values.yaml` values file.
   Replace the URL with the URL of your *ICAP* service.

   .. dropdown:: Malware scan settings
      :open:

      ``url``
         Defines the URL of the *ICAP* service,
         for example ``icap://clamav:1344/avscan``.
         Use the scheme ``icaps://`` for a connection with TLS.
         If the URL doesn't include a port,
         the *End User Self Service* uses the port ``1344``.

         If the value is empty,
         the *End User Self Service* doesn't scan uploaded files.

         The value supports Helm templates.

         Default value: empty

      ``timeout``
         Defines the time in seconds
         that the *End User Self Service* waits for the *ICAP* service
         to scan all uploaded files of one request.

         Default value: ``30``

      ``maxFiles``
         Defines the maximum number of files that a user can upload in one request
         when the malware scan is active.
         All upload attributes of the request count together.
         The *End User Self Service* rejects a request with more files
         before it scans or saves any file.
         The value ``0`` allows no files.

         Default value: ``10``

   .. code-block:: yaml
      :caption: Activate the malware scan in *End User Self Service*
      :name: conf-self-service-malware-scan-listing

      nubusUmcServer:
        selfService:
          malwareScan:
            maxFiles: 10
            icap:
              url: "icap://clamav:1344/avscan"
              timeout: 30

#. Optional: If the *ICAP* service uses TLS with a certificate
   from your own certificate authority,
   add the CA certificate as described in
   :ref:`conf-self-service-malware-scan-tls`.

#. To activate the changes,
   you need to apply the configuration as described in
   :ref:`nubus-configuration-apply`.
   Kubernetes automatically restarts the *UMC Server* pod
   with the updated configuration.

.. _conf-self-service-malware-scan-tls:

Use TLS with your own certificate authority
-------------------------------------------

With the scheme ``icaps://``,
the *End User Self Service* always verifies the certificate of the *ICAP* service.
By default, it uses the CA certificates of the *UMC Server* container.
If a certificate authority that the container doesn't know
signed the certificate of the *ICAP* service,
provide its CA certificate in one of the following ways:

* Add the CA certificate in PEM format to your :file:`custom_values.yaml` values file,
  as in :numref:`conf-self-service-malware-scan-tls-listing`.
  The Helm chart stores the certificate in a Kubernetes *Secret*.

* Use an existing Kubernetes *Secret* with the key :file:`ca.crt`,
  as in :numref:`conf-self-service-malware-scan-tls-secret-listing`.
  If the *Secret* uses another key,
  set the key with ``keyMapping``.

.. code-block:: yaml
   :caption: CA certificate for the *ICAP* service in the values file
   :name: conf-self-service-malware-scan-tls-listing

   nubusUmcServer:
     selfService:
       malwareScan:
         icap:
           url: "icaps://clamav:11344/avscan"
           tls:
             caCert: |
               -----BEGIN CERTIFICATE-----
               ...
               -----END CERTIFICATE-----

.. code-block:: yaml
   :caption: CA certificate for the *ICAP* service from an existing *Secret*
   :name: conf-self-service-malware-scan-tls-secret-listing

   nubusUmcServer:
     selfService:
       malwareScan:
         icap:
           url: "icaps://clamav:11344/avscan"
           tls:
             existingSecret:
               name: "icap-ca"
               keyMapping:
                 ca.crt: "ca.pem"

To activate the changes,
apply the configuration as described in
:ref:`nubus-configuration-apply`.

.. seealso::

   :ref:`conf-self-service`
      for information about how to restrict users or groups
      from capabilities in *End User Self Service*.

   :external+uv-nubus-kubernetes-architecture:ref:`component-end-user-self-service`
      in :cite:t:`uv-nubus-kubernetes-architecture`
      for an architectural overview of the *End User Self Service*.