[cravex2-reachability] Add documentation for triage rules

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.

docs/index.rst

@@ -24,6 +24,7 @@ Welcome to the very start of your DejaCode journey!
  tutorial-5-sboms
  tutorial-6-vuln-report
  tutorial-7-policy-rules
+ tutorial-8-vulnerability-triage
 
 .. toctree::
  :maxdepth: 1
@@ -35,6 +36,7 @@ Welcome to the very start of your DejaCode journey!
  howto-4-product-vulnerability-analysis
  howto-5-product-object-permissions
  howto-6-policy-rules-configuration
+ howto-7-vulnerability-triage-configuration
 
 .. toctree::
  :maxdepth: 1
@@ -43,6 +45,7 @@ Welcome to the very start of your DejaCode journey!
  reference-data-models
  reference-vulnerability-management
  reference-policy-rules
+ reference-vulnerability-triage
  reference-1
  reference-2
  reference-3-cravex

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
 -------------------------