Manual Rule Creation

Overview

While AI-generated rules are convenient, some scenarios require precise manual configuration. The JSON rule editor provides full control over rule definitions, allowing you to specify exact conditions, actions, and metadata.

Manual rule creation is recommended when you need:

• Complex multi-condition rules
• Custom action configurations
• Specific compliance annotations
• Integration with external systems

Key Features

• Full Schema Access: Configure every rule attribute
• Condition Expressions: Write precise evaluation logic
• Action Customization: Define exact response behaviors
• Validation: Real-time schema validation prevents errors
• Import/Export: Bulk manage rules via JSON files
• Version Control: Track rule changes over time

How It Works

Rule Lifecycle

Create/Edit Rule
       |
       v
+----------------+
| Schema         |
| Validation     |
+----------------+
       |
       v
+----------------+
| Database       |
| Persistence    |
+----------------+
       |
       v
+----------------+
| Active Rule    |
| Engine         |
+----------------+
       |
       v
  Evaluating Actions

Rule Schema Reference

Complete Schema

{
  "id": "integer (auto-generated)",
  "agent_id": "string | '*'",
  "action_type": "string",
  "description": "string",
  "condition": "string (expression)",
  "action": "string",
  "risk_level": "string (low|medium|high|critical)",
  "recommendation": "string",
  "justification": "string",
  "name": "string",
  "rule_type": "string",
  "conditions": "object (advanced)",
  "actions": "object (advanced)",
  "priority": "integer (0-100)",
  "enabled": "boolean",
  "created_at": "datetime (auto)",
  "organization_id": "integer (auto)"
}

Field Definitions

Field	Type	Required	Description
agent_id	string	Yes	Target agent or * for all agents
action_type	string	Yes	Action type to match (e.g., file_access)
description	string	Yes	Human-readable rule description
condition	string	Yes	Evaluation expression
action	string	Yes	Action to execute on match
risk_level	string	No	low, medium, high, critical
recommendation	string	No	Guidance for approvers
justification	string	No	Reason for the rule
name	string	No	Short rule name
priority	integer	No	Evaluation order (higher first)
enabled	boolean	No	Active status (default: true)

Condition Expression Syntax

Conditions use a simple expression language:

<field> <operator> <value> [AND|OR <expression>]

Operators:

• == - Equals
• != - Not equals
• >, <, >=, <= - Numeric comparison
• CONTAINS - String contains
• IN - Value in list
• MATCHES - Regex match

Examples:

# Simple condition
action_type == 'file_delete'

# Multiple conditions
action_type == 'database_write' AND risk_score > 70

# Agent-specific
agent_id == 'code-assistant' AND action_type == 'system_command'

# List matching
action_type IN ['file_delete', 'file_write', 'file_modify']

# Pattern matching
target MATCHES '^/etc/.*'

Action Types

Action	Description	Use Case
auto_approve	Automatically approve	Low-risk operations
require_approval	Queue for manual approval	Medium-risk operations
auto_block	Immediately block	Critical security threats
flag_high_risk	Flag and notify	High-risk monitoring
monitor	Log without blocking	Audit and observation
escalate	Send to security team	Anomaly detection
security_assessment	Trigger risk analysis	Complex scenarios

Configuration

Create Rule via API

curl -X POST "https://api.ascend.ai/api/smart-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "data-pipeline",
    "action_type": "database_write",
    "description": "Require approval for bulk database writes from data pipeline",
    "condition": "agent_id == '\''data-pipeline'\'' AND action_type == '\''database_write'\'' AND record_count > 1000",
    "action": "require_approval",
    "risk_level": "high",
    "recommendation": "Review data volume and target tables before approval",
    "priority": 50,
    "enabled": true
  }'

Update Existing Rule

curl -X PUT "https://api.ascend.ai/api/smart-rules/15" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "description": "DEPRECATED: Replaced by rule 42"
  }'

Bulk Import Rules

curl -X POST "https://api.ascend.ai/api/smart-rules/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "agent_id": "*",
        "action_type": "privilege_escalation",
        "condition": "action_type == '\''privilege_escalation'\''",
        "action": "auto_block",
        "risk_level": "critical"
      },
      {
        "agent_id": "*",
        "action_type": "network_scan",
        "condition": "action_type == '\''network_scan'\''",
        "action": "require_approval",
        "risk_level": "high"
      }
    ]
  }'

Usage Examples

Example 1: Block File Deletions in Production

{
  "name": "Block Prod File Deletions",
  "agent_id": "*",
  "action_type": "file_delete",
  "description": "Block all file deletion attempts in production environment",
  "condition": "action_type == 'file_delete' AND environment == 'production'",
  "action": "auto_block",
  "risk_level": "critical",
  "recommendation": "File deletions in production require change management approval",
  "priority": 100,
  "enabled": true
}

Example 2: Require Approval for External API Calls

{
  "name": "External API Approval",
  "agent_id": "*",
  "action_type": "api_call",
  "description": "Require approval for API calls to external domains",
  "condition": "action_type == 'api_call' AND target NOT CONTAINS 'internal.company.com'",
  "action": "require_approval",
  "risk_level": "medium",
  "recommendation": "Verify external API is on approved vendor list",
  "priority": 75,
  "enabled": true
}

Example 3: Monitor Specific Agent

{
  "name": "Monitor Analytics Bot",
  "agent_id": "analytics-bot",
  "action_type": "data_access",
  "description": "Log all data access from analytics bot for compliance",
  "condition": "agent_id == 'analytics-bot' AND action_type == 'data_access'",
  "action": "monitor",
  "risk_level": "low",
  "justification": "GDPR compliance requires tracking all PII access",
  "priority": 25,
  "enabled": true
}

Validation

Schema Validation

Rules are validated against the schema before saving:

1. Required Fields: agent_id, action_type, condition, action must be present
2. Type Validation: Fields must match expected types
3. Enum Validation: risk_level must be valid value
4. Expression Validation: condition must be parseable

Common Validation Errors

Error	Cause	Fix
Missing required field	Required field omitted	Add the field
Invalid risk_level	Unknown risk level	Use low, medium, high, or critical
Condition parse error	Invalid expression syntax	Check operator and value formatting
Duplicate rule	Rule with same conditions exists	Update existing rule or use unique condition

Best Practices

1. Use Descriptive Names: Make rules easy to identify
2. Set Appropriate Priority: Higher priority rules evaluated first
3. Include Recommendations: Help approvers make informed decisions
4. Add Justifications: Document why the rule exists
5. Test Before Enabling: Create rules as disabled, test, then enable
6. Use Version Control: Export rules and track changes in Git

Related

• Smart Rules Overview - Understanding smart rules
• AI Rule Generation - Generate rules from descriptions
• Rule Analytics - Track rule performance
• API Reference - Full API documentation