[cravex2-reachability] Add documentation for triage rules (#565)

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/howto-7-vulnerability-triage-configuration.rst

@@ -0,0 +1,160 @@
+.. _how_to_7:
+
+How To 7 - Configure Vulnerability Triage
+=========================================
+
+This chapter explains how to create and configure **Triage Rulesets** for your
+Dataspace and how to assign them to products. Triage rulesets automatically detect
+vulnerabilities that match configured conditions and recommend a remediation action to
+your product teams.
+
+All rulesets are disabled by default. You must create and configure the rulesets that
+are relevant to your security program, then assign them to the products you want to
+monitor.
+
+.. seealso::
+    Refer to :ref:`reference_vulnerability_triage` for a complete description of all
+    available rules, actions, triage record lifecycle, and configuration options.
+
+.. tip::
+    To get started quickly, a set of reference rulesets and presets covering common
+    scenarios can be seeded automatically with ``./manage.py create_triage_rulesets
+    <dataspace_name>``. This section covers creating a ruleset manually for full
+    control over its rules and thresholds.
+
+1. Create a Triage Ruleset
+--------------------------
+
+1. From the DejaCode **Administration dashboard**, navigate to
+   :guilabel:`Vulnerabilities > Triage Rulesets`.
+2. Click :guilabel:`Add Triage Ruleset`.
+3. Fill in the **Name** field with a descriptive label (e.g., "Critical and Exploited").
+4. Select an **Action** from the dropdown. This is the remediation action that will be
+   recommended when any rule in the ruleset fires.
+5. Set a **Precedence** value (integer). Higher values take priority when multiple
+   rulesets match the same vulnerability on the same product.
+6. Leave **Enabled** checked to make the ruleset active immediately after saving.
+
+.. image:: images/howto-7-vulnerability-triage-configuration/add-ruleset-form.jpg
+
+2. Configure Rules
+------------------
+
+Below the base fields, each built-in rule appears as a collapsible section.
+
+1. Expand the rule sections you want to activate.
+2. Check the :guilabel:`Enable [Rule Name]` checkbox to include that rule in the
+   ruleset evaluation.
+3. For rules that support parameters, adjust the threshold values:
+
+   - **Risk Score**: set :guilabel:`Min risk score` (default 8.0) to restrict
+     detection to vulnerabilities at or above that score.
+   - **Weighted Risk**: set :guilabel:`Min weighted risk score` (default 8.0) to
+     restrict detection by weighted package exposure.
+   - **Stale Vulnerability**: set :guilabel:`Max days` (default 30) and
+     :guilabel:`Min risk score` (default 8.0).
+
+A ruleset must have at least one rule enabled to produce any triage records.
+
+Click :guilabel:`Save` to create the ruleset. Disabling a rule that was previously
+active removes the triage records it produced on the next evaluation.
+
+.. image:: images/howto-7-vulnerability-triage-configuration/rule-sections.jpg
+   :width: 500
+
+3. Set Up an Analysis Preset
+----------------------------
+
+An **Analysis Preset** instructs the engine to automatically apply default analysis
+values to each vulnerability matched by the ruleset. This is useful when you want to
+pre-fill new analyses with a known state, such as marking newly detected vulnerabilities
+as ``in_triage``.
+
+To create an Analysis Preset:
+
+1. Navigate to :guilabel:`Vulnerabilities > Analysis Presets`.
+2. Click :guilabel:`Add Analysis Preset`.
+3. Fill in the **Name** and optionally a **Description**.
+4. Under **Analysis defaults**, configure the fields you want the engine to apply:
+
+   - **State**: e.g., ``in_triage`` to mark all new analyses as being evaluated.
+   - **Justification**, **Responses**, **Detail**, **Is Reachable**: leave blank to
+     leave that field unchanged on any existing analysis.
+
+5. Click :guilabel:`Save`.
+
+To attach the preset to a ruleset, open the ruleset form and select the preset in the
+:guilabel:`Analysis Preset` field, then save.
+
+.. image:: images/howto-7-vulnerability-triage-configuration/add-preset-form.jpg
+
+.. note::
+    Only analyses created by the preset are updated on subsequent evaluation runs.
+    Any analysis modified by a user is never overwritten.
+
+4. Link a Request Template
+--------------------------
+
+When a **Request Template** is linked to a ruleset, the engine opens one DejaCode
+request per new triage record automatically. This routes newly detected vulnerabilities
+into a review workflow without manual intervention.
+
+Prerequisites:
+
+- A **Request Template** of content type **Product** must already exist under
+  :guilabel:`Workflow > Request Templates`.
+- The template must have a creator (the user who created it): they are used as the
+  automatic requester. A template with no creator is rejected when you try to select
+  it on a ruleset.
+
+To link a template to a ruleset:
+
+1. Open the ruleset form in the Admin interface.
+2. Select the template in the :guilabel:`Request Template` field. Only product-type
+   templates are listed.
+3. Click :guilabel:`Save`.
+
+From the next evaluation, new triage records will have a DejaCode request opened
+automatically. Triage records that already have a linked request are not affected by
+subsequent evaluations.
+
+.. _how_to_7_assign_rulesets:
+
+5. Assign Rulesets to Products
+------------------------------
+
+A ruleset has no effect until it is assigned to one or more products.
+
+1. Open a product detail page.
+2. Navigate to the :guilabel:`Vulnerabilities` tab.
+3. Click :guilabel:`Manage Triage Rulesets` in the triage panel header.
+4. In the modal that opens, select the rulesets you want to assign to this product.
+5. Click :guilabel:`Save`.
+
+.. image:: images/howto-7-vulnerability-triage-configuration/manage-rulesets-modal.jpg
+
+The engine evaluates all assigned and enabled rulesets immediately. The
+**Recommendation** column appears in the Vulnerabilities tab as soon as at least one
+enabled ruleset is assigned.
+
+To unassign a ruleset, open the same modal and deselect it. Existing triage records
+for that ruleset are deleted (a record with an open request is kept so reassigning the
+ruleset later reconnects to it instead of opening a duplicate). Preset-applied analyses
+are left in place: only the tracking record is removed, not the analysis itself.
+
+6. Manage Precedence
+--------------------
+
+When multiple rulesets are assigned to a product and their rules overlap on the same
+vulnerability, only the record from the highest-precedence ruleset is displayed in the
+Recommendation column. Lower-precedence records still exist and are maintained by the
+engine, but are hidden from the product view.
+
+To adjust precedence:
+
+1. Open the ruleset form in the Admin interface.
+2. Change the :guilabel:`Precedence` value. A higher number raises the ruleset's
+   priority.
+3. Click :guilabel:`Save`.
+
+Re-evaluation of all assigned products is triggered automatically after saving.