Merge pull request #8014 from wazuh/enhancement/7991-vulnerability-de…

…tector-add-troubleshooting-steps

Create a troubleshooting guide for vulnerability detector module

source/_static/js/redirects.js

@@ -64,6 +64,17 @@ removedUrls['x.y'] = [
 ];
 */
 
+/* *** RELEASE 4.10 ****/
+
+/* Pages added in 4.10 */
+newUrls['4.10'] = [
+  '/release-notes/release-4-10-0.html',
+  '/user-manual/reference/ossec-conf/anti-tampering.html',
+  '/user-manual/capabilities/vulnerability-detection/troubleshooting.html',
+  '/user-manual/capabilities/vulnerability-detection/FAQ.html',
+  '/user-manual/capabilities/vulnerability-detection/known-issues.html',
+]
+
 /* *** RELEASE 4.9 ****/
 
 /* Redirections from 4.8 to 4.9  */
@@ -296,12 +307,6 @@ redirections.push(
   },
 );
 
-/* Pages added in 4.10 */
-newUrls['4.10'] = [
-  '/release-notes/release-4-10-0.html',
-  '/user-manual/reference/ossec-conf/anti-tampering.html'
-]
-
 /* Pages added in 4.9 */
 
 newUrls['4.9'] = [

source/user-manual/capabilities/vulnerability-detection/FAQ.rst

@@ -0,0 +1,102 @@
+.. Copyright (C) 2015, Wazuh, Inc.
+
+.. meta::
+   :description: Learn how to solve common issues with the Vulnerability Detection module in this section of the documentation.
+
+Frequently Asked Questions (FAQs)
+=================================
+
+This section provides solutions to common issues encountered during the configuration, installation, and operation of the Vulnerability Detection module.
+
+Communication issues between the Wazuh server and the Wazuh indexer
+-------------------------------------------------------------------
+
+.. list-table:: Issue description
+   :widths: 15 50
+
+   *  -  Problem
+      -  No vulnerabilities reported in the Wazuh dashboard, or the ``wazuh-states-vulnerabilities-*`` index has not been created. The manager logs might show messages like ``IndexerConnector initialization failed for index 'X', retrying until the connection is successful``.
+   *  -  Cause
+      -  A misconfiguration in one of the following components:
+
+         -  Vulnerability detector
+         -  Indexer connector
+         -  wazuh-keystore
+
+Troubleshooting steps
+^^^^^^^^^^^^^^^^^^^^^
+
+Step 1: Check credentials and configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Ensure the wazuh-keystore is updated with correct admin username and password. For details, see the :doc:`wazuh-keystore </user-manual/reference/tools/wazuh-keystore>` documentation.
+#. Verify the :doc:`indexer connector configuration </user-manual/reference/ossec-conf/indexer>` at ``/var/ossec/etc/ossec.conf``. Ensure:
+
+   -  The ``<host>`` section contains the correct Wazuh indexer URL. The host FQDN/IP address must match the certificate details.
+   -  The ``<ssl>`` section specifies the correct paths for the certificate, key, and CA files.
+
+**Example configuration**:
+
+.. code-block:: xml
+   :emphasize-lines: 4,8,10,11
+
+   <indexer>
+     <enabled>yes</enabled>
+     <hosts>
+       <host>https://0.0.0.0:9200</host>
+     </hosts>
+     <ssl>
+       <certificate_authorities>
+         <ca>/etc/filebeat/certs/root-ca.pem</ca>
+       </certificate_authorities>
+       <certificate>/etc/filebeat/certs/filebeat.pem</certificate>
+       <key>/etc/filebeat/certs/filebeat-key.pem</key>
+     </ssl>
+   </indexer>
+
+Step 2: Verify the connection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can verify the connection to the Wazuh indexer using the ``curl`` command from the Wazuh server.
+
+.. code-block:: console
+
+   # curl --cacert <ROOT_CA> --cert <CERTIFICATE_PEM> --key <CERTIFICATE_KEY> -u <USER>:<PASS> -XGET https://<INDEXER_IP_ADDRESS>:9200/_cluster/health
+
+Where:
+
+-  ``<ROOT_CA>``, ``<CERTIFICATE_PEM>``, ``<CERTIFICATE_KEY>``: Certificate paths.
+-  ``<USER>`` and ``<PASS>``: Admin credentials.
+-  ``<INDEXER_IP_ADDRESS>``: IP address of the Wazuh indexer.
+
+If this command fails, the vulnerability detector module won't be able to connect to the indexer.
+
+To check if the issue is related to certificates, bypass certificate verification using the ``-k`` option:
+
+.. code-block:: console
+
+   # curl -k -u <USER>:<PASS> -XGET https://<INDEXER_IP_ADDRESS>:9200/_cluster/health
+
+A successful connection returns a result similar to the following:
+
+.. code-block:: json
+
+   {
+       "cluster_name": "opensearch",
+       "status": "green",
+       "timed_out": false,
+       "number_of_nodes": 1,
+       "number_of_data_nodes": 1,
+       "discovered_master": true,
+       "discovered_cluster_manager": true,
+       "active_primary_shards": 9,
+       "active_shards": 9,
+       "relocating_shards": 0,
+       "initializing_shards": 0,
+       "unassigned_shards": 0,
+       "delayed_unassigned_shards": 0,
+       "number_of_pending_tasks": 0,
+       "number_of_in_flight_fetch": 0,
+       "task_max_waiting_in_queue_millis": 0,
+       "active_shards_percent_as_number": 100.0
+   }

source/user-manual/capabilities/vulnerability-detection/index.rst

@@ -2,7 +2,7 @@
 
 .. meta::
    :description: The Vulnerability Detection module detects vulnerabilities in applications installed on the endpoints. Learn more about this capability in this section.
-  
+
 Vulnerability detection
 =======================
 
@@ -23,3 +23,4 @@ The Wazuh Vulnerability Detection module helps users discover vulnerabilities in
       how-it-works
       configuring-scans
       offline-update
+      troubleshooting

source/user-manual/capabilities/vulnerability-detection/known-issues.rst

@@ -0,0 +1,133 @@
+.. Copyright (C) 2015, Wazuh, Inc.
+
+.. meta::
+   :description: Learn how to solve common issues with the Vulnerability Detection module in this section of the documentation.
+
+Known issues
+============
+
+This section lists known issues that might occur when using the Vulnerability Detection module. It includes the affected versions, fixes, and remediation steps for situations where an upgrade is not feasible.
+
+
+Dangling entries in the vulnerabilities dashboard
+-------------------------------------------------
+
+.. list-table:: Issue description
+   :widths: 15 50
+
+   *  -  Problem
+      -
+         -  Reported vulnerabilities for agents that were removed from the environment.
+         -  Reported vulnerabilities for uninstalled or upgraded packages.
+   *  -  Cause
+      -  The agent removal event isn’t processed.
+
+         -  Example: Queued scan events and a content update triggers a re-scan.
+   *  -  Affected versions
+      -  Wazuh 4.8.0 through 4.9.x.
+   *  -  Fix available
+      -  Wazuh 4.10.0 introduces a fix that ensures processing agent removal events immediately. However, upgrading doesn't remove pre-existing dangling entries, which require manual cleanup.
+
+Remediation plan
+^^^^^^^^^^^^^^^^
+
+Apply a full reset of the module’s data, but only after addressing common configuration and environmental issues.
+
+Step 1: Address common issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  **Inactive agent or connection problems**:
+
+   -  Verify the agent is active and reporting. Check agent logs for errors and warnings about the connection with the manager.
+   -  Ensure the agent’s inventory doesn’t list uninstalled packages. If it does, there might be a problem with Syscollector.
+
+-  **Server-Indexer communication problems**:
+
+   -  Check manager logs for errors like ``No available server`` or ``Failed to sync agent 'X' with the indexer``.
+   -  Query the indexer’s health with ``GET _cluster/health``. The cluster status must be:
+
+      -  Wazuh v4.8.0–v4.9.0: ``green``
+      -  Wazuh v4.9.1 and later: ``green`` or ``yellow``
+
+-  **Pending inventory updates**:
+
+   -  Wait for the next :doc:`Syscollector </user-manual/capabilities/system-inventory/configuration>` scan after removing agents or upgrading packages.
+
+
+Step 2: Reset the module's data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the above steps don’t resolve the issue, follow these steps for every Wazuh manager node:
+
+#. Stop the Wazuh manager.
+
+   .. code-block:: console
+
+      # systemctl stop wazuh-manager
+
+#. Disable the Vulnerability Detector module:
+
+   .. code-block:: xml
+      :emphasize-lines: 2
+
+      <vulnerability-detection>
+         <enabled>no</enabled>
+         <!-- Other configurations -->
+      </vulnerability-detection>
+
+#. Delete state databases. They store data such as agent vulnerabilities and queued events.
+
+   .. code-block:: console
+
+      # rm -rf /var/ossec/queue/vd/inventory/
+      # rm -rf /var/ossec/queue/vd/delayed/
+      # rm -rf /var/ossec/queue/vd/event/
+      # rm -rf /var/ossec/queue/indexer/
+
+#. Clean the vulnerabilities index.
+
+   .. code-block:: none
+
+      DELETE wazuh-states-vulnerabilities-*
+
+#. Ensure the index is clean.
+
+   .. code-block:: none
+
+      GET wazuh-states-vulnerabilities-*/_count
+
+   .. code-block:: json
+      :class: output
+
+      {
+        "count": 0,
+        "_shards": {
+          "total": 0,
+          "successful": 0,
+          "skipped": 0,
+          "failed": 0
+        }
+      }
+
+#. Start the Wazuh manager. The module updates its state to disabled.
+
+   .. code-block:: console
+
+      # systemctl start wazuh-manager
+
+#. Enable the Vulnerability Detector module.
+
+   .. code-block:: xml
+      :emphasize-lines: 2
+
+      <vulnerability-detection>
+         <enabled>yes</enabled>
+         <!-- Other configurations -->
+      </vulnerability-detection>
+
+#. Restart the manager to initiate a re-scan.
+
+   .. code-block:: console
+
+      # systemctl restart wazuh-manager
+

source/user-manual/capabilities/vulnerability-detection/troubleshooting.rst

@@ -0,0 +1,15 @@
+.. Copyright (C) 2015, Wazuh, Inc.
+
+.. meta::
+   :description: Learn how to solve common issues with the Vulnerability Detection module in this section of the documentation.
+
+Troubleshooting
+===============
+
+This section provides solutions to common issues with the Vulnerability Detection module. It includes FAQs, known issues, fixed versions, and applicable workarounds.
+
+.. toctree::
+   :maxdepth: 1
+
+   FAQ
+   known-issues