diff --git a/docs/images/reference-policy-rules/compliance-tab-policy-rules.jpg b/docs/images/reference-policy-rules/compliance-tab-policy-rules.jpg new file mode 100644 index 00000000..3a8f9ed8 Binary files /dev/null and b/docs/images/reference-policy-rules/compliance-tab-policy-rules.jpg differ diff --git a/docs/images/reference-policy-rules/compliance-tab-policy-violations.jpg b/docs/images/reference-policy-rules/compliance-tab-policy-violations.jpg new file mode 100644 index 00000000..25c13d6f Binary files /dev/null and b/docs/images/reference-policy-rules/compliance-tab-policy-violations.jpg differ diff --git a/docs/images/reference-policy-rules/dataspace-configuration-policy-rules-config.jpg b/docs/images/reference-policy-rules/dataspace-configuration-policy-rules-config.jpg new file mode 100644 index 00000000..39f5e6dd Binary files /dev/null and b/docs/images/reference-policy-rules/dataspace-configuration-policy-rules-config.jpg differ diff --git a/docs/images/reference-policy-rules/manual-reevaluation-button.jpg b/docs/images/reference-policy-rules/manual-reevaluation-button.jpg new file mode 100644 index 00000000..1b6ae5b1 Binary files /dev/null and b/docs/images/reference-policy-rules/manual-reevaluation-button.jpg differ 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/integrations-webhook.rst b/docs/integrations-webhook.rst index aa90da11..efed3992 100644 --- a/docs/integrations-webhook.rst +++ b/docs/integrations-webhook.rst @@ -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 ----------------------- diff --git a/docs/reference-policy-rules.rst b/docs/reference-policy-rules.rst new file mode 100644 index 00000000..79e32375 --- /dev/null +++ b/docs/reference-policy-rules.rst @@ -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.