Smart Rules Engine

Field	Value
Document ID	ASCEND-GOV-008
Version	2026.04
Last Updated	April 2026
Author	ASCEND Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 12 minutes | Skill Level: Intermediate

Overview

Smart Rules provide AI-powered security automation. Rules can be created manually, generated from natural language, or suggested by machine learning analysis.

Immediate Effect

Smart rules are evaluated in real time against every incoming action. Enabling a new rule immediately affects all agents in your organization -- use the test mode to validate rule behavior before activation.

Rule Structure

# Source: models.py
class SmartRule(Base):
    """Enterprise smart rule definition."""
    __tablename__ = "smart_rules"

    id = Column(Integer, primary_key=True)
    name = Column(String(255), nullable=False)
    condition = Column(Text, nullable=False)        # Logical expression
    action = Column(String(50), nullable=False)     # Response action
    risk_level = Column(String(20), nullable=False) # low/medium/high/critical
    description = Column(Text)
    recommendation = Column(Text)
    justification = Column(Text)
    organization_id = Column(Integer, nullable=False)  # Multi-tenant

Creating Rules

Manual Creation

curl -X POST "https://pilot.owkai.app/api/smart-rules" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value Transaction Alert",
    "condition": "action_type == '\''financial.transfer'\'' AND amount > 10000",
    "action": "require_approval",
    "risk_level": "high",
    "description": "Require approval for transactions over $10,000",
    "recommendation": "Verify transaction details with account holder"
  }'

Natural Language Generation

curl -X POST "https://pilot.owkai.app/api/smart-rules/generate-from-nl" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "natural_language": "Block any database deletions in production during business hours",
    "context": "enterprise_security"
  }'

Response:

{
  "id": 123,
  "name": "Production Database Delete Protection",
  "condition": "action_type == 'database.delete' AND environment == 'production' AND time_context == 'business_hours'",
  "action": "block_and_alert",
  "risk_level": "critical",
  "justification": "Prevents accidental or malicious data loss during active business operations",
  "enterprise_features": {
    "compliance_impact": "SOX, PCI-DSS data retention requirements",
    "business_impact": "High - protects production data integrity",
    "ai_confidence": 85
  }
}

Rule Actions

Action	Description	Use Case
alert	Create alert, allow action	Monitoring
block	Deny action	Hard block
block_and_alert	Deny and create alert	Security events
require_approval	Queue for human review	Sensitive actions
escalate	Route to security team	Critical issues
monitor	Log without blocking	Baseline collection
quarantine	Isolate for investigation	Suspicious behavior

Rule Conditions

Condition Syntax

# Source: routes/smart_rules_routes.py:905
# Conditions use Python-like syntax

# Simple conditions
"action_type == 'database.delete'"
"risk_score > 70"
"environment == 'production'"

# Compound conditions
"action_type == 'financial.transfer' AND amount > 10000"
"(environment == 'production' OR data_classification == 'pii') AND action_type LIKE 'write%'"

# List membership
"action_type IN ['database.delete', 'database.drop', 'database.truncate']"
"user_role NOT IN ['admin', 'security']"

# Pattern matching
"resource LIKE 'customer%'"
"agent_id LIKE 'finance-%'"

# Numeric comparisons
"risk_score >= 50"
"amount BETWEEN 1000 AND 50000"

Available Fields

Field	Type	Description
action_type	string	Action category
agent_id	string	Agent identifier
resource	string	Target resource
environment	string	prod/staging/dev
risk_score	int	Calculated risk (0-100)
data_classification	string	pii/financial/public
user_id	string	Acting user
time_context	string	business_hours/after_hours
amount	float	Transaction amount

ML-Powered Suggestions

Get Suggestions

curl "https://pilot.owkai.app/api/smart-rules/suggestions" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "suggestions": [
    {
      "id": 1,
      "suggested_rule": "Automated response for Unauthorized Access alerts",
      "confidence": 87,
      "reasoning": "Pattern analysis identified 150 occurrences in last 30 days. 45% escalation rate indicates high threat level requiring immediate attention.",
      "potential_impact": "Could automate 135 alerts/month, saving ~11 analyst hours ($825 value).",
      "data_points": 150,
      "priority": "critical",
      "category": "unauthorized_access"
    },
    {
      "id": 2,
      "suggested_rule": "Enhanced monitoring during 14:00-15:00 peak hours",
      "confidence": 78,
      "reasoning": "Temporal analysis identified 89 alerts during this hour (35% high/critical severity).",
      "potential_impact": "Faster response for 89 peak-hour alerts/month.",
      "data_points": 89,
      "priority": "high",
      "category": "temporal_optimization"
    }
  ]
}

Suggestion Types

# Source: routes/smart_rules_routes.py:1269
# ML suggestions are generated from four analysis patterns:

# 1. Gap Analysis - High-volume alert types without rules
# Query: Find alert types that occur frequently but lack dedicated rules

# 2. Temporal Patterns - Peak hours requiring monitoring
# Query: Find hours with >50% above average alert volume

# 3. Agent Behavior - Agents with high false positive rates
# Query: Find agents needing threshold tuning

# 4. Automation Opportunities - Repetitive manual actions
# Query: Find actions with >80% approval rate (safe to automate)

A/B Testing

Create A/B Test

curl -X POST "https://pilot.owkai.app/api/smart-rules/ab-test?rule_id=123" \
  -H "Authorization: Bearer owkai_..." \
  -H "Content-Type: application/json" \
  -d '{
    "traffic_split": 50,
    "test_duration_hours": 168
  }'

Response:

{
  "success": true,
  "test_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "rule_id": 123,
  "variant_a_rule_id": 124,
  "variant_b_rule_id": 125,
  "message": "A/B test created successfully!"
}

Monitor A/B Test

curl "https://pilot.owkai.app/api/smart-rules/ab-tests" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "ab_tests": [
    {
      "test_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "test_name": "A/B Test: High-Value Transaction Alert",
      "status": "running",
      "progress_percentage": 65,
      "variant_a_performance": 78,
      "variant_b_performance": 85,
      "confidence_level": 82,
      "winner": null,
      "statistical_significance": "medium",
      "improvement": "+9.0% projected",
      "enterprise_insights": {
        "cost_savings": "$4,500/month projected",
        "false_positive_reduction": "7.0% reduction",
        "recommendation": "Monitor for 24-48 hours for statistical significance"
      }
    }
  ]
}

Deploy Winner

curl -X POST "https://pilot.owkai.app/api/smart-rules/ab-test/f47ac10b.../deploy" \
  -H "Authorization: Bearer owkai_..."

Rule Analytics

Get Analytics

curl "https://pilot.owkai.app/api/smart-rules/analytics" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "total_rules": 25,
  "active_rules": 25,
  "avg_performance_score": 87.5,
  "total_triggers_24h": 1247,
  "false_positive_rate": 3.2,
  "top_performing_rules": [
    {
      "id": 45,
      "name": "Financial Transaction Monitor",
      "score": 95,
      "category": "high"
    }
  ],
  "performance_trends": {
    "accuracy_improvement": "+12%",
    "response_time_improvement": "-25%",
    "false_positive_reduction": "-35%"
  },
  "enterprise_metrics": {
    "cost_savings_monthly": "$12,500",
    "incidents_prevented": 47,
    "automation_rate": "78%"
  }
}

Rule Performance Metrics

Metric	Description	Calculation
performance_score	Overall effectiveness	(total - false_positives) / total × 100
triggers_last_24h	Recent activity	Count from alerts table
false_positive_rate	Noise level	FP / total × 100
effectiveness_rating	Classification	high (≥90), medium (≥70), low (<70)

Optimize Rules

Request Optimization

curl -X POST "https://pilot.owkai.app/api/smart-rules/optimize/123" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "rule_id": 123,
  "status": "analysis_complete",
  "original_performance": 78.5,
  "data_points_analyzed": 1247,
  "current_metrics": {
    "total_triggers_30d": 1247,
    "false_positives_30d": 267,
    "false_positive_rate": "21.4%",
    "avg_detection_time_ms": 45.2
  },
  "optimization_available": true,
  "optimization_techniques": [
    "Machine learning threshold tuning",
    "Behavioral pattern recognition",
    "Threat intelligence integration",
    "Context-aware analysis"
  ],
  "message": "Optimization recommendations available"
}

List Rules

curl "https://pilot.owkai.app/api/smart-rules" \
  -H "Authorization: Bearer owkai_..."

Response:

[
  {
    "id": 123,
    "name": "High-Value Transaction Alert",
    "condition": "action_type == 'financial.transfer' AND amount > 10000",
    "action": "require_approval",
    "risk_level": "high",
    "performance_score": 92,
    "triggers_last_24h": 47,
    "false_positives": 2,
    "effectiveness_rating": "high",
    "last_triggered": "2025-12-15T10:30:00Z",
    "has_execution_history": true
  }
]

Delete Rule

curl -X DELETE "https://pilot.owkai.app/api/smart-rules/123" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "message": "Enterprise smart rule deleted successfully",
  "audit_info": {
    "rule_id": 123,
    "deleted_by": "admin@company.com",
    "deletion_timestamp": "2025-12-15T10:30:00Z"
  },
  "recommendation": "Monitor security metrics for 24 hours to ensure no coverage gaps"
}

Best Practices

1. Start with ML Suggestions

# Use ML to identify gaps in coverage
suggestions = client.get_rule_suggestions()

for suggestion in suggestions:
    if suggestion.confidence > 80:
        print(f"High-confidence suggestion: {suggestion.name}")

2. A/B Test Before Deploying

# Always test rule changes
test = client.create_ab_test(rule_id=123, duration_hours=168)

# Wait for statistical significance
while test.confidence < 90:
    test = client.get_ab_test(test.test_id)
    time.sleep(3600)

# Deploy winner
client.deploy_ab_test_winner(test.test_id)

3. Monitor Performance

# Regular performance reviews
analytics = client.get_rule_analytics()

for rule in analytics.rules:
    if rule.false_positive_rate > 20:
        print(f"Rule {rule.name} needs tuning: {rule.false_positive_rate}% FP")

4. Use Specific Conditions

# Good - specific and targeted
{
    "condition": "action_type == 'database.delete' AND environment == 'production' AND data_classification == 'pii'"
}

# Bad - too broad, many false positives
{
    "condition": "action_type LIKE '%delete%'"
}

Next Steps

• Approval Workflows — Configure approvals
• Risk Assessment — Customize scoring
• Analytics — Monitor effectiveness

---

Document Version: 2026.04 | Last Updated: April 2026