diff --git a/docs/content/automation/rules_engine_2/about.md b/docs/content/automation/rules_engine_2/about.md index 737490df54a..08102876cc8 100644 --- a/docs/content/automation/rules_engine_2/about.md +++ b/docs/content/automation/rules_engine_2/about.md @@ -120,7 +120,7 @@ Runs and deliveries are both kept for 180 days by default, then pruned. The prod ## Where to go next * [Building Rules](../building_rules/) covers the editor, triggers, scope, conditions and templates. -* [Node Reference](../node_reference/) documents all 25 nodes. +* [Node Reference](../node_reference/) documents all 37 nodes. * [Runs](../runs/) covers execution, traces, cascading and limits. * [Deliveries](../deliveries/) covers channels, statuses, retries and replay. * [Converting from Rules Engine](../converting_from_rules_engine/) covers moving existing rules across. diff --git a/docs/content/automation/rules_engine_2/building_rules.md b/docs/content/automation/rules_engine_2/building_rules.md index 9c1f10765e4..f0eab9a6f23 100644 --- a/docs/content/automation/rules_engine_2/building_rules.md +++ b/docs/content/automation/rules_engine_2/building_rules.md @@ -14,13 +14,14 @@ A rule is built on a canvas. You drag nodes out of a palette, wire them together Open **Rules Engine 2.0 > All Rules** and choose **New Rule**, or open an existing rule to edit it. -The palette is grouped into four categories, which is also the order items flow through a typical graph: +The palette is grouped into five categories, which is also the order items flow through a typical graph: | Category | What the nodes do | |----------|-------------------| -| **Triggers** | Decide when the rule wakes up and which Findings enter it. Exactly one per graph. | +| **Triggers** | Decide when the rule wakes up and which Findings or Assets enter it. | | **Logic** | Route, limit and de-duplicate the items flowing through. | | **Findings** | Change the Findings. | +| **Assets** | Change the Assets. | | **Egress** | Send something outward: a ticket, a message, a report. | The palette is generated from the engine itself, so what you see in the editor is always exactly what the engine can execute. @@ -48,6 +49,8 @@ Preview runs the real engine, not a simulation of it, and then rolls the whole t Preview is the one execution that caps how many items it looks at, so that it stays fast. When it truncates, it says so in the trace. A real run has no such cap. +For an Asset rule, Preview lists the Assets it would change and what would change about each one, before and after, the same way it does for a Finding rule. + ## What a rule works on Every rule works on one kind of item, and its trigger decides which: @@ -73,9 +76,13 @@ Every graph starts with one of four triggers. ### Scope -Every trigger takes a **Scope**, and scope is how you narrow what the rule considers. For a Finding rule it is the same filter vocabulary the original Rules Engine uses, roughly sixty filters spanning Findings and the objects around them, so a filter you already know how to write there means the same thing here. For an Asset rule it is the Assets list's own filters instead. +Every trigger takes a **Scope**, and scope is how you narrow what the rule considers. + +A Finding trigger's scope is the same filter vocabulary the original Rules Engine uses, roughly sixty filters spanning Findings and the objects around them, so a filter you already know how to write there means the same thing here. An Asset trigger's scope is the filter vocabulary the Assets list itself uses instead — name, tags, Organization, criticality, lifecycle and the rest of that list's filters — and the scope editor is that list, so picking one works the same way it does for a Finding rule. + +Asset type is not one of those filters. The scope picker offers exactly what the Assets list can filter on, and type is not among them today. To act on Assets of one type, scope broadly and add an **If / Filter** node with a condition on `product.asset_type`, which compares the type's code rather than its display label. -Two things about scope are worth understanding: +Two things about scope are worth understanding, and both hold for either kind of rule: * **Scope is applied on top of authorization, never instead of it.** The rule runs as its owner, so scope narrows an already-authorized set. Leaving scope empty does not mean "everything in the instance", it means "everything the rule owner can see". * **An invalid scope fails the run rather than widening it.** If a filter key does not exist, or a value is one the filter would silently discard, the run errors out. A rule that does nothing is recoverable. A rule that quietly edits everything in the instance is not. @@ -158,6 +165,22 @@ Dates are ISO-8601 strings. That is deliberate: it means `gt` and `lt` order the `priority`, `risk` and `risk_score` come from Pro's prioritization. A Finding that has not been scored yet carries no value for them. +### Referring to Asset data + +An Asset item carries no `finding`, `test` or `engagement` block at all — those paths simply resolve to nothing on it. `product` is the Asset itself, and `product_type` is the Organization it belongs to, the same two keys a Finding item carries. + +| Group | Fields | +|-------|--------| +| Identity | `id`, `name`, `asset_type` | +| Classification | `business_criticality`, `platform`, `lifecycle`, `origin`, `tags` | +| Exposure | `external_audience`, `internet_accessible`, `user_records` | +| SLA and Risk Priority | `sla_configuration_id`, `sla_configuration_name`, `prioritization_engine_id`, `prioritization_engine_name` | +| Dates | `created`, `updated` | + +`asset_type` is the type's code, not its display label. + +Alongside `product`, an Asset item carries `product_type` (`id`, `name`) and `ctx`. Because the key names match, a condition or template written against `product.name` or `product_type.name` means the same thing whichever kind of rule it is in. + ### Conditions An **If / Filter** node holds a list of condition rows. Each row is a path, an operator, and a value. **Match** decides whether every row has to hold (`all`) or just one of them (`any`). @@ -252,4 +275,4 @@ The recommended order for a rule that sends anything: 4. Let it run, then read **Deliveries** and check the recorded payloads are what you intended. 5. Switch the mode to **Live**. -Simulate is not a partial run. Every Finding edit in the graph happens for real in simulate mode. Only the outbound sends are held back. +Simulate is not a partial run. Every Finding or Asset edit in the graph happens for real in simulate mode. Only the outbound sends are held back. diff --git a/docs/content/automation/rules_engine_2/node_reference.md b/docs/content/automation/rules_engine_2/node_reference.md index 597d78c4188..246624d6965 100644 --- a/docs/content/automation/rules_engine_2/node_reference.md +++ b/docs/content/automation/rules_engine_2/node_reference.md @@ -8,7 +8,7 @@ aliases: --- Note: Rules Engine 2.0 is a DefectDojo Pro-only feature. -Rules Engine 2.0 ships 35 nodes in five categories. This page documents all of them. +Rules Engine 2.0 ships 37 nodes in five categories. This page documents all of them. Unless stated otherwise, a node takes one input, produces one output called `out`, and passes every item it received on to that output. That matters when you chain nodes: a Findings node changes the Finding and then hands the item onward, so several of them in a row all apply. @@ -353,6 +353,34 @@ Removes one custom field's value from the Asset, recording what it held on the A |---------|-------| | **Field** | Which custom field to clear. | +### Naming a configuration or engine the rule owner cannot see + +Both action nodes below only offer what their rule's owner is [permitted to see](/admin/user_management/user_permission_chart/#configuration-permission-chart) in their own picker — the same permission the SLA Configuration and Prioritization Engine settings pages themselves require. That is a picker-level convenience, not the only gate: a hand-written graph naming a configuration or engine the owner cannot see still resolves it when the rule runs, so it fails the run with an error naming it instead of silently doing nothing. + +### Assign SLA Configuration + +`asset.set_sla_configuration` + +Assigns an SLA configuration to every Asset that reaches it. Findings under that Asset have their SLA expiration dates recalculated, exactly as [applying one by hand](/asset_modelling/pro_hierarchy/priority_sla/) on the Asset's own edit form does. + +| Setting | Notes | +|---------|-------| +| **SLA Configuration** | Which SLA configuration to assign. Required. | + +**An Asset already recalculating is skipped, not silently dropped.** If a person, or another rule, is already recalculating the same Asset's SLA dates when this node reaches it, writing here would not change anything and would be reverted, so the node counts that Asset as skipped instead of changed. The run's node summary reports the skip by name, alongside how many Assets were actually changed. + +### Assign Risk Priority + +`asset.set_risk_priority` + +Assigns a Risk Priority — a [prioritization engine](/asset_modelling/pro_hierarchy/priority_sla/) — to every Asset that reaches it. Findings under that Asset are rescored asynchronously. + +| Setting | Notes | +|---------|-------| +| **Risk Priority** | Which prioritization engine to assign. Required. | + +Unlike the SLA action, this node does not skip an Asset that is mid-recalculation: nothing reverts its write, so the assignment lands normally either way. + ## Egress Egress nodes are the nodes that leave DefectDojo. Every one of them records a [Delivery](../deliveries/) before anything is sent, and every one of them honours the rule's **Simulate** or **Live** mode.