add Configure Vulnerability Triage how-to

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

Author: tdruez

docs/howto-7-vulnerability-triage-configuration.rst

@@ -0,0 +1,149 @@
+.. _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.
+
+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.
+
+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.
+
+.. 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.
+
+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`.
+
+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.