From 7c819d2c25032726a4bca13823d129cbd391b3e6 Mon Sep 17 00:00:00 2001 From: tdruez Date: Fri, 24 Jul 2026 10:18:26 +0400 Subject: [PATCH 1/7] add Policy Rules Engine documentation Signed-off-by: tdruez --- docs/index.rst | 1 + docs/reference-policy-rules.rst | 94 +++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 docs/reference-policy-rules.rst diff --git a/docs/index.rst b/docs/index.rst index 15b41b86..674096ce 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst new file mode 100644 index 00000000..a5e099dc --- /dev/null +++ b/docs/reference-policy-rules.rst @@ -0,0 +1,94 @@ +.. _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. From b3fa91f46b9facc591d97af160af272e1f65ffb4 Mon Sep 17 00:00:00 2001 From: tdruez Date: Fri, 24 Jul 2026 10:18:59 +0400 Subject: [PATCH 2/7] add violation lifecycle section Signed-off-by: tdruez --- docs/reference-policy-rules.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst index a5e099dc..fbee8e60 100644 --- a/docs/reference-policy-rules.rst +++ b/docs/reference-policy-rules.rst @@ -92,3 +92,21 @@ rules and vulnerability-based rules. 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. From 512f177bae53f2f0ca62555e57c776656e9d9fa1 Mon Sep 17 00:00:00 2001 From: tdruez Date: Fri, 24 Jul 2026 10:26:53 +0400 Subject: [PATCH 3/7] add configuration section Signed-off-by: tdruez --- docs/reference-policy-rules.rst | 70 +++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst index fbee8e60..7bce39a6 100644 --- a/docs/reference-policy-rules.rst +++ b/docs/reference-policy-rules.rst @@ -110,3 +110,73 @@ lifecycle follows these states: 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**. + +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``. From e43368bfca7851d40749717596ecbff9631f4301 Mon Sep 17 00:00:00 2001 From: tdruez Date: Fri, 24 Jul 2026 10:40:36 +0400 Subject: [PATCH 4/7] add rules evaluation section Signed-off-by: tdruez --- docs/reference-policy-rules.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst index 7bce39a6..852e8db4 100644 --- a/docs/reference-policy-rules.rst +++ b/docs/reference-policy-rules.rst @@ -180,3 +180,28 @@ The following parameters are supported by rules that accept them: 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 **compliance tab** of a product detail page, using the re-evaluate button + next to the policy violations panel. +- From the **Product Administration** form in the Admin interface, using the + **Evaluate policy rules** bulk action on the product list. From e727566e5a1bea54b0d4f14d391f7407cf6a88b9 Mon Sep 17 00:00:00 2001 From: tdruez Date: Fri, 24 Jul 2026 10:44:14 +0400 Subject: [PATCH 5/7] add compliance tab section Signed-off-by: tdruez --- docs/reference-policy-rules.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst index 852e8db4..150e2027 100644 --- a/docs/reference-policy-rules.rst +++ b/docs/reference-policy-rules.rst @@ -205,3 +205,22 @@ Rules can also be re-evaluated on demand in two ways: next to the policy violations panel. - From the **Product Administration** form in the Admin interface, using the **Evaluate policy rules** bulk action on the product list. + +5. Compliance Tab +----------------- + +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). From 866f118fea9843ad5deb025b611b034045e9f03f Mon Sep 17 00:00:00 2001 From: tdruez Date: Fri, 24 Jul 2026 10:49:14 +0400 Subject: [PATCH 6/7] add webhook notifications section Signed-off-by: tdruez --- docs/reference-policy-rules.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst index 150e2027..ab070eeb 100644 --- a/docs/reference-policy-rules.rst +++ b/docs/reference-policy-rules.rst @@ -224,3 +224,22 @@ 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). + +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. From f6f0f8d24e5c7ef3344717a97f839ffd8cd68c06 Mon Sep 17 00:00:00 2001 From: tdruez Date: Fri, 24 Jul 2026 11:05:59 +0400 Subject: [PATCH 7/7] add REST API section Signed-off-by: tdruez --- docs/reference-policy-rules.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst index ab070eeb..d8aadffc 100644 --- a/docs/reference-policy-rules.rst +++ b/docs/reference-policy-rules.rst @@ -243,3 +243,25 @@ Two events are available: .. 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.