docs: [five-c] add tutorial and how-to documentation #418

docs/howto-6-policy-rules-configuration.rst

@@ -0,0 +1,136 @@
+.. _how_to_6:
+
+How To 6 - Configure Policy Rules
+=================================
+
+This chapter explains how to activate and configure the **Policy Rules Engine** for
+your Dataspace. Policy rules evaluate compliance conditions against your products
+automatically and record violations when thresholds are exceeded.
+
+All rules are disabled by default. You must explicitly enable the rules that are
+relevant to your compliance program and, optionally, adjust their parameters and
+thresholds.
+
+.. seealso::
+    Refer to :ref:`reference_policy_rules` for a complete description of all available
+    rules, configuration options, and violation lifecycle.
+
+1. Access the Policy Rules Configuration
+----------------------------------------
+
+1. From the DejaCode **Administration dashboard**, navigate to :guilabel:`Dataspaces`.
+2. Open your Dataspace by clicking on its name.
+3. Scroll down to the **Policy Rules Configuration** section.
+
+.. image:: images/howto-6-policy-rules-configuration/policy-rules-configuration-section.jpg
+
+Each built-in rule is listed with its label, description, threshold, and optional
+parameters.
+
+2. Enable a Rule
+----------------
+
+To activate a rule check the :guilabel:`Enable this rule` checkbox.
+
+.. image:: images/howto-6-policy-rules-configuration/enable-rule-checkbox.jpg
+   :width: 150
+
+Click :guilabel:`Save` at the bottom of the Dataspace form. DejaCode will immediately
+schedule a background re-evaluation of all products in the Dataspace.
+
+To disable a rule, uncheck the :guilabel:`Enable this rule` checkbox and save. Any
+currently open violations for that rule are automatically resolved.
+
+.. note::
+    Rules that are not enabled are skipped during evaluation and any previously open
+    violations for those rules are automatically resolved.
+
+3. Set a Threshold
+------------------
+
+By default, a single violation is enough to trigger a rule. The :guilabel:`Threshold`
+field lets you tolerate a certain number of violations before a triggered state is
+recorded. Violations are only recorded when the count strictly exceeds the threshold.
+
+For example, setting a threshold of 2 on the **License Coverage Gap** rule means the
+rule is only triggered when more than 2 packages have no license expression.
+
+This is useful when a small number of violations is acceptable during remediation
+phases.
+
+4. Configure Rule Parameters
+----------------------------
+
+Only vulnerability-based rules expose additional parameter fields to narrow their scope.
+
+For the **Vulnerability Detected** rule, you can set a :guilabel:`Min Risk Score` to
+restrict detection to vulnerabilities above a minimum risk score. Leave the field blank
+to flag any vulnerability regardless of score.
+
+For the **Vulnerability Stale** rule, two parameters are available:
+
+- :guilabel:`Max Days`: the maximum number of days a high-risk vulnerability may remain
+  unaddressed before the package is flagged. Defaults to 30.
+- :guilabel:`Min Risk Score`: only vulnerabilities at or above this score are
+  considered. Defaults to 8.0.
+
+.. image:: images/howto-6-policy-rules-configuration/vulnerability-rule-parameters.jpg
+   :width: 300
+
+5. Investigate Violations
+-------------------------
+
+Once rules are active and violations have been detected, DejaCode provides two levels
+of visibility.
+
+**Compliance Dashboard**
+
+The :guilabel:`Compliance Dashboard` is a dedicated page (accessible from the main
+menu) providing an overview of all products with their compliance metrics, including a
+**Policy violations** column showing the number of active violations per product.
+Use this view to identify at a glance which products have triggered rules and
+prioritize which ones to address first.
+
+.. image:: images/howto-6-policy-rules-configuration/compliance-dashboard-violations-column.jpg
+   :width: 400
+
+**Compliance tab drill-down**
+
+From the :guilabel:`Compliance Dashboard`, click the policy violations count on a
+product row to open its :guilabel:`Compliance` tab directly.
+The **Policy violations** panel lists each triggered rule with its violation count
+and detection date.
+
+.. image:: images/howto-6-policy-rules-configuration/compliance-tab-policy-violations.jpg
+
+.. tip::
+    To see the status of all active rules, including those that are not triggered,
+    click the info icon next to the panel title. A modal opens showing every enabled
+    rule with its current status: **Triggered** or **OK**.
+
+To drill into the affected packages for a specific rule:
+
+1. In the **Policy violations** panel, locate the rule you want to investigate.
+2. Click the violation count in the **In violation** column.
+
+The product inventory opens pre-filtered to show only the packages that triggered
+that rule. You can use the inventory's standard filters and sorting to prioritize
+remediation.
+
+6. Set Up Notifications
+-----------------------
+
+DejaCode can notify external systems automatically when policy violations are detected
+or resolved, without requiring manual checks of the compliance tab.
+
+Two webhook events are available:
+
+- ``policy.violation_detected``: fired when one or more new violations are detected
+  during a rule evaluation run.
+- ``policy.violation_resolved``: fired when violations are resolved.
+
+To receive these notifications, configure a webhook in the Admin interface pointing to
+your target endpoint (Slack, ticketing system, CI/CD pipeline, or any HTTP receiver).
+
+.. seealso::
+    :ref:`integrations_webhook` for instructions on creating and configuring webhooks.

docs/index.rst

@@ -23,6 +23,7 @@ Welcome to the very start of your DejaCode journey!
     tutorial-4-vulnerabilities
     tutorial-5-sboms
     tutorial-6-vuln-report
+    tutorial-7-policy-rules
 
 .. toctree::
     :maxdepth: 1
@@ -33,6 +34,7 @@ Welcome to the very start of your DejaCode journey!
     howto-3
     howto-4-product-vulnerability-analysis
     howto-5-product-object-permissions
+    howto-6-policy-rules-configuration
 
 .. toctree::
     :maxdepth: 1

docs/integrations-webhook.rst

@@ -46,6 +46,9 @@ The following events can be configured as webhook triggers.
 - ``policy.violation_resolved`` — One or more policy violations are resolved during
   a rule evaluation run
 
+.. seealso::
+    :ref:`how_to_6` for instructions on enabling policy rules in your Dataspace.
+
 **User events**
 
 - ``user.locked_out`` — A user account is locked out following failed login attempts

docs/reference-policy-rules.rst

@@ -114,9 +114,12 @@ 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**.
+Policy rules are configured per dataspace using the **Dataspace Configuration** form
+in the Admin interface under **Dataspaces > Dataspace configurations**.
+
+.. seealso::
+    For step-by-step instructions on enabling and configuring rules through the Admin
+    UI, refer to :ref:`how_to_6`.
 
 .. image:: images/reference-policy-rules/dataspace-configuration-policy-rules-config.jpg
 
@@ -229,8 +232,8 @@ The badge count in the panel header reflects the total number of triggered rules
 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).
+Clicking the **info icon** next to the panel title opens a modal listing all active
+rules with their current status: **Triggered** or **OK**.
 
 .. image:: images/reference-policy-rules/compliance-tab-policy-rules.jpg
    :width: 500

docs/reference-vulnerability-management.rst

@@ -188,6 +188,9 @@ Key Features:
 For a step-by-step guide on using these features, refer to the dedicated
 :ref:`how_to_4` section.
 
+For automated compliance monitoring of vulnerability exposure across your products,
+refer to :ref:`reference_policy_rules` and :ref:`how_to_6`.
+
 6. Configuration Settings
 -------------------------
 

docs/tutorial-7-policy-rules.rst

@@ -0,0 +1,107 @@
+Tutorial 7 - Managing Policy Violations
+=======================================
+
+Your DejaCode administrator has configured policy rules for your Dataspace. This
+tutorial walks you through discovering policy violations on a product, understanding
+what they mean, drilling into the affected packages, and resolving them.
+
+.. seealso::
+    Refer to :ref:`reference_policy_rules` for a complete description of all available
+    rules and their violation lifecycle. If you are an administrator and need to enable
+    or configure rules, refer to :ref:`how_to_6`.
+
+Sign into DejaCode.
+
+1. Open the Compliance Dashboard
+--------------------------------
+
+1. From the main menu, navigate to the :guilabel:`Compliance Dashboard`.
+
+.. image:: images/tutorial-7-policy-rules/compliance-dashboard.jpg
+
+2. The dashboard lists all your products with their compliance metrics. Look at the
+   **Policy violations** column to see which products have active violations.
+
+3. Click the policy violations count on a product row to open its
+   :guilabel:`Compliance` tab directly.
+
+2. Review Policy Violations
+---------------------------
+
+The **Policy violations** panel shows the active violations for the product.
+
+.. image:: images/tutorial-7-policy-rules/compliance-tab-policy-violations.jpg
+
+For each triggered rule, the table shows:
+
+- The rule label and severity, color-coded as red (error) or yellow (warning).
+- A short description of what the rule detects.
+- The number of packages **in violation**.
+- The date the violation was first **detected**.
+
+The badge in the panel header shows the total number of triggered rules. Its color
+reflects the highest severity: red if at least one error rule is triggered, yellow
+if only warning rules are triggered.
+
+.. tip::
+    Click the info icon next to the panel title to open a modal listing all active
+    rules with their current status: **Triggered** or **OK**. This gives you a full
+    picture of your overall compliance status at a glance.
+
+.. image:: images/tutorial-7-policy-rules/policy-rules-modal.jpg
+   :width: 400
+   :align: center
+
+3. Drill Into Affected Packages
+-------------------------------
+
+1. In the **Policy violations** table, click the count in the **In violation** column
+   for the rule you want to investigate.
+
+.. image:: images/tutorial-7-policy-rules/violation-count-link.jpg
+   :width: 140
+   :align: center
+
+2. The :guilabel:`Inventory` tab opens pre-filtered to show only the packages that
+   triggered that rule.
+
+3. Review the packages and decide what action to take: update a license expression,
+   assign a usage policy, or triage a vulnerability.
+
+4. Resolve a Violation
+----------------------
+
+Violations are resolved automatically when the underlying condition is corrected.
+The following example shows how to resolve a **Vulnerability Unresolved** violation
+by completing a vulnerability analysis.
+
+1. From the filtered inventory, click a package to open its detail page.
+2. Navigate to the :guilabel:`Vulnerabilities` tab.
+3. For each vulnerability, click :guilabel:`Edit analysis` and set the analysis state
+   to a terminal value such as **Resolved** or **Not affected**.
+
+.. image:: images/tutorial-7-policy-rules/vulnerability-analysis-form.jpg
+   :width: 400
+   :align: center
+
+.. seealso::
+    Refer to :ref:`how_to_4` for a detailed guide on vulnerability analysis.
+
+Once all vulnerabilities on a package have a terminal analysis, that package is no
+longer counted as a violation for the **Vulnerability Unresolved** rule.
+
+5. Re-evaluate and Confirm
+--------------------------
+
+After correcting the underlying condition, trigger a manual re-evaluation to update
+the violation count immediately rather than waiting for the next automatic run.
+
+1. Return to the :guilabel:`Compliance` tab of the product.
+2. Click the re-evaluate button next to the **Policy violations** panel header.
+
+.. image:: images/tutorial-7-policy-rules/reevaluate-button.jpg
+   :width: 200
+   :align: center
+
+3. The panel refreshes with updated violation counts. Rules whose conditions are no
+   longer met are cleared from the table.

product_portfolio/templates/product_portfolio/compliance/compliance_panels.html

@@ -62,9 +62,7 @@ <h5 class="modal-title fs-6 fw-medium" id="policy-rules-modal-label">{% trans "P
                       <div class="text-body-secondary small">{{ rule.description }}</div>
                     </div>
                     <div class="flex-shrink-0">
-                      {% if not rule.is_active %}
-                        <span class="badge text-bg-secondary">{% trans "Disabled" %}</span>
-                      {% elif rule.is_violated %}
+                      {% if rule.is_violated %}
                         {% if rule.severity == "error" %}
                           <span class="badge bg-danger-subtle text-danger-emphasis">{% trans "Triggered" %}</span>
                         {% else %}

product_portfolio/tests/test_views.py

@@ -4324,17 +4324,17 @@ def test_stale_rule_type_filtered_from_context(self):
         response = self.client.get(url)
         self.assertEqual(0, response.context["policy_violation_count"])
 
-    def test_all_rules_context_reflects_active_status(self):
+    def test_all_rules_context_only_includes_active_rules(self):
         DataspaceConfiguration.objects.create(
             dataspace=self.dataspace,
             policy_rules_config={"usage_policy_error": {"is_active": True}},
         )
         self.client.login(username="nexb_user", password="secret")
         url = self.product1.get_url("tab_compliance")
         response = self.client.get(url)
-        all_rules = {rule["rule_type"]: rule for rule in response.context["all_rules"]}
-        self.assertTrue(all_rules["usage_policy_error"]["is_active"])
-        self.assertFalse(all_rules["license_coverage_gap"]["is_active"])
+        rule_types = [rule["rule_type"] for rule in response.context["all_rules"]]
+        self.assertIn("usage_policy_error", rule_types)
+        self.assertNotIn("license_coverage_gap", rule_types)
 
 
 class ComplianceDashboardPolicyViolationsTestCase(TestCase):

product_portfolio/views.py

@@ -2887,10 +2887,10 @@ def rule_registry_position(violation):
                 "description": handler.description,
                 "rule_type": rule_type,
                 "severity": handler.severity,
-                "is_active": rules_config.get(rule_type, {}).get("is_active", False),
                 "is_violated": rule_type in violated_rule_types,
             }
             for rule_type, handler in RULE_REGISTRY.items()
+            if rules_config.get(rule_type, {}).get("is_active", False)
         ]
         has_error_violation = any(
             violation.rule_severity == "error" for violation in policy_violations