add cross chapter references

Signed-off-by: tdruez <tdruez@aboutcode.org>

Author: tdruez

docs/howto-4-product-vulnerability-analysis.rst

@@ -11,8 +11,7 @@ Overview
 
 Product Vulnerability Analysis in DejaCode helps teams assess, review, and manage
 vulnerabilities specific to individual Products. The platform supports detailed
-analysis workflows, data propagation across related products, and integration with
-external tools via the **REST API**.
+analysis workflows and data propagation across related products.
 
 1. Accessing Product Vulnerability Analysis
 -------------------------------------------
@@ -39,36 +38,12 @@ vulnerability, enabling in-depth review and understanding of its potential impac
 
 .. image:: images/howto-4-product-vulnerability-analysis/vulnerabilities-tab.jpg
 
-Each entry includes the following information:
-
-- **Vulnerability ID**:
-  A unique identifier prefixed with "VCID-", such as **VCID-2024-0001**, ensuring
-  traceability.
-- **Aliases**:
-  Alternate identifiers for the vulnerability, including **CVE identifiers**
-  (e.g., **CVE-2019-17571**).
-- **Severity Levels**:
-  Categorized as **critical**, **high**, **medium**, or **low**, based on potential
-  impact.
-- **Exploitability Score**:
-  Indicates the likelihood of exploitation, with three levels:
-
-  - **0.5**: No known exploits.
-  - **1.0**: Potential exploits exist.
-  - **2.0**: Known exploits are available.
-
-- **Risk Score**:
-  A value between **0.0** and **10.0**, representing the overall risk posed by the
-  vulnerability.
-  This score is calculated by multiplying the highest severity with its weight and
-  the exploitability score, capped at **10.0**.
-- **Affected Packages**:
-  Links to the affected packages and their versions.
+Each entry includes the vulnerability ID, its aliases, severity, exploitability, and
+risk score, along with links to the affected packages.
 
-.. note::
-   All vulnerability details, including analysis results and propagation status, are
-   accessible through the **REST API**, enabling automated workflows and seamless
-   integration with external tools.
+.. seealso::
+   Refer to :ref:`reference_vulnerability_management` for a complete description of
+   these fields and how the risk score is calculated.
 
 3. Conducting Analysis
 ----------------------
@@ -158,10 +133,6 @@ To analyze a vulnerability effectively:
 6. **Save Changes**:
    Save your analysis to ensure it is available for reference and propagated as needed.
 
-.. note::
-   The analysis data is also accessible via the **REST API**, making it possible to
-   integrate with automated tools and workflows.
-
 4. Propagating Analysis Across Products
 ---------------------------------------
 
@@ -177,15 +148,16 @@ To streamline reviews, DejaCode supports analysis data propagation:
 5. Leveraging REST API for Automation
 -------------------------------------
 
-The **REST API** provides full access to vulnerability analysis data, enabling
-programmatic workflows such as:
-
-- Querying vulnerabilities linked to specific Products.
-- Automating analysis result updates.
+Vulnerability analyses are available at ``/api/v2/vulnerability_analyses/``, supporting
+create, retrieve, update, and list operations. Use it to query analyses for specific
+products or packages, and to automate analysis updates as part of your own workflows.
 
-Refer to the **API documentation** from the **"Tools" menu** for detailed guidance on
-using these endpoints.
+.. seealso::
+   Refer to the **API documentation** from the **"Tools" menu** for the full list of
+   fields and filters.
 
 .. seealso::
    Explore the :ref:`reference_vulnerability_management` chapter for an overview of
-   related features.
+   related features. If you are looking for automated, rule-based recommendations
+   instead of manual review, refer to :ref:`reference_vulnerability_triage` and
+   :ref:`how_to_7`.

docs/reference-vulnerability-management.rst

@@ -13,7 +13,7 @@ This documentation outlines how vulnerabilities are **collected**, **displayed**
 Introduction
 ------------
 
-DejaCode’s vulnerability management system relies on the **VulnerableCodeDB** service
+DejaCode's vulnerability management system relies on the **VulnerableCodeDB** service
 to collect and process vulnerability data. This service is integrated into DejaCode to
 provide seamless tracking and management of vulnerabilities associated with software
 packages and components.
@@ -191,6 +191,9 @@ For a step-by-step guide on using these features, refer to the dedicated
 For automated compliance monitoring of vulnerability exposure across your products,
 refer to :ref:`reference_policy_rules` and :ref:`how_to_6`.
 
+For automated detection and remediation recommendations based on configurable rules,
+refer to :ref:`reference_vulnerability_triage` and :ref:`how_to_7`.
+
 6. Configuration Settings
 -------------------------
 

docs/reference-vulnerability-triage.rst

@@ -205,6 +205,10 @@ analysis, it becomes user-owned and the engine will not modify it again.
 Analysis Presets are managed in the Admin interface under
 :guilabel:`Vulnerabilities > Analysis Presets`.
 
+.. seealso::
+    Refer to :ref:`how_to_4` for the meaning of each analysis field (State,
+    Justification, Responses, Detail).
+
 4.3 Request Template
 ^^^^^^^^^^^^^^^^^^^^
 

docs/tutorial-4-vulnerabilities.rst

@@ -70,6 +70,10 @@ Conduct Vulnerability Analysis
 
 .. image:: images/tutorial-4-vulnerabilities/vulnerabilities-tab-with-analysis.jpg
 
+.. seealso::
+    Refer to :ref:`how_to_4` for a detailed guide on each analysis field and its
+    meaning.
+
 Export CycloneDX SBOM with VEX
 ------------------------------
 
@@ -81,3 +85,8 @@ Export CycloneDX SBOM with VEX
 
 2. The analysis details you provide for product package vulnerabilities are
    included in the ``vulnerabilities`` section of the CycloneDX VEX output.
+
+.. seealso::
+    Once your administrator has configured triage rulesets for your Dataspace, this
+    manual review is complemented by automated remediation recommendations. Refer to
+    :ref:`user_tutorial_8_vulnerability_triage` to get started.

docs/tutorial-8-vulnerability-triage.rst

@@ -1,3 +1,5 @@
+.. _user_tutorial_8_vulnerability_triage:
+
 Tutorial 8 - Vulnerability Triage
 =================================
 
@@ -9,7 +11,9 @@ mean, recording your vulnerability analysis, and tracking the associated request
 .. seealso::
     Refer to :ref:`reference_vulnerability_triage` for a complete description of all
     available rules, actions, and triage record lifecycle. If you are an administrator
-    and need to create or configure rulesets, refer to :ref:`how_to_7`.
+    and need to create or configure rulesets, refer to :ref:`how_to_7`. If this is your
+    first time reviewing a product's vulnerabilities, start with
+    :ref:`user_tutorial_4_vulnerabilities`.
 
 Sign into DejaCode.