Skip to content

LOT Language - Rule Management Documentation

"You can do a LOT"

1. Overview

This document provides guidance on using LOT language rules within Coreflux, focusing on creating, managing, and understanding rules that govern user permissions and system actions. Rules in Coreflux can be added, removed, or modified to ensure precise control over system operations.

2. Rules Mechanism

2.1 Rule Processing Overview

Rules are processed after authentication and mTLS (mutual TLS), if both are enabled. These rules serve as decision points, determining user permissions for actions, visibility, and interactions with the broker.

The elements controlled by rules include MQTT topics, MQTT $SYS topics, MQTT users, user properties, rule priorities, and operations.

2.2 User Properties

The user properties that can be used in the LOT language include:

  • AllowedSystemConfiguration
  • AllowedAssetManipulation
  • AllowedUserManagement
  • AllowedLogManagement

Additional properties can be added for a user using the -changeUserSettings command by specifying a property that does not currently exist.

2.3 Operations

The following is the list of operations that rules manage:

  • Subscribe: Triggered when a specific topic is subscribed.
  • SubscribeSys: Triggered when a specific topic under $SYS is subscribed.
  • Publish: Triggered when a message is published to a specific topic.
  • PublishSys: Triggered when a message is published to a topic under $SYS.
  • UserManagementCreation: Triggered when the addUser command is called (either in the Hub or the broker itself).
  • UserManagementPasswordChange: Triggered by the changeUserPassword command.
  • UserManagementUpdate: Triggered by the changeUserSettings command.
  • UserManagementRemove: Triggered by the removeUser command.
  • AssetManagementCreation: Triggered by the I command for installing assets.
  • AssetManagementUpdate: Triggered by the assetConfigSave command.
  • AssetManagementRemove: Triggered by the asset uninstall -U command.
  • AssetManagementStart: Triggered by the run asset -R command.
  • AssetManagementStop: Triggered by the stop asset -S command.
  • AssetManagementPolicySet: Triggered by the assetPolicySet command.
  • AssetManagementNameSet: Triggered by the assetNameSet command.
  • SystemConfiguration: Triggered when changing the configuration under the topic $SYS/Coreflux/Config/New.
  • CommandCall: Blocks the user from sending commands without appropriate permissions. Without this, the user cannot send commands to $SYS/Coreflux/Command (initial trigger since other operations depend on it).
  • RuleManagementCreation: Enables the creation of rules, allowing the user to execute the addRule command.
  • RuleManagementRemove: Enables the removal of rules, allowing the user to execute the removeRule command.
  • ModelManagementCreation: Enables the creation of models, allowing the user to execute the addModel command.
  • ModelManagementRemove: Enables the removal of models, allowing the user to execute the removeModel command.

2.4 Topics Controlled by Rules

Rules can control specific topics or use wildcards to extend their coverage. If a topic is specified directly, like Test/Topic, the rule will only apply to that single topic. If the wildcard # is used, such as Test/Topic/#, the rule will apply to all topics under the base Test/Topic. The wildcard +, often used in unified namespaces, such as Test/+/Topic/#, will cover a wide range of topics, like Test/Machine1/Topic/Xpto or Test/Machine2/Topic/Xpto3. The $SYS topics are handled by PublishSys or SubscribeSys operations, as they require special safety considerations.

2.5 Priority

Each rule acts as an ALLOW or DENY process. When an operation is triggered, a list of all rules associated with that specific operation is created. These rules are processed in order of their priority. Rules with a lower priority value (e.g., Priority 1) take precedence over rules with higher priority values (e.g., Priority 2). Therefore, if a rule with priority 2 defines DENY, but a rule with priority 1 defines ALLOW, then the final result will be ALLOW.

Handling priority is crucial to ensure that critical permissions are enforced correctly. By assigning the correct priority levels, you can ensure that high-importance rules override lower-priority ones, reducing the risk of accidental permission conflicts or security breaches. It helps maintain a predictable and consistent system behavior, especially in complex scenarios where multiple rules may apply to a single action.

3. Default Rules

Coreflux comes with a set of default rules preconfigured to cover standard operations such as user management, asset management, system configuration, and more. These rules ensure that the system is functional out of the box and provide the base security configuration.

Below are examples of some default rules:

4. Rule Syntax

Rules in the LOT language follow a specific syntax. Each rule defines a condition for allowing or denying actions performed by users in the system.

4.1 Syntax of DEFINE RULE

The general syntax for defining a rule is:

DEFINE RULE <rule_name> WITH PRIORITY <priority_value> FOR <action_scope>
    IF <condition> THEN
        ALLOW
    ELSE
        DENY

4.2 Components Explained

4.2.1 DEFINE RULE <rule_name>

Defines a new rule with a unique <rule_name>. This name must be unique across the system.

4.2.2 WITH PRIORITY <priority_value>

Specifies the priority of the rule. The lower the number, the higher the priority. For example, a rule with a priority of 1 will take precedence over a rule with a priority of 5 if both are applicable.

4.2.3 FOR <operation_scope>

Indicates the scope of the operations that the rule governs. This could be operations such as UserManagementCreation, AssetManagementRemove, or PublishSys. It defines the specific command or action within the system to which the rule will apply.

4.2.4 IF **** THEN ALLOW / DENY

The IF statement specifies the condition under which the rule applies. If the condition evaluates to true, then the action is allowed (ALLOW). Otherwise, the action is denied (DENY). The ALLOW or DENY component is essential in every rule; if it is missing, the rule will always result in a denial. If no rules explicitly allow an action, it is denied by default.

4.3 Example Rule Explained

Consider the following rule:

DEFINE RULE AllowUserCreation WITH PRIORITY 1 FOR UserManagementCreation
    IF USER HAS AllowedUserManagement OR USER HAS AllowedSystemConfiguration OR USER IS "root" THEN
        ALLOW
    ELSE
        DENY
  • DEFINE RULE AllowUserCreation: This is the name of the rule, which aims to govern the creation of new users.
  • WITH PRIORITY 1: This rule has the highest priority (1), which means it will be evaluated before other rules with lower priorities.
  • FOR UserManagementCreation: The action scope is user creation.
  • IF USER HAS AllowedUserManagement OR USER HAS AllowedSystemConfiguration OR USER IS "root": The condition under which the action will be allowed. Here, the action is allowed if the user has the AllowedUserManagement or AllowedSystemConfiguration permissions, or if the user is the system administrator (root).
  • ALLOW: If the condition is true, the action is permitted.
  • ELSE DENY: If the condition is false, the action is denied.

5. Default Behavior

In Coreflux, every action is DENY by default if no rule explicitly allows it. The ALLOW or DENY outcome must be specified in the rule. This ensures that if a condition is not met, or if no rule is provided for a specific action, the system denies the action, thereby enforcing security.

6. Rule Management Guidelines

There is a default rule in Coreflux that manages the addition and removal of rules, which enables the use of command topics to manage rules. This default rule allows users to use the command topic $SYS/Coreflux/Command to add or remove rules.

6.1 Add a Rule: addRule <DEFINE RULE code>

This command allows you to add a new rule to the system. Example:

-addRule DEFINE RULE AllowUserCreation WITH PRIORITY 1 FOR UserManagementCreation
    IF USER HAS AllowedUserManagement OR USER HAS AllowedSystemConfiguration OR USER IS "root" THEN
        ALLOW
    ELSE
        DENY

In this example, the rule named AllowUserCreation is added to the system. It allows users to create new user accounts if they have the AllowedUserManagement or AllowedSystemConfiguration permissions, or if they are the system administrator (root). The rule is assigned a priority of 1, meaning it will take precedence over other rules with lower priorities.

Another example:

-addRule DEFINE RULE AllowAssetInstall WITH PRIORITY 2 FOR AssetManagementCreation
    IF USER HAS AllowedAssetManipulation THEN
        ALLOW
    ELSE
        DENY

In this example, the rule named AllowAssetInstall is added to the system. It allows users to install new assets if they have the AllowedAssetManipulation permission. The rule is assigned a priority of 2, meaning it will be evaluated after rules with a priority of 1.

6.2 Remove a Rule: removeRule <rule name in the DEFINE RULE>

This command allows you to remove an existing rule by specifying its name. Example:

-removeRule AllowUserCreation

In this example, the rule named AllowUserCreation is removed from the system. Removing a rule means that any permissions or restrictions defined by that rule will no longer be enforced.

Another example:

-removeRule AllowAssetInstall

In this example, the rule named AllowAssetInstall is removed from the system. This action revokes the permissions previously granted by the rule.

7. Additional Examples

Below are additional examples of rules to provide more clarity on how to use the LOT language effectively:

7.1 Direct and Single Approach

DEFINE RULE SpecificTopicClient WITH PRIORITY 1 FOR Subscribe TO TOPIC "Emanuel/#"
    IF USER IS "Emanuel" THEN
        ALLOW
    ELSE
        DENY

DEFINE RULE SpecificTopicClient WITH PRIORITY 1 FOR Publish TO TOPIC "Emanuel/#"
    IF USER IS "Emanuel" THEN
        ALLOW
    ELSE
        DENY

The rules (Subscribe and Publish) allow the user with the username "Emanuel" to only subscribe or publish to topics under Emanuel/#. This means that the user "Emanuel" has exclusive access to subscribe and publish messages to all topics under the Emanuel namespace.

7.2 UNS / Domain Approach

DEFINE RULE SpecificUNSDevices WITH PRIORITY 1 FOR Subscribe TO TOPIC "Machines/+/#"
    IF USER IS "MachineUser" THEN
        ALLOW
    ELSE
        DENY

DEFINE RULE SpecificUNSDevices WITH PRIORITY 1 FOR Publish TO TOPIC "Machines/+/#"
    IF USER IS "MachineUser" THEN
        ALLOW
    ELSE
        DENY

The rules (Subscribe and Publish) allow the user with the username "MachineUser" to subscribe or publish to topics under Machines/+/#. This means that the "MachineUser" can access topics related to different machines, each with its own subtopic structure. However, the user cannot access any other topics outside the specified namespace (Machines/+/#), making this a domain-specific rule that limits the scope of the user's actions.

These rules enable the setup of either a direct, one-rule-per-client approach, or a more general, domain-specific approach that covers multiple devices or users. This flexibility allows administrators to tailor access control based on individual client needs or broader operational requirements.