Risk rules & customization

tirreno is designed to be customized for your specific security needs. No CLA or pull request is required for local modifications.

The two main customization points are:

1. Custom rules Create detection rules based on user behavior
2. Suspicious pattern lists Adjust URL, user agent, and email pattern detection

Rule presets

tirreno includes pre-configured rule sets for common security scenarios. Presets provide a quick starting point—select one from the Rules page dropdown and click Apply.

Each preset assigns weights to specific rules. You can customize the weights after applying a preset.

Rule weights:

Rule organization

Rules are organized by namespace (core vs custom) and category (prefix letter).

Namespaces:

Rule categories by prefix:

Custom rules must use the X prefix (e.g., X01.php, X02.php). Core rule prefixes (A–R) are reserved.

Built-in rules

tirreno includes standard detection rules organized by category:

Account takeover (A01-A08)

Behaviour (B01-B26)

Country (C01-C16)

Device (D01-D10)

Email (E01-E30)

Note: E18 is reserved for future use.

IP (I01-I12)

Phone (P01-P04)

Reuse/blacklist (R01-R03)

Developing custom rules

Custom rules are placed in assets/rules/custom/ with filenames X01.php, X02.php, etc.

Each rule must:

• Use namespace Tirreno\Rules\Custom
• Extend \Tirreno\Assets\Rule
• Define constants: NAME, DESCRIPTION, ATTRIBUTES
• Implement defineCondition() method

Example rule

See assets/rules/custom/X03.example.php for a complete example:

<?php

namespace Tirreno\Rules\Custom;

class X03 extends \Tirreno\Assets\Rule {
    public const NAME = '1xx user name';
    public const DESCRIPTION = 'Username starts with digit 1.';
    public const ATTRIBUTES = [];

    protected function defineCondition() {
        return $this->rb->logicalAnd(
            $this->rb['extra_one_digit_userid']->equalTo(true),
        );
    }
}

Custom context

For rules that need custom data, create a Context class in assets/rules/custom/Context.php. See Context.example.php:

<?php

declare(strict_types=1);

namespace Tirreno\Rules\Custom;

class Context extends \Tirreno\Assets\Context {
    protected $DB_TABLE_NAME = 'event_account';
    protected $uniqueValues = false;

    public function expandContext(array &$extraData, array &$user): void {
        // Add custom attributes to $user array
        $user['extra_one_digit_userid'] = substr(($extraData['extra_userid'][0][0] ?? ' '), 0, 1) === '1';
    }

    protected function getDetails(array $accountIds, int $apiKey): array {
        [$params, $placeHolders] = $this->getRequestParams($accountIds, $apiKey);

        $query = (
            "SELECT
                event_account.id      AS id,
                event_account.userid  AS extra_userid
            FROM event_account
            WHERE event_account.id IN ({$placeHolders})
              AND event_account.key = :api_key"
        );

        return $this->execQuery($query, $params);
    }
}

Testing rules

1. Refresh rules: After creating or modifying rules, go to the Rules page and click Refresh at the bottom of the page to apply your changes
2. Test a rule: Select a rule and click the Play button (▷) to see how many users are triggered by the rule
3. Match rate: The percentage shown indicates how many users from 1000 match the rule (e.g., "22%" means 22% of 1000 users trigger this rule)

Ruler operators reference

The rules engine uses ruler/ruler for condition evaluation. Available operators in defineCondition():

Logical operators:

// AND - all conditions must be true
$this->rb->logicalAnd(
    $this->rb['eip_tor']->equalTo(true),
    $this->rb['ea_days_since_account_creation']->lessThan(7)
);

// OR - at least one condition must be true
$this->rb->logicalOr(
    $this->rb['eip_vpn']->equalTo(true),
    $this->rb['eip_tor']->equalTo(true)
);

// NOT - negate a condition
$this->rb->logicalNot(
    $this->rb['le_has_no_data_breaches']->equalTo(true)
);

Rule context attributes

When writing custom rules, the following attributes are available in the defineCondition() method. Access them via $this->rb['attribute_name'].

Event attributes (event_)

From Event context:

Derived event attributes:

Account attributes (ea_)

Raw account data from User context:

Derived account attributes:

IP attributes (eip_)

From Ip context:

Device attributes (eup_)

From Device context:

Derived device attributes:

Session attributes (event_session_)

From Session context:

Email attributes (Platform Edition only)

Last Email Attributes (le_):

Derived last email attributes:

Email Attributes (ee_):

Domain attributes (Platform Edition only)

Last Domain Attributes (ld_):

Derived last domain attributes:

Phone attributes (Platform Edition only)

From Phone context (ep_):

Last phone from User context (lp_):

Derived phone attributes:

Suspicious pattern lists

tirreno maintains lists of suspicious patterns in assets/lists/:

Each file returns a PHP array:

<?php
return [
    '.env',
    '.git',
    '/wp-admin',
    'phpmyadmin',
    '<script>',
    // ...
];

To add patterns:

1. Open the appropriate file in assets/lists/
2. Add your pattern string to the array
3. Patterns are case-sensitive substring matches

Example patterns by type: