docs: [five-c] add usage and configuration documentation #416 (#557)

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

Author: tdruez

docs/images/reference-policy-rules/compliance-tab-policy-rules.jpg

@@ -40,6 +40,7 @@ Welcome to the very start of your DejaCode journey!
 
     reference-data-models
     reference-vulnerability-management
+    reference-policy-rules
     reference-1
     reference-2
     reference-3-cravex

docs/images/reference-policy-rules/compliance-tab-policy-violations.jpg

@@ -20,16 +20,36 @@ Webhooks can be used to:
 - Push updates to a monitoring or reporting dashboard
 - Synchronize status changes with an external ticketing system
 - Trigger automation in CI/CD pipelines
+- Alert a Slack channel when new policy violations are detected or resolved
+- Notify security teams when new vulnerability data is available
 
 Available events
 ----------------
 
-The following events can be configured as webhook triggers:
+The following events can be configured as webhook triggers.
+
+**Request events**
 
 - ``request.added`` — A new request is created
 - ``request.updated`` — An existing request is modified
 - ``request_comment.added`` — A comment is added to a request
-- ``vulnerability.data_update`` — Vulnerability data is updated
+
+**Vulnerability events**
+
+- ``vulnerability.data_update`` — Vulnerability data is updated (daily refresh or
+  package import)
+
+**Policy events**
+
+- ``policy.violation_detected`` — One or more new policy violations are detected
+  during a rule evaluation run
+- ``policy.violation_resolved`` — One or more policy violations are resolved during
+  a rule evaluation run
+
+**User events**
+
+- ``user.locked_out`` — A user account is locked out following failed login attempts
+- ``user.added_or_updated`` — A user account is created or modified
 
 .. note::
 
@@ -60,15 +80,14 @@ with the event payload.
 Payload structure
 -----------------
 
-The default webhook payload is JSON-formatted and contains at least:
+DejaCode uses two payload formats depending on the event type.
 
-- ``hook`` — The data related to the webhook, like event name, e.g. ``request.created``
-- ``data`` — Object containing event-specific data
+**Structured payload** (request events)
 
-If **extra payload** is defined, it is merged into the JSON body.
-If **extra headers** are defined, they are added to the HTTP request.
+Request events use a structured JSON format containing a ``hook`` object with webhook
+metadata and a ``data`` object with the full serialized resource.
 
-Example payload::
+Example payload for ``request.added``::
 
     {
       "hook": {
@@ -107,6 +126,32 @@ Example payload::
       }
     }
 
+**Text payload** (vulnerability and policy events)
+
+Vulnerability and policy events use a simpler format with a single ``text`` field
+containing a human-readable summary of the event.
+
+Example payload for ``vulnerability.data_update``::
+
+    {
+      "text": "[DejaCode] New vulnerabilities detected!\n42 vulnerabilities affecting 7 packages"
+    }
+
+Example payload for ``policy.violation_detected``::
+
+    {
+      "text": "[DejaCode] Policy violations detected for MyApp 2.0\n- Vulnerability Detected: 3 violation(s)\n- Vulnerability Stale: 1 violation(s)"
+    }
+
+Example payload for ``policy.violation_resolved``::
+
+    {
+      "text": "[DejaCode] 2 policy violation(s) resolved for MyApp 2.0"
+    }
+
+If **extra payload** is defined on the webhook, it is merged into the JSON body.
+If **extra headers** are defined, they are added to the HTTP request.
+
 Security considerations
 -----------------------
 

docs/images/reference-policy-rules/dataspace-configuration-policy-rules-config.jpg

@@ -0,0 +1,278 @@
+.. _reference_policy_rules:
+
+Policy Rules Engine
+===================
+
+DejaCode includes a **Policy Rules Engine** that continuously evaluates configurable
+compliance rules against your products and records violations. It provides a structured
+way to detect, track, and resolve compliance issues across usage policies, license
+coverage, and vulnerability exposure.
+
+When a rule is triggered, DejaCode records a **policy violation** with a count of the
+affected packages and the detection date. Violations are automatically resolved when the
+underlying condition is corrected.
+
+All rules are **disabled by default**. Each dataspace activates and configures the
+rules that are relevant to its compliance program via the **Dataspace Configuration**
+form.
+
+1. Built-in Rules
+-----------------
+
+Eight rules are available out of the box, organized into two categories: policy-based
+rules and vulnerability-based rules.
+
+**Policy-based rules**
+
+.. list-table::
+   :header-rows: 1
+
+   * - Rule type
+     - Label
+     - Severity
+     - Description
+   * - ``usage_policy_error``
+     - **Usage Policy Error**
+     - Error
+     - Detects packages assigned a usage policy flagged with an error compliance alert.
+   * - ``usage_policy_warning``
+     - **Usage Policy Warning**
+     - Warning
+     - Detects packages assigned a usage policy flagged with a warning compliance alert.
+   * - ``license_policy_error``
+     - **License Policy Error**
+     - Error
+     - Detects packages whose licenses are assigned a usage policy flagged with an error
+       compliance alert.
+   * - ``license_policy_warning``
+     - **License Policy Warning**
+     - Warning
+     - Detects packages whose licenses are assigned a usage policy flagged with a warning
+       compliance alert.
+   * - ``license_coverage_gap``
+     - **License Coverage Gap**
+     - Warning
+     - Detects packages with no license expression.
+
+**Vulnerability-based rules**
+
+.. list-table::
+   :header-rows: 1
+
+   * - Rule type
+     - Label
+     - Severity
+     - Description
+   * - ``vulnerability_detected``
+     - **Vulnerability Detected**
+     - Error
+     - Detects packages with at least one known vulnerability. Supports an optional
+       ``min_risk_score`` parameter to restrict detection to vulnerabilities above a
+       minimum risk score.
+   * - ``vulnerability_unresolved``
+     - **Vulnerability Unresolved**
+     - Warning
+     - Detects packages with known vulnerabilities that have no completed triage analysis
+       (i.e., no analysis in a terminal state: resolved, resolved_with_pedigree, or
+       not_affected).
+   * - ``vulnerability_stale``
+     - **Vulnerability Stale**
+     - Error
+     - Detects packages with high-risk vulnerabilities that have remained unaddressed
+       beyond a configurable number of days. Supports ``max_days`` and ``min_risk_score``
+       parameters.
+
+.. seealso::
+    Refer to :ref:`reference_vulnerability_management` for background on vulnerability
+    fields such as risk score used by the vulnerability-based rules.
+
+**Severity levels** determine how violations are displayed in the compliance tab:
+
+- **Error** rules are highlighted in red and indicate a critical compliance issue
+  requiring immediate attention.
+- **Warning** rules are highlighted in yellow and indicate a condition that requires
+  attention but does not necessarily block a release.
+
+2. Violation Lifecycle
+----------------------
+
+Each policy violation is a record associated with a product and a rule type. Its
+lifecycle follows these states:
+
+- **Detected**: the violation is created the first time a rule evaluation finds the
+  condition triggered. The ``detected_date`` is set at this point and never changes.
+- **Active**: the violation remains active as long as the condition persists across
+  subsequent evaluations.
+- **Resolved**: when a rule evaluation finds the condition is no longer triggered, the
+  violation is marked resolved and a ``resolved_date`` is recorded.
+- **Re-activated**: if the condition recurs after being resolved, the existing violation
+  record is updated in place (the original ``detected_date`` is preserved).
+
+Only **active (unresolved)** violations are shown in the compliance tab and returned
+by the REST API.
+
+3. Configuration
+----------------
+
+Policy rules are configured per dataspace using the ``policy_rules_config`` JSON field
+in the **Dataspace Configuration** form, accessible from the Admin interface under
+**Dataspaces > Dataspace configurations**.
+
+.. image:: images/reference-policy-rules/dataspace-configuration-policy-rules-config.jpg
+
+Each entry in the JSON object is keyed by the rule type and supports three options:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Description
+   * - ``is_active``
+     - Boolean. Set to ``true`` to enable the rule. Defaults to ``false`` (disabled).
+   * - ``threshold``
+     - Integer. Violations are only recorded when the count strictly exceeds this value.
+       Defaults to ``0``, meaning any violation triggers the rule.
+   * - ``parameters``
+     - Object. Rule-specific parameters (see parameter reference below).
+
+**Example configuration**::
+
+    {
+        "usage_policy_error": {
+            "is_active": true
+        },
+        "license_coverage_gap": {
+            "is_active": true,
+            "threshold": 2
+        },
+        "vulnerability_detected": {
+            "is_active": true,
+            "parameters": {
+                "min_risk_score": 7.0
+            }
+        },
+        "vulnerability_stale": {
+            "is_active": true,
+            "parameters": {
+                "max_days": 14,
+                "min_risk_score": 8.0
+            }
+        }
+    }
+
+.. note::
+    Rules that are omitted from the configuration, or that do not have ``is_active``
+    set to ``true``, are skipped during evaluation and any previously open violations
+    for those rules are automatically resolved.
+
+3.1 Rule Parameters
+^^^^^^^^^^^^^^^^^^^
+
+The following parameters are supported by rules that accept them:
+
+**Vulnerability Detected** (``vulnerability_detected``)
+
+- ``min_risk_score`` (float, 0.0-10.0): only flag packages with at least one
+  vulnerability whose risk score is greater than or equal to this value. When omitted,
+  any vulnerability triggers the rule regardless of score.
+
+**Vulnerability Stale** (``vulnerability_stale``)
+
+- ``max_days`` (integer): maximum number of days a high-risk vulnerability may remain
+  without a completed analysis before the package is flagged. Defaults to ``30``.
+- ``min_risk_score`` (float, 0.0-10.0): only consider vulnerabilities whose risk score
+  is greater than or equal to this value. Defaults to ``8.0``.
+
+4. Evaluation
+-------------
+
+4.1 Automatic Evaluation
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Rules are re-evaluated automatically in the background (via the task queue) whenever
+any of the following changes occur:
+
+- A **product** is saved.
+- A **package is added to or removed from** a product.
+- A **package** record is updated (for example, a new vulnerability is linked to it).
+- The **Dataspace Configuration** is saved, which triggers re-evaluation of all
+  products in the dataspace.
+
+4.2 Manual Re-evaluation
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Rules can also be re-evaluated on demand in two ways:
+
+- From the **Product Administration** form in the Admin interface, using the
+  **Evaluate policy rules** bulk action on the product list.
+- From the **compliance tab** of a product detail page, using the re-evaluate button
+  next to the policy violations panel.
+
+  .. image:: images/reference-policy-rules/manual-reevaluation-button.jpg
+     :width: 400
+
+5. Compliance Tab
+-----------------
+
+.. image:: images/reference-policy-rules/compliance-tab-policy-violations.jpg
+
+The **Compliance** tab on each product detail page displays an overview of active
+policy violations. For each triggered rule, the table shows:
+
+- The rule label and severity (color-coded badge).
+- The rule description.
+- The number of packages **in violation**, linked to the product inventory pre-filtered
+  to show only those packages.
+- The **detection date** of the violation.
+
+The badge count in the panel header reflects the total number of triggered rules. Its
+color is red if at least one error-severity rule is triggered, yellow if only
+warning-severity rules are triggered.
+
+Clicking the **info icon** next to the panel title opens a modal listing all configured
+rules with their current status (Triggered, OK, or Disabled).
+
+.. image:: images/reference-policy-rules/compliance-tab-policy-rules.jpg
+   :width: 500
+   :align: center
+
+6. Webhook Notifications
+------------------------
+
+The policy rules engine fires webhook events when violations change state. These can be
+used to integrate DejaCode compliance alerts into external workflows such as Slack,
+ticketing systems, or CI/CD pipelines.
+
+Two events are available:
+
+- ``policy.violation_detected``: fired when one or more **new** violations are detected
+  during an evaluation run. The payload includes the product name and a summary of
+  triggered rules with their violation counts.
+- ``policy.violation_resolved``: fired when violations are resolved during an evaluation
+  run. The payload includes the product name and the number of violations resolved.
+
+.. seealso::
+    :ref:`integrations_webhook` for instructions on configuring webhook endpoints and
+    event subscriptions.
+
+7. REST API
+-----------
+
+Active policy violations for a product are accessible via the REST API at::
+
+    GET /api/v2/products/{uuid}/policy_violations/
+
+The response is a list of active (unresolved) violations, each including:
+
+- ``rule_type``: the rule identifier (e.g., ``vulnerability_detected``).
+- ``rule_label``: the human-readable rule name.
+- ``rule_description``: a short description of what the rule detects.
+- ``rule_severity``: ``"error"`` or ``"warning"``.
+- ``violation_count``: the number of packages currently in violation.
+- ``detected_date``: when the violation was first recorded.
+
+Only active (unresolved) violations are returned by this endpoint.
+
+.. seealso::
+    Refer to the **API documentation** from the :guilabel:`Tools` menu for detailed
+    guidance on authentication and available endpoints.