Decisioning Guide

At its core, Darwinium decisioning answers a fundamental question: "Should we allow, challenge, or reject this event?"

Decisioning Components

1. Features: Real-time variables that provide context by analyzing historical behavior. Defined in <name>.feature.yaml files Features Overview
2. Rules: Binary conditions that generate signals when specific risk patterns are detected. Defined in <name>.rules files Rules and Signals
3. Decision Strategy: The final arbiter that determines the ultimate disposition. Defined in <name>.strategy files. Can only be one per step. Decision Strategy

The decisioning components are added to Workflows of Steps within Darwinium journey.

Key Architectural Principles

• Event-Driven: Every decision is made in the context of a specific event with full historical context
• Parallel Execution: All features and rules run simultaneously for maximum performance
• Centralized Decision: The strategy.yaml file acts as the "CEO," making the final call
• Git-Based Workflow: All policy changes are version-controlled and deployed through Git

1. Features: The Memory of the System

Features Overview

Features, defined in *.feature.yaml files, are numeric values computed from historical event data that provide real-time context about user behavior. They answer questions like:

• "How many times has this device logged in during the past hour?"
• "How many unique devices has this account used in the past 30 days?"
• "How long has it been since this IP address was first seen?"

Example Feature Types

Example: Different emails used to log in to from this device

# File: example.feature.yaml
features:
  - name: count_emails_for_dvcid_90days
    default_value: -1
    with_scope: same_node_instance
    time_window:
      days: 90
    starting: immediately
    find_the:
      distinct_count_of:
        attributes:
          - identity['ACCOUNT'].email['PERSONAL'].email
        for_events:
          event_type:
            - account_login_success
          include_current_event: true
          with_the_same:
            - profiling.device.identifier

2. Rules: The Pattern Detectors

Rules and Signals

Rules, defined in *.rules files, are binary (yes/no) conditions that generate signals when specific risk patterns are detected. They use features, apply conditions to profiling data, and threshold model score outputs to classify suspicious behavior.

Rule Components

Referencing Features in Rules

Features can be referenced in rules using either of these syntax:

outcome[CHAMPION].features.general['myfeaturename']

feature('myfeaturename')

Example:

# File: example.rules
rules:
  - type: condition
    signal: MULTIPLE_EMAIL_SAME_DEVICE  
    condition: feature('count_emails_for_dvcid_90days') >= 2
    category: ACCOUNT_TAKEOVER_RISK
    score: -250

3. Decision Strategy: The Final Say

The *.strategy file is a special rule set that runs last and determines the final disposition of an event. It has access to all features, signals, categories, and scores generated by other Workflows. The output from the strategy is found in attribute group outcome[CHAMPION].decision_strategy.*. In particular outcome[CHAMPION].decision_strategy.result

Critical Behaviors:

• Terminate Flag: When enabled, this sets the final result / disposition and stops further evaluation.
• Priority Matters: The order of terminate rules defines your decision hierarchy
• Incidents: Incidents can be raised within the strategy

Example

# example.strategy.yaml
version: 2
checksum: 4+1DEFAULTuuoYfxCbTkCA==
decision_type: decisionOutcome
rules:
  - type: condition
    condition: has(outcome[CHAMPION].models.signal_categories, 'REJECT')
    signal: REJECT_RULE
    remediations:
      - type: terminate
        disposition: reject
  - type: condition
    condition: has(outcome[CHAMPION].models.signal_categories, 'CHALLENGE')
    signal: CHALLENGE_RULE
    remediations:
      - type: terminate
        disposition: challenge
  - type: condition
    condition: 'True'
    signal: DEFAULT
    comment: Default allow rule. Always true
    remediations:
      - type: terminate
        disposition: pass

Available Result

Git-Based Workflow

All policy changes follow a Git-based deployment workflow to ensure version control, collaboration, and safe deployments. Git is an industry standard for version control and change management.

Deployment Process Steps

1. Pull: Synchronize your local repository with the remote main branch
2. Edit: Modify policy files in the Workflows pane
3. Stage: Select which changes you want to include in your next commit
4. Commit: Save changes locally with a descriptive message
5. Sync (Push): Push changes to the remote repository
6. Build: Automatic compilation and deployment triggers
7. Deploy: Pushes (makes live) the compiled step & decisioning configuration to the target
   

Prevention Tools

• Rule Editor v2: Prevents saving rules with invalid syntax
• Terminal Command: Run dwn_journey_checker before committing to validate syntax
• Deployments Log: Check for detailed error messages and file paths when builds fail

Investigations

The Investigations tab provides a complete view of how Darwinium processed an event:

Investigations

• Features Evaluated: All custom features and their computed values
• Features Darwinium: System-generated features from profiling
• Signals and Scores: Which rules fired, their individual scores, and categories
• Final Disposition: The ultimate decision made by the strategy
• Full Event Context: All data available at decision time

Best Practices

Feature Design

• Specify a time window
• Useful to set default values to -1 to distinguish from legitimate zero counts
• Try to primarily filter by event_type for fastest execution, rather than a condition
• At least one identifier must be specified in a with_the_same pivot. Use approximate features when the attribute is not an identifier.

Rule Design

• Use categories to group similar rules
• Provide meaningful rule names that describe the risk
• Include score values that reflect risk severity
• Use automated actions (eg. add labels, attributes) to avoid manual effort

Deployment Workflow

• Always pull before editing, to avoid needing to resolve merge conflicts later
• Write descriptive commit messages
• (optional) Run dwn_journey_checker before committing
• Monitor the Deployments log after pushing

Glossary