Rules are defined in files with a '.rules' file extension. These files are YAML files respecting the Darwinium .rules format.
The Rule Editor provides a simplified way of creating a Ruleset via a graphical 'drag and drop' style interface.
Signals along with Features are key data points for making a decision within a Journey Step.
Rules are binary checks against a Condition and can be TRUE or FALSE (commonly also referred to as 'Flags' by programmers).
If the Condition evaluates as TRUE, then the Signal is set and published for use by other Models and the Decision Strategy. However, if the Condition evaluates to FALSE, then the Signal is not set and is not published.
Rulesets publish their Signals to the outcomes['CHAMPION'].models.signals attribute.
The Decision Strategy publishes its Signals to the outcomes['CHAMPION'].decision_strategy.signals attribute.
Creating a New Rules File
First click on the "Workflows" icon
Click on the "add a new file" icon inside the file explorer on the right-hand menu:
Next, enter the name of the rules file and be sure to give it a '.rules' extension, so that it's recognised as a rules file.
Double click the new rules file to launch the Rule Editor.
At the top of the Rule Editor is a drop down to choose the type of Rules being edited.
- Decision Outcome - This type of Rule is used to directly set the outcome of a Decision within a Journey. Instead of just producing Signals or Scores, it determines the final action (e.g., Allow, Review, Block) based on the conditions defined in the rule.
- Scoring Model - (default) is used to implement a Rule Based System that produces Signals and a Score.
- Proxy Action - This is a special type of Rule for handling with Proxy Actions. Please refer to the Proxy Actions article for more information.
Use the Add Rule button located on the top-right to add new rule:
A new window will appear, allowing you to set the parameters for your rule.
Here's what each parameter means:
| Parameter Name | Description |
|---|---|
| Rule Name | The label you give your rule. If the condition below evaluates to TRUE, this name will also be used as the Signal Name that gets generated. |
| Score | If the Condition evaluates to TRUE, then the configured score will be added to the total score which is returned at the end of the Rules. Positive scores can be used to increase the total score (increasing Trust) whilst negative scores can be used to lower the total score (increasing Risk).For more information on Scoring, please refer to the Scoring and Percentiles article. |
| Condition | Defines the logical expression that must evaluate to TRUE for the Rule to trigger. When the condition is satisfied, the following will occur:
|
| Category | Category is an optional setting for configuring a Signal Category. Signal Categories allow high level grouping of Signals which is useful for Analysis and the authoring Rules. Select a Signal Category, if the Signal Category doesn't exist then a new one can be added by entering a new value, and then selecting "Add Category".
|
| Comment | Use this field to leave notes for yourself or your team about the purpose of the Rule. It has no effect on how the Rule runs. |
| Add Labels | Specifies which labels to attach when the Rule condition evaluates to TRUE. Labels are typically used to categorize events, group related data, or trigger downstream workflows. |
| Remove Labels | Specifies which labels to detach when the Rule condition evaluates to TRUE. This can be used to clear outdated classifications or reset previous labeling decisions. |
| Set Attributes | Used to update or override the value of a selected Attribute when the Rule condition evaluates to TRUE |
| Remove Attributes | Used to clear the value of a selected Attribute when the Rule condition evaluates to TRUE. |
Example of a rule.
has(outcome['CHAMPION'].models.signals, 'MY SIGNAL NAME')not has(outcome['CHAMPION'].models.signals, 'MY SIGNAL NAME')These queries can be executed in the investigations tab.
Setting and Removing Attributes
The rule editor gives you the ability to map values from an expression to an Darwinium attribute that can be used for investigative purposes or features.
Here's an example of splitting a JA4 string into an array and storing the 2nd index in a custom_identifier attribute.
Note that ".identifier"extensions enable the attribute to be used in features where you may want to run velocity or distinct calculations.
The “Remove Attribute” feature clears the selected attribute by setting its value to null whenever the rule is triggered.
If a value was previously assigned to this custom_identifier either mapped from a journey step or set by another rule, the Remove Attribute action will clear it.
When this rule executes, the attribute’s value is set to null.
Adding and Removing Labels
Labels are tags that can be dynamically assigned to identifiers (e.g. usernames, device identifiers, device signatures etc) when a condition evaluates to TRUE.
They are useful for whitelists, blocklists, investigating, truth data review, grouping, rule conditions, and more.
Please refer to Labels for more information.
To add a label to an existing rule, double-click on the signal name of a given rule and select "Add new"under the "Add Label" section
Select a category and a label from the dropdown menu and click Save.
Analytics
You may notice the “Analytics” column, which provides visibility into how often a signal contributes to detection outcomes.
In the example shown, 20,113 events were rejected and 457,881 events were accepted.
The values shown here reflect the number of events in which the signal was present and resulted in either an allowed or rejected outcome.
To ensure the metrics reflect the correct environment, navigate to the bottom-left corner of the screen and select the environment you want to view.
Groups
Nested rule groups let you create a hierarchy of logic where a top-level (master) rule must be true before any child rules are evaluated. This keeps rules easy to read and ensures that detailed checks only run when they are relevant.
Example of four top-level group signals with a collapsed view:
Notice that each group signal except “Device Signature Velocities” uses a condition of true.
This means the nested rules inside those groups are always evaluated without requiring an initial gating calculation.
In contrast, the “Device Signature Velocities” group acts as a true parent gate: its nested rules are only evaluated when the top-level condition evaluates to true.
Below, we’ve expanded the “IP Velocities” group to reveal the underlying rules. These rules are evaluated only when the top-level condition and their individual conditions both evaluate to true.
You can also create groups within existing groups. To do this, right-click a rule and select “Group” from the drop-down menu. The selected rule will be placed inside a newly created parent group.
An automatic name will be assigned to the group. You can rename it and define its condition by double-clicking the new group.
Advanced
If you prefer to edit the rule file in its native YAML format, you can do so by right-clicking the rule name tab at the top of the screen and selecting “Reopen Editor With…” from the drop-down menu.
Select "Text Editor Default" from the new drop-down. This will switch to the YAML view
Repeat the steps but this time select "Darwinium Rules Active" to switch views.