Smart Rules Engine

Field	Value
Document ID	ASCEND-GOV-008
Version	1.0.0
Last Updated	December 19, 2025
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.

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: 1.0.0 | Last Updated: December 2025