Rules System

MyDeskBot's Rules System provides powerful control mechanisms to guide, constrain, and customize AI agent behavior. Rules act as guardrails that ensure agents operate within defined parameters.

🎯 Overview

What are Rules?

Rules are declarative statements that define how AI agents should behave, what they can and cannot do, and how they should respond to specific situations. Think of rules as policies or guidelines for your AI assistants.

Why Rules?

• Safety & Security: Prevent agents from performing dangerous operations
• Compliance: Ensure agents follow organizational policies and regulations
• Consistency: Maintain consistent behavior across different sessions
• Customization: Tailor agent behavior to your specific needs
• Auditability: Track and review agent decisions

📋 Rule Types

1. Security Rules

Restrict access to sensitive operations and data.

rule: security_file_access
type: security
description: "Prevent access to sensitive directories"
condition: "path matches /etc/, ~/.ssh/, /var/secrets/"
action: "deny"
message: "Access to sensitive directory is not allowed"

2. Permission Rules

Control what operations agents can perform.

rule: permission_ssh_execution
type: permission
description: "Require confirmation before SSH command execution"
condition: "operation == 'ssh_execute'"
action: "require_confirmation"

3. Format Rules

Enforce specific output formats.

rule: format_json_response
type: format
description: "Always return JSON for API responses"
condition: "context == 'api_call'"
action: "format_as_json"

4. Context Rules

Activate or deactivate behaviors based on context.

rule: context_development_mode
type: context
description: "Enable detailed logging in development mode"
condition: "environment == 'development'"
action: "set_log_level", "debug"

5. Compliance Rules

Ensure regulatory compliance.

rule: compliance_data_handling
type: compliance
description: "Redact personal information in logs"
condition: "contains_personal_data"
action: "redact", "name, email, phone, ssn"

🚀 Getting Started

Creating a Rule

Rules can be created in multiple ways:

Via UI (Desktop App)

1. Navigate to Settings → Rules
2. Click Create New Rule
3. Fill in rule details:
   • Name and description
   • Rule type
   • Condition expression
   • Action to take
4. Save and activate the rule

Via Configuration File

Create a .rules.yaml or .rules.json file:

rules:
  - name: no_file_deletion
    type: security
    condition: "operation == 'delete_file'"
    action: deny
    message: "File deletion is not allowed"

  - name: require_ssh_confirm
    type: permission
    condition: "operation == 'ssh_command'"
    action: require_confirmation

Via CLI

mydeskbot rules create --name "no_file_deletion" \
  --type security \
  --condition "operation == 'delete_file'" \
  --action deny \
  --message "File deletion is not allowed"

🔧 Rule Syntax

Conditions

Conditions use a simple expression language:

# String matching
condition: "operation == 'read_file'"

# Pattern matching
condition: "path matches '*.log'"

# Multiple conditions
condition: "operation == 'write_file' && size > 1024"

# Boolean logic
condition: "(operation == 'ssh' || operation == 'sftp') && !approved"

# Range checking
condition: "severity in ['critical', 'high']"

# Function calls
condition: "has_permission('admin')"

# Nested conditions
condition: "(type == 'database' && operation == 'drop') || (type == 'file' && path matches '/etc/')"

Actions

Available actions by rule type:

Rule Type	Available Actions
security	deny, allow, quarantine, notify_admin
permission	allow, deny, require_confirmation, require_escalation
format	format_as_json, format_as_markdown, format_as_xml
context	set_variable, set_log_level, enable_feature
compliance	redact, encrypt, log_audit, require_approval

🎛️ Advanced Features

Rule Priority

Rules are evaluated in priority order. Lower priority numbers are evaluated first.

rules:
  - name: global_allow_all
    priority: 100
    action: allow

  - name: block_sensitive
    priority: 10
    condition: "is_sensitive"
    action: deny

Rule Groups

Organize related rules into groups:

groups:
  security:
    description: "Security-related rules"
    rules:
      - name: no_sensitive_access
      - name: require_auth

  development:
    description: "Development environment rules"
    rules:
      - name: allow_debug_tools
      - name: verbose_logging

Conditional Activation

Rules can be conditionally activated:

rule: strict_mode
condition: "user.role == 'admin'"
type: context
action: enable_strict_mode

rule: relaxed_mode
condition: "user.role == 'guest'"
type: context
action: enable_relaxed_mode

Rule Variables

Use variables in rules for dynamic behavior:

variables:
  max_file_size: 10485760  # 10MB
  sensitive_paths: ["/etc", "/var/secrets", ".ssh"]

rule: check_file_size
condition: "operation == 'write_file' && size > ${max_file_size}"
action: deny
message: "File size exceeds maximum allowed (${max_file_size} bytes)"

rule: block_sensitive_paths
condition: "operation == 'read_file' && path in ${sensitive_paths}"
action: deny

🔍 Rule Evaluation Flow

┌─────────────┐
│ Agent Action│
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Load Rules │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Sort by     │
│ Priority    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Evaluate   │
│ Conditions │◄───┐
└──────┬──────┘    │
       │           │
       ▼           │
   ┌───────┐       │
   │ Match?│       │
   └───┬───┘       │
       │           │
   ┌───┴───┐       │
   │       │       │
  Yes      No      │
   │       │       │
   ▼       │       │
┌───────┐   │       │
│Execute │   │       │
│Action  │   │       │
└───┬───┘   │       │
    │       │       │
    ▼       │       │
┌───────┐   │       │
│Continue│   │       │
│ / Stop │   │       │
└───┬───┘   │       │
    │       │       │
    └───────┴───────┘
            │
            ▼
    ┌───────────┐
    │Next Rule? │
    └─────┬─────┘
          │
         Yes│   No
          │   │
          └───┴────► Complete

🛠️ Best Practices

Security Rules

# ✅ Good: Specific and clear
rule: block_sensitive_directories
condition: "path matches '/etc/|~/.ssh/|/var/secrets/'"
action: deny
message: "Access to sensitive directory is not allowed"

# ❌ Bad: Too broad
rule: block_files
condition: "operation == 'read_file'"
action: deny

Performance

• Order Rules by Match Frequency: Put frequently matched rules first
• Use Specific Conditions: Avoid overly broad conditions that match everything
• Cache Results: Cache rule evaluation for repeated operations
• Avoid Regex in Hot Paths: Pre-compile regex patterns where possible

Maintainability

# ✅ Good: Named groups and clear descriptions
groups:
  security:
    description: "Prevent unauthorized access to sensitive resources"
    rules:
      - name: block_sensitive_paths
      - name: require_auth_for_write

# ❌ Bad: Unclear organization
rules:
  - rule1
  - rule2
  - rule3

🐛 Troubleshooting

Rules Not Applying

Problem: Rule is defined but not being applied

Solutions:

1. Check rule priority - ensure it's not being overridden
2. Verify condition syntax - use the rule tester to debug
3. Check rule is activated (not disabled)
4. Review rule logs for evaluation errors

Conflicting Rules

Problem: Multiple rules with conflicting actions

Solutions:

1. Review and adjust rule priorities
2. Use rule groups to isolate conflicts
3. Add more specific conditions to reduce overlap
4. Use the conflict resolution tool

Performance Issues

Problem: Many rules causing slow performance

Solutions:

1. Merge similar rules into a single rule
2. Optimize condition expressions
3. Disable unused rules
4. Use rule caching

📊 Rule Analytics

MyDeskBot provides analytics on rule usage:

Viewing Rule Metrics

mydeskbot rules analytics --period "7d"

Output:

Rule                          Hits    Denies   Avg Time
─────────────────────────────────────────────────────
block_sensitive_paths        1,234   45       2.3ms
require_ssh_confirm           567     12       1.8ms
format_json_response          8,901   0        0.5ms

🔗 Related Topics

• Agent Skills - How rules interact with skills
• MCP Tools - Controlling MCP tool access with rules
• Prompts - Rules for prompt handling