.. Reminder for header structure:
  Parts (H1)          : #################### with overline
  Chapters (H2)       : ******************** with overline
  Sections (H3)       : ====================
  Subsections (H4)    : --------------------
  Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^
  Paragraphs (H6)     : """"""""""""""""""""

.. meta::
  :description: Using the WAPT Console advanced features
  :keywords: WAPT, advanced, features, documentation.

.. |ok| image:: wapt-resources/icon-ok.png
  :scale: 5%
  :alt: Feature available

.. |nok| image:: wapt-resources/icon-nok.png
  :scale: 5%
  :alt: Feature not available

.. _wapt_wua:

##############################################################
Using WAPT Windows Update Agent (WAPTWUA) |enterprise_feature|
##############################################################

.. hint::

  **WAPT is able to manage Windows Updates on your endpoints and replace automatic Windows Updates or a WSUS Server.**

  **Responsibilities in the Upgrade Process**

    **Tranquil IT (WAPT) is responsible for:**

        * Downloading upgrade files (ISO, scripts) to the endpoint
        * Invoking either the compatibility scan or the upgrade via Microsoft's setup.exe
        * Reporting to the WAPT console
        * Cleaning up upgrade files after the process

    **Microsoft remains responsible for:**

        * Performing the actual compatibility scan
        * Executing the actual upgrade (including tagging critical machines and selecting target devices)
        * Managing reboots during the upgrade process
        * Reporting success or failure of the upgrade

.. attention::

  WAPTWUA can not operate concurrently with the Microsoft Store.

.. versionadded:: 2.6.0.16881

  **breaking change:** Removed the ability to install Windows updates at shutdown in waptexit because it **is not supported anymore in Windows 11 24h2**. In waptsetup, the checkbox is replaced by a install scheduling combobox (if empty, no automatic install).

.. note::

  WAPTWUA works with the :abbr:`WUA (Windows Update Agent)` Windows API.

  For more information: https://docs.microsoft.com/en-us/windows/win32/wua_sdk/using-the-windows-update-agent-api.

*****************
Working principle
*****************

Video demonstration:

.. youtube:: x36gAaT31Ko
   :align: center
   :width: 50%

Each :abbr:`Patch Tuesday (Patch Tuesday is an unofficial term used to refer the second Tuesday of each month when Microsoft releases software patches for their software products.)` , the WAPT Server downloads an updated :file:`wsusscn2.cab` file from official Microsoft servers.

By default, downloads are scheduled once a day and no download is triggered if the :file:`wsusscn2.cab` file has not changed since the last download.

.. hint::

  In order to make WAPTWUA work, The WAPT Server must have access to:

  * windowsupdate.microsoft.com
  * ..windowsupdate.microsoft.com
  * ..update.microsoft.com
  * windowsupdate.com
  * download.windowsupdate.com
  * download.microsoft.com
  * download.windowsupdate.com
  * wustat.windows.com
  * ntservicepack.microsoft.com
  * go.microsoft.com
  * dl.delivery.mp.microsoft.com

  Even though you may choose other sources for Windows updates, ports 443 and 80 need to accept incoming trafic on the WAPT Server.

.. figure:: wapt-resources/wapt_wua_windows-update_flow-diagram.png
  :align: center
  :scale: 75 %
  :alt: Flow diagram of the WAPT Windows Updates

  Flow diagram of the WAPT Windows Updates

The :file:`wsusscn2.cab` file is then downloaded by the WAPT Agent from the WAPT Server repository and then passed on to :abbr:`WUA (Windows Update Agent)` Windows utility to crunch the update tree for the host.

Regularly, the host will analyze the available updates using the :file:`wsusscn2.cab` file and send its list of needed updates to the WAPT Server.

If an update is pending on the host and if that update is not present on the WAPT Server, the WAPT Server will download the needed update from official Microsoft servers.

.. hint::

  This mode of operation allows WAPT to download only the necessary updates on the computers, thus saving bandwidth, download time and disk space.

.. note::

  On the WAPT Server, downloaded updates are stored:

  * on Linux hosts in :file:`/var/www/waptwua`;

  * on Windows hosts in :file:`C:\\wapt\\waptserver\\repository\\waptwua`.

The WAPT Windows Update Agent repository download URL is based on the :code:`repo_url` parameter in :file:`wapt-get.ini`:

.. note::

  * If repository replication is used, it will synchronize WAPT Windows Update out of the box.
    For this, the :file:`waptwua` folder needs to be included in the folder to synchronize.

  If a proxy is required to access Internet, then be sure to :ref:`set the proxy server in the waptserver.ini file <waptserver_ini_file_options>`.

*************************************************
Differences between WAPT Windows Updates and WSUS
*************************************************

WSUS downloads by default the updates for selected categories.
This can lead to a very large update database and lots of storage.

WAPT Windows Update only downloads updates that have been requested by at least one client computer.
This helps to keep the local database small (a few 10s of Gigabytes) and it can be easily cleaned up if you want to recover space.

WAPT Windows Update does not support HyperV `Cluster Aware Updating <https://learn.microsoft.com/en-us/windows-server/failover-clustering/cluster-aware-updating>`_.  
It supports standard HyperV non-CUA update methods though.

*********************************************
Security Differences Between WAPTWUA and WSUS
*********************************************

WAPT using Windows Update Agent (WUA) differs significantly from WSUS (Windows Server Update Services) in terms of security, particularly against known attack vectors like **WSUSpect** or **WSUSpendu** 
(check `this <https://www.sstic.org/2017/presentation/wsus_pendu/>`_ for more information).
These attacks exploit vulnerabilities in WSUS, such as default unencrypted HTTP communication and the ability to manipulate update packages during transmission, enabling attackers to deploy malicious updates.

Wapt supplies the wsus2.cab file to the Windows agents, enabling them to analyse the missing KBs. This list is transmitted to the WAPT server, which downloads only the KBs required for your machine park and makes them available to the machines.

Because WAPT WUA relies on direct downloads and signature verification, the attacks targeting WSUS are not applicable.
There is no intermediary server hosting updates that could be compromised, and no opportunity for attackers to inject malicious updates into the update process.

By design, WAPT WUA leverages Microsoft's secure update infrastructure, significantly reducing the attack surface compared to traditional WSUS configurations.
However, it remains essential to secure the broader WAPT ecosystem to protect against other potential vulnerabilities.


*****************
Major OS upgrades
*****************

Major OS upgrades are upgrades from one OS version to another.
That includes, for example, upgrades from Windows 10 to Windows 11, or from Windows 11 22h2 to Windows 11 23H2.

Major version upgrades are not handled in the same way as minor OS upgrades.
Major upgrades are handled via the downloading of the new install ISO content (same content as for a fresh install) and running the :command:`setup.exe` with the correct parameters.
This process is the same for WSUS, SCCM and WAPT Windows Updates.

In the case of WAPT Windows Updates, you need to create a OS update package using a template package provided on https://store.wapt.fr.

***************
Driver upgrades
***************

Driver upgrades via WSUS are not recommended since it is hard to properly handle side effects.
In the case of WAPT Windows Updates, **DRIVERS ARE NOT DOWNLOADED** since they are not referenced in the :file:`wsusscn2.cab` files provided by Microsoft.

It is recommended to push driver updates via a custom WAPT package.
If the driver patch is packaged as a :mimetype:`.msu`, you may package it as a standard WAPT package.

Just select the :mimetype:`.msu` file and click :menuselection:`Make package template from setup file --> Package template --> Windows Update packages (.msu)` in the WAPT Console to launch the wizard for simplified package creation.

If the driver update is packaged as a :mimetype:`.zip` containing the :mimetype:`.exe` file, you can create a WAPT package containing the necessary files and :program:`setup.exe` binary with the correct silent flag.

**************
Out of band KB
**************

Microsoft sometimes provides :abbr:`OOB (Out of Band)` updates that are not contained in the :file:`wsusscn2.cab` index.
Those updates are not included in the main update because they may fix a very specific problem or may have drawbacks in some situations.

If you want to deploy an OOB KB update, you can download it from the `Microsoft catalog <https://www.catalog.update.microsoft.com/Home.aspx>`_.

Just select the :file:`.msu` file and click :menuselection:`create package` in the WAPT Console to launch the wizard to create a simple package.

To do so, follow :ref:`this documentation <simple_msu_packaging>` on packaging :file:`.msu` files for these *Out-of-band* updates.

.. attention::

  You have to be careful that :abbr:`OOB (Out of Band)` updates may break your system, be sure to read the prerequisites on the Microsoft bulletin corresponding to the update and thoroughly test the update.

.. _wapt_wua_agent:

*************************************
Configuring WAPTWUA on the WAPT Agent
*************************************

*WAPTWUA* is configured in :file:`wapt-get.ini` in ``[waptwua]`` section.

You then have several options:

.. list-table:: Configuration options in the ``[waptwua]`` section in the :file:`wapt-get.ini`
  :header-rows: 1
  :widths: auto
  :align: center

  * - Options (Default Value)
    - Description
    - Example
  * - :code:`enabled` (default ``False``)
    - Enables or disables WAPTWUA on this host.
    - enabled = True
  * - :code:`direct_download` (default ``False``)
    - Defines whether updates are downloaded directly from Microsoft servers.
    - direct_download = True
  * - :code:`default_allow` (default ``False``)
    - Defines whether missing update are authorized by default.
    - default_allow = True
  * - :code:`download_scheduling` (default ``None``)
    - Defines the Windows Update download of KB recurrence (download_scheduling performs a scan and the download) (Will not do anything if *waptwua* package rule or :file:`wsusscn2.cab` file have not changed).For example 1d means that every 24 hours, if an update is pending, the computer will download it.
    - download_scheduling = 1d
  * - :code:`install_scheduling` (default ``None``)
    - Defines the Windows Update install recurrence (install_sheduling performs a scan, download and install). For example 2h means that every 2 hours, if an update is pending, the computer will install it.
    - install_scheduling = 2h
  * - :code:`install_delay` (default ``None``)
    - Defines a deferred installation delay after publication in the Microsoft repository. The reference date of the KB is that of the :file:`wsusscn2.cab` file.
    - install_delay = 15d
  * - :code:`allowed_severities` (default ``None``)
    - Defines a severity list that will be automatically accepted during a WAPT windows update scan. ex: *Important*, *Critical*, *Moderate*.
    - allowed_severities = Important
  * - :code:`waptexit_disable_skip_windows_updates` (default ``False``)
    - Defines whether the :guilabel:`skip Microsoft Windows Update` checkbox in the WaptExit window is available (``False``) or not (``True``).
    - waptexit_disable_skip_windows_updates = True
  * - :code:`include_potentially_superseded_updates` (default ``False``)
    - Defines whether the Windows Update agent will show both the latest KB and the superseeded ones (True), or only the lastest KB (False).
    - include_potentially_superseded_updates = False

.. hint::

  These options can be set when generating the WAPT Agent.

Example ``[waptwua]`` section in :file:`wapt-get.ini` file:

.. code-block:: ini

  [waptwua]
  enabled = True
  default_allow = False
  direct_download = False
  download_scheduling = 7d
  install_at_shutdown = True
  install_scheduling = 12h
  install_delay = 3d

When creating the :file:`waptagent.exe` from the WAPT Console, these options are equivalent to this:

.. figure:: wapt-resources/wapt_console_wua-agent-options_dialog-box.png
  :align: center
  :alt: Menu options for the WAPT Windows Update Agent

  Menu options for the WAPT Windows Update Agent

Example source code to modify ``[waptwua]`` settings with a WAPT package:

.. code-block:: python

  def install():

    inifile_writestring(WAPT.config_filename,'waptwua','enabled','true')
    inifile_writestring(WAPT.config_filename,'waptwua','install_at_shutdown','true')
    inifile_writestring(WAPT.config_filename,'waptwua','download_scheduling','7d')
    inifile_writestring(WAPT.config_filename,'waptwua','allowed_severities','Critical,Important')

    print('Reload WAPT configuration')
    WAPT.reload_config_if_updated()

***********************************
Using WAPTWUA from the WAPT Console
***********************************

* WUA Rules in :guilabel:`WAPT Packages` tab:

  .. figure:: wapt-resources/wapt_console_wua_container-window.png
    :align: center
    :scale: 60%
    :alt: Creating a waptwua package in the WAPT Console
    
    Creating a waptwua package in the WAPT Console

  * When a *waptwua* package is installed on a host, it indicates to the WAPTWUA Agent what are the authorized or forbidden :abbr:`KBs (Knowledge Base articles)`.

  * When several *waptwua* packages are installed on a host, the different rules will be merged.

  * When a :file:`cab` is neither mentioned as authorized, nor mentioned as prohibited, WAPT Agents will then take the value of :code:`default_allow` in :file:`wapt-get.ini`.

  .. note::

    * If the WAPTWUA Agent configuration is set to :code:`default_allow` = ``True``, then it will be necessary to specify the forbidden :file:`cab`.

    * If the WAPTWUA Agent configuration is set to :code:`default_allow` = ``False``, then it will be necessary to specify the authorized :file:`cab`.

  .. hint::

    * To test updates on a small set of computers, you can set WAPTWUA package default maturity to ``PREPROD``.

    * You can then test the Windows Updates on a small sample of ``PREPROD`` hosts and if everything is good, you can release the updates to the entire fleet of computers.

* Windows Updates tab:

  .. figure:: wapt-resources/wapt_console_wua-update-list_container-window.png
    :align: center
    :scale: 60%
    :alt: Windows Updates tab in the WAPT Console

    Windows Updates tab in the WAPT Console

  The :guilabel:`Windows Update` tab lists all needed Windows Updates.

  .. important::

    The WAPT Server does not scan the :file:`wsussc2.cab` itself, it lets the Windows Update Agent utility present on all Windows hosts do it.
    If an update seems to be missing from the list, you **MUST** run a scan on one of the hosts present in the WAPT Console.
    If you run a WAPT WUA scan on a Windows 10 client, the CAB and Windows 10 files will be displayed on the :guilabel:`Windows Update` tab.

  The left pane displays update categories, allowing you to filter by:

  * criticality;

  * product;

  * classification.

  In the right panel grid, if the :guilabel:`Downloaded on` column is empty, it means that the update has not yet been downloaded by the WAPT Server and is not present on the WAPT Server (This update is not missing on any host).

  * To force download an update, do :menuselection:`Right-click --> Download`.

  * To force download the :file:`wsusscn2.cab` file, click on the :guilabel:`Download WSUSScan cab from Microsoft Web Site` button.

  * To see the Windows Updates downloaded on the WAPT Server, click on the :guilabel:`Show download task` button.


  .. hint::

    Every 30 minutes, the WAPT Server will look for updates that have been requested at least once by WAPT Clients and that have not yet been downloaded and cached.
    If a Windows update has been requested by a WAPT Client and the requested Windows Update is not cached, the WAPT Server will download it from official Microsoft servers.

    You can force this scan with the :guilabel:`Download index and missing cabs from Microsoft Web site` button in the tab :menuselection:`Windows Updates --> Windows Updates list`

Cleaning old Windows updates
============================

.. _auto_kb_clean:

You can run the cleanup either manually or automatically.

.. tabs::

  .. tab:: Automatically

    If the KB is not installed on the host, it is automatically deleted on the WAPT Server between 2:30 am and 3:30 am every day.
    It is possible to disable the automatic deletion of KB with the :code:`cleanup_kbs` option in the :file:`waptserver.ini` configuration file of the WAPT Server.

    Add this setting on :ref:`the WAPT Server configuration file <waptserver_ini_file_options>`: 

    .. code-block:: ini

      cleanup_kbs = False

  .. tab:: From the WAPT Console

    To cleanup the :file:`waptwua` folder, go to the :guilabel:`Windows update` tab and click on the :guilabel:`Delete Unused KB` button.
    Pressing the button will delete all unused KB stored on the WAPT Server.

    .. image:: wapt-resources/wapt_console_wua-delete-unused-kb.png
        :align: center
        :alt: Button to delete unused KB in the WAPT Console

  .. tab:: From the WAPT Server

    It is possible to delete manually from the WAPT Server any Windows Update file that is no longer required.

    The WAPT Server will only re-download deleted updates if any of the WAPT Agents requests it.

    On the WAPT Server, downloaded updates are stored:

    * On Linux hosts in :file:`/var/www/waptwua`.

    * On Windows hosts in :file:`C:\\wapt\\waptserver\\repository\\waptwua`.

.. _wua_on_client:

Launching WUA on clients
========================

From the WAPT Console you have three options.

.. figure:: wapt-resources/wapt_console_wua_menu-items.png
  :align: center
  :alt: Windows Update action buttons available in the WAPT Console

  Windows Update action buttons available in the WAPT Console

* The :guilabel:`Trigger the scan of pending Windows Updates` button will launch the scan on the client and list all updates flagged for the OS.

* The :guilabel:`Trigger the download of pending Windows Updates` button will launch the downloading of pending updates on the client.

* The :guilabel:`Trigger the install of pending Windows Updates` button will launch the install of downloaded updates on the client.

.. hint::

  When pending updates stored in cache need to be installed, the WAPT Agent triggers the :abbr:`WUA (Windows Update Agent)` service.

  The WAPT Agent will then enable and start the WUA Service temporarily to install the updates.
  When updates are installed, the WAPT service will stop and disable the WUA service until the next cycle.

State of Windows Update on the host
===================================

Windows updates can have 4 states on a host.

.. list-table::
  :header-rows: 1
  :widths: auto
  :align: center

  * - Status
    - Description
  * - :guilabel:`OK`
    - A Windows update has installed correctly.
  * - :guilabel:`MISSING`
    - A Windows update has not yet been downloaded to the WAPT Server.
  * - :guilabel:`PENDING`
    - The WAPT Server knows it has to download an update from official Microsoft servers.
  * - :guilabel:`DISCARDED`
    - A Windows update was forbidden by rules.

.. figure:: wapt-resources/wapt_console_wua-pending_screen-item.png
  :align: center
  :alt: Pending Windows Updates showing in the WAPT Console

  Pending Windows Updates showing in the WAPT Console

Notion of UpdateID
==================

In WAPT we do not use *kbids* but instead we use **updateids**.

This allows finer grade management of updates.

.. figure:: wapt-resources/wapt_console_wua-kbs-doublon_screen-item.png
  :align: center
  :alt: List showing duplicate KB in the WAPT Console

  List showing duplicate KB in the WAPT Console

In this example, KB4537759 appears multiple times because there are 3 different *updateids*:

* win10 1803;

* win10 1903;

* win10 1909;

You should therefore authorize *updateids* and not *KB ids*.

*********************************************************
WAPT does not force Windows to uninstall a Windows Update
*********************************************************

.. attention::

  **Uninstalling a Windows update can be dangerous for the host**.

  When an update is detected as forbidden by WAPT, its removal will **NOT** be forced.

.. hint::

  If you use the "Windows updates" tab, you can see the uninstallable colomn. This permit to verify if the kb is uninstallable or not.

  .. figure:: wapt-resources/wapt_kb_uninstalable_status.png
    :align: center
    :alt: wapt kb uninstalable status

    wapt kb uninstalable status

If you really want to uninstall an update, you should package the KB that you want to uninstall as a standard WAPT package.

Here is an example:

.. code-block:: python

  from setuphelpers import *
  from setuphelpers import get_kb_dism_name

  kbs = ['kb5012170']
  def install():
    dism_data = get_kb_dism_name()
    with EnsureWUAUServRunning():
        for kb in kbs:
        if kb.lower() in dism_data:
            run('"%s" /Online /Remove-Package /PackageName:%s /Quiet /NoRestart' % (makepath(system32(), 'Dism.exe'), dism_data[kb.lower()]), timeout=900)
            print('reboot needed')
        else:
            print('kb %s not found' % kb)
  
Then you need to **restart the machine** and **run a windows update scan** through WAPT to see the kb as uninstalled on the machine.

****************************
WUA offline from the Console
****************************

Due to specific constraints, your WAPT server is not directly accessible from the Internet, but you still want to take advantage of Windows Update (WUA) for your agents. 
We have a solution adapted to this situation.

The process consists of using a WAPT agent machine to download the missing KBs using a file containing curl links to :file:`wsusscn2.cab` and :guilabel:`PENDING` updates on workstations that are not present on the WAPT server. The agent will then download the necessary files (such as .cab, .msu files, etc.). 
These files can then be imported directly onto the WAPT server. Once the files are available on the server, they will automatically be offered to other agents who need these updates.

.. figure:: wapt-resources/WUA-Pending_updates.png
  :align: center
  :alt: Action buttons for Pending updates

  Action buttons for Pending updates

* The :guilabel:`Show pending updates` button ; Allows you to view direct links, the file names of pending KBs and their associated hashes (sha1). At the bottom are the :guilabel:`Import WUA CAB file` and :guilabel:`Export as curl` buttons.

* The :guilabel:`Import WUA CAB file` button ; Opening a Windows Explorer on your workstation, to upload update files directly to the WAPT server.

* The :guilabel:`Export as curl` button ; A file is generated containing the curl links for the missing Windows updates. You can then run a command to initiate the download of the specified KB updates into a desired directory.

Operating Procedure
===================

.. note::

  **You will have to repeat the procedure each month when Microsoft releases its patches.**

1. On a machine with internet access:

.. code:: bash 

  curl -O http://download.windowsupdate.com/microsoftupdate/v6/wsusscan/wsusscn2.cab

2. On a WAPT Console connected to the isolated WAPT Server, go to  :guilabel:`Windows Update` tab, then click :guilabel:`Pending Updates`, :guilabel:`Import WUA CAB file` and import the cab file downloaded previously.

3. Right click on machines, :guilabel:`Trigger the scan of missing Windows Updates`.

4. Missing updates will then appear in the :guilabel:`Windows Update` tab, click on :guilabel:`Pending Updates`, :guilabel:`Export as curl`.

5. On a machine with internet access, download updates with the commands listed in the export file.

6. On a WAPT Console connected to the isolated WAPT Server, go to  :guilabel:`Windows Update` tab, then click :guilabel:`Pending Updates`, :guilabel:`Import WUA CAB file` and import the cab files downloaded previously.

7. Updates are now available for the WAPT agents.




