Add the capability to know which CVE’s affect an agent - Documentation changes

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

@@ -18,3 +18,32 @@ The global vulnerability database is created automatically, currently pulling da
 This database can be configured to be updated periodically, ensuring that the solution will check for the very latest CVEs.
 
 Once the global vulnerability database (with the CVEs) is created, the detection process looks for vulnerable packages in the inventory databases (unique per agent). Alerts are generated when a CVE (Common Vulnerabilities and Exposures) affects a package that is known to be installed in one of the monitored servers. A package is labeled as vulnerable when its version is contained within the affected range of a CVE.
+The results are presented as alerts and also stored in a database. So you can check the last scan alerts, or query every single agent's vulnerable software DB.
+
+.. _vuln_det_scan_types:
+
+Scan types
+^^^^^^^^^^
+
+The Vulnerability Detector module can run a scan on startup (:ref:`run_on_start <vuln_det_run_on_start>`) and every certain period of time (:ref:`interval <vuln_det_interval>`).
+In any of these cases, the packages that have already been scanned will wait until the :ref:`ignore_time <vuln_det_ignore_time>` expires to be re-scanned.
+This improves the performance and avoids repeated alerts during a configurable time. We have then two different types of scan:
+
+- Full scan: The first time, Vulnerability Detector scans every single package installed. After this, all the available packages are scanned again only when the configured :ref:`ignore_time <vuln_det_ignore_time>` expires.
+- Partial scans: Only new packages are scanned while :ref:`ignore_time <vuln_det_ignore_time>` is still valid.
+
+There are few considerations that arise from this behavior:
+
+- Every full scan generates alerts for all the packages, so the alerts are repeated until they get fixed.
+- The user ca not trigger a full scan manually, the only option is to decrease the :ref:`ignore_time <vuln_det_ignore_time>` setting.
+- The partial scans generate alerts for new packages, but they do not delete alerts for removed packages.
+- Partial scans can be triggered with a Manager restart.
+
+Check :doc:`Vulnerability detector settings<../../reference/ossec-conf/vuln-detector>` for more configuration details.
+
+The following example may be useful to understand all steps involved
+
+.. thumbnail:: ../../../images/manual/vuln-detector/vuln-detector-workflow.png
+ :title: Vulnerability detector workflow
+ :align: center
+ :width: 100%

source/user-manual/reference/ossec-conf/vuln-detector.rst

@@ -51,6 +51,8 @@ Enables the module.
 | **Allowed values** | yes, no |
 +--------------------+-----------------------------+
 
+.. _vuln_det_interval:
+
 interval
 ^^^^^^^^
 
@@ -62,6 +64,8 @@ Time between vulnerabilities scans.
 | **Allowed values** | A positive number that should contain a suffix character indicating a time unit: s (seconds), m (minutes), h (hours) or d (days). |
 +--------------------+------------------------------------------------------------------------------------------------------------------------------------------+
 
+.. _vuln_det_run_on_start:
+
 run_on_start
 ^^^^^^^^^^^^
 
@@ -73,17 +77,22 @@ Runs updates and vulnerabilities scans immediately when service is started.
 | **Allowed values** | yes, no |
 +----------------------+-----------+
 
+.. _vuln_det_ignore_time:
+
 ignore_time
 ^^^^^^^^^^^^
 
-Time during which vulnerabilities that have already been alerted will be ignored.
+Time during which vulnerabilities that have already been alerted will be ignored. When this time hasn't passed yet, only :ref:`partial scans <vuln_det_scan_types>` will be performed.
 
 +----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 | **Default value** | 6 hours |
 +----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 | **Allowed values** | A positive number that should contain a suffix character indicating a time unit: s (seconds), m (minutes), h (hours) or d (days). |
 +----------------------+------------------------------------------------------------------------------------------------------------------------------------+
 
+.. note:: In a partial scan new packages are scanned, but only a full scan removes the CVEs related to old packages that are not present anymore.
+
+
 provider
 ^^^^^^^^