--- title: "Rules & signals" slug: "rules-and-signals" description: "Use a rule to recognize a condition in an event—for example, a known-risk identifier or an unusual number of login attempts." updated: 2026-10-16T09:37:35Z published: 2026-10-16T09:37:35Z canonical: "docs.darwinium.com/rules-and-signals" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.darwinium.com/llms.txt > Use this file to discover all available pages before exploring further. # Rules & signals Use a rule to recognize a condition in an event—for example, a known-risk identifier or an unusual number of login attempts. A matching rule can emit a signal, contribute a score or perform a configured action. A rules file must be attached to the relevant step workflow before it runs. Start with [How decisioning works](/docs/decisioning-overview) to understand features, rules, models and the decision strategy together. Then use this editor guide to build the rule, configure its [dependencies](/docs/understanding-dependencies), and verify its output in [Investigations](/docs/investigations-overview). To change the customer experience, connect the result through [Apply decisions in your application](/docs/decisioning-implementation). 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 ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%2012.31.06%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=M7Aqd7Ob8cm9CMF28sWvlibw1P59%2BnOGmefKpFAwl30%3D) Click on the "**add a new file**" icon inside the file explorer on the right-hand menu: ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/image-1657609592312.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=H%2FrnQ6iP18uQECOiQ1A5y3Sg49w1tIownTU8BQZQ3Ck%3D) 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. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/image-1657609568615.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=Kgoi9%2FdItvJITr0ljB5hOUaRdREQ%2BF50IAyO9N2jckI%3D) 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. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%2010.09.28%E2%80%AFAM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=7drMDN1qhdH2xi0xNjd1ukXz67hSu6DQaQzO9QT%2F1QU%3D) - **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](https://darwinium.document360.io/v1/docs/proxy-actions) article for more information. Use the **Add Rule** button located on the top-right to add new rule: ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%2010.04.49%E2%80%AFAM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=0WIzZRsNX7Ya12bVUAopbAPdn83vOr9zsTqCz5Dif6A%3D) A new window will appear, allowing you to set the parameters for your rule. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%2010.07.53%E2%80%AFAM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=ntwa2OtZKMwHZnZ5Yb75ozDZm6zTa6iiJuMWZbzGU%2BA%3D) 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](https://darwinium.document360.io/v1/docs/rule-and-model-scoring) 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: - **Signal Generation** – A Signal is emitted using the configured Rule *Name* and *Category*. - **Score Contribution** – The configured Score (if provided) is applied and contributes to the overall decision score. - **Condition Reference** – The Condition itself is assigned the configured *Condition Name*, which can be referenced locally within the Rules file. | | **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". ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%2010.50.44%E2%80%AFAM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=rtWaCgccfekU3KR8Wk24Lh0wdkkAtiKcx4LPmtoPuoY%3D) | | **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](https://docs.darwinium.com/docs/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. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%204.49.51%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=%2FcCZTPd%2BwwZlesaZufMQJvp4hKFBs13%2Bhy6Mbk6bPnM%3D) ImportantLike all string data, Signal names are case sensitive. When testing for and publishing signals make sure the case is consistent. How To: Test if a Signal has been setTo test if a Signal has been set by a model, use the **has** function as follows: ```none has(outcome['CHAMPION'].models.signals, 'MY SIGNAL NAME') ``` How To: Test if a Signal has not been setTo test if a Signal has **not** been set,  use the negation operator **not** in combination with the has function as follows: ```none 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. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%203.30.57%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=ltpAdr%2FkV%2FfNycsD8HIpT%2BwiBbBYPEjvt9sVz5215Ho%3D) The **“Remove Attribute”** feature clears the selected attribute by setting its value to `null` whenever the rule is triggered. ### ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%203.48.41%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=4tcgLeVKtGKMPGv7oSKCTwEwg07U%2BM0jRVbPQtvcgVc%3D) 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](https://docs.darwinium.com/docs/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 ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%205.32.38%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=xjQY6%2BJ7tqrsWIQrjaZDJliUAm%2FISyXl1f9EAQGXysk%3D) Select a category and a label from the dropdown menu and click **Save**. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%205.34.43%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=cr%2Fw04D10V0BP%2FcI5d9C1lwBVzFION%2Bbd3OPI2yRu0s%3D) ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-09-18%20at%205.34.55%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=SSOTKwazQWi7P95nhuypqD5C5lWXXyc5MuTDvmJwDwE%3D) --- ### ### 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**. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%201.53.42%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=WbVxKq%2FVAGPawUkk7lRmwTj%2BIUWRHP5xnSaDvkbKBMM%3D) 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. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%202.10.58%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=xF6sobb%2FRcIPvQm8ptNQkUTl%2FiQkj1N5zViwn2wDlQo%3D) --- ### ### 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: ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%201.00.05%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=iI6I0gslBfbxgEfwP%2BH3xswxPNPTt4%2ByJX1WTza7LV4%3D)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`. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%201.00.28%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=YAtoyLV2XxBR6IzN3SHBWpdM4Fz25247ZikLZk9SvbE%3D) 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. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%201.40.27%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=PZnmUDaIrxGHNFuoN%2FZtWtHImMI8394jTXh64uv1KhY%3D) ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%201.41.50%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=DqUVlkOZ%2FhqdI2%2FfC4bjwYGq1md%2BPZ2MBwMgUebZ3XA%3D) --- ### 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. ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%202.17.24%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=wgp8EypgON%2FZxphe5hNRll4Td7HYpEwt8Z40%2FYYZDTQ%3D) Select "**Text Editor Default**" from the new drop-down. This will switch to the **YAML** view ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%202.17.32%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=QOTJmGq4e60KfEzme1VVnuiMEyJ4B7YaeOkbMnFjhzk%3D) ![](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202025-11-21%20at%202.17.43%E2%80%AFPM.png?sv=2026-02-06&spr=https&st=2026-11-22T23%3A46%3A49Z&se=2026-11-23T00%3A46%3A49Z&sr=b&sp=r&sig=L7EPOmGbWfe%2F9HrNhTfoAQAzNiPhP%2FdPIuQP0SlW%2F5E%3D) Repeat the steps but this time select "**Darwinium Rules Active**" to switch views. IMPORTANT Like all string data, Signal names are case sensitive. When testing for and publishing signals, make sure the case is consistent.