diff --git a/docs/howto-6-policy-rules-configuration.rst b/docs/howto-6-policy-rules-configuration.rst new file mode 100644 index 00000000..97f9cc0b --- /dev/null +++ b/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. diff --git a/docs/images/howto-6-policy-rules-configuration/compliance-dashboard-violations-column.jpg b/docs/images/howto-6-policy-rules-configuration/compliance-dashboard-violations-column.jpg new file mode 100644 index 00000000..ed455b91 Binary files /dev/null and b/docs/images/howto-6-policy-rules-configuration/compliance-dashboard-violations-column.jpg differ diff --git a/docs/images/howto-6-policy-rules-configuration/compliance-tab-policy-violations.jpg b/docs/images/howto-6-policy-rules-configuration/compliance-tab-policy-violations.jpg new file mode 100644 index 00000000..5fb9c7a0 Binary files /dev/null and b/docs/images/howto-6-policy-rules-configuration/compliance-tab-policy-violations.jpg differ diff --git a/docs/images/howto-6-policy-rules-configuration/enable-rule-checkbox.jpg b/docs/images/howto-6-policy-rules-configuration/enable-rule-checkbox.jpg new file mode 100644 index 00000000..212f78b6 Binary files /dev/null and b/docs/images/howto-6-policy-rules-configuration/enable-rule-checkbox.jpg differ diff --git a/docs/images/howto-6-policy-rules-configuration/policy-rules-configuration-section.jpg b/docs/images/howto-6-policy-rules-configuration/policy-rules-configuration-section.jpg new file mode 100644 index 00000000..58a0d567 Binary files /dev/null and b/docs/images/howto-6-policy-rules-configuration/policy-rules-configuration-section.jpg differ diff --git a/docs/images/howto-6-policy-rules-configuration/vulnerability-rule-parameters.jpg b/docs/images/howto-6-policy-rules-configuration/vulnerability-rule-parameters.jpg new file mode 100644 index 00000000..9c57a027 Binary files /dev/null and b/docs/images/howto-6-policy-rules-configuration/vulnerability-rule-parameters.jpg differ diff --git a/docs/images/reference-policy-rules/compliance-tab-policy-rules.jpg b/docs/images/reference-policy-rules/compliance-tab-policy-rules.jpg index 3a8f9ed8..5eb33054 100644 Binary files a/docs/images/reference-policy-rules/compliance-tab-policy-rules.jpg and b/docs/images/reference-policy-rules/compliance-tab-policy-rules.jpg differ diff --git a/docs/images/tutorial-7-policy-rules/compliance-dashboard.jpg b/docs/images/tutorial-7-policy-rules/compliance-dashboard.jpg new file mode 100644 index 00000000..4e051b88 Binary files /dev/null and b/docs/images/tutorial-7-policy-rules/compliance-dashboard.jpg differ diff --git a/docs/images/tutorial-7-policy-rules/compliance-tab-policy-violations.jpg b/docs/images/tutorial-7-policy-rules/compliance-tab-policy-violations.jpg new file mode 100644 index 00000000..11ccf16c Binary files /dev/null and b/docs/images/tutorial-7-policy-rules/compliance-tab-policy-violations.jpg differ diff --git a/docs/images/tutorial-7-policy-rules/policy-rules-modal.jpg b/docs/images/tutorial-7-policy-rules/policy-rules-modal.jpg new file mode 100644 index 00000000..5eb33054 Binary files /dev/null and b/docs/images/tutorial-7-policy-rules/policy-rules-modal.jpg differ diff --git a/docs/images/tutorial-7-policy-rules/reevaluate-button.jpg b/docs/images/tutorial-7-policy-rules/reevaluate-button.jpg new file mode 100644 index 00000000..a30315bc Binary files /dev/null and b/docs/images/tutorial-7-policy-rules/reevaluate-button.jpg differ diff --git a/docs/images/tutorial-7-policy-rules/violation-count-link.jpg b/docs/images/tutorial-7-policy-rules/violation-count-link.jpg new file mode 100644 index 00000000..4d5a8a19 Binary files /dev/null and b/docs/images/tutorial-7-policy-rules/violation-count-link.jpg differ diff --git a/docs/images/tutorial-7-policy-rules/vulnerability-analysis-form.jpg b/docs/images/tutorial-7-policy-rules/vulnerability-analysis-form.jpg new file mode 100644 index 00000000..9085fd24 Binary files /dev/null and b/docs/images/tutorial-7-policy-rules/vulnerability-analysis-form.jpg differ diff --git a/docs/index.rst b/docs/index.rst index 674096ce..5846e2f1 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/integrations-webhook.rst b/docs/integrations-webhook.rst index efed3992..6cd687b6 100644 --- a/docs/integrations-webhook.rst +++ b/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 diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst index 79e32375..d22e6319 100644 --- a/docs/reference-policy-rules.rst +++ b/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 diff --git a/docs/reference-vulnerability-management.rst b/docs/reference-vulnerability-management.rst index f4a61c74..a0daecf1 100644 --- a/docs/reference-vulnerability-management.rst +++ b/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 ------------------------- diff --git a/docs/tutorial-7-policy-rules.rst b/docs/tutorial-7-policy-rules.rst new file mode 100644 index 00000000..64727021 --- /dev/null +++ b/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. diff --git a/product_portfolio/templates/product_portfolio/compliance/compliance_panels.html b/product_portfolio/templates/product_portfolio/compliance/compliance_panels.html index 1f657cd7..697588f3 100644 --- a/product_portfolio/templates/product_portfolio/compliance/compliance_panels.html +++ b/product_portfolio/templates/product_portfolio/compliance/compliance_panels.html @@ -62,9 +62,7 @@