Omniguard Protocol Integration Guide for Kindly API¶

Overview¶

The Omniguard Protocol has been successfully integrated into Kindly API, providing quantum-temporal security that operates at sub-microsecond speeds. This guide explains how to use and configure Omniguard with your existing Kindly API setup.

Architecture Integration¶

Omniguard leverages Kindly API's existing components:

• Quantum Superposition Cache: Used for parallel threat assessment across 4 timelines
• Atomic Primitives: Circuit breaker and rate limiter for resilience
• Zero-Copy Cache: High-performance threat pattern storage
• Universal API: Seamless integration with existing API traits

Quick Start¶

1. Basic Setup¶

use kindly_api::security::omniguard_integrated::OmniguardProtocol;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize Omniguard
    let omniguard = OmniguardProtocol::new().await?;

    // Use with your API
    // ...

    Ok(())
}

2. Axum Middleware Integration¶

use axum::{Router, routing::post};
use kindly_api::security::omniguard_integrated::middleware::omniguard_middleware;

let app = Router::new()
    .route("/api/endpoint", post(handler))
    .layer(axum::middleware::from_fn_with_state(
        omniguard.clone(),
        omniguard_middleware
    ));

3. Direct API Protection¶

use kindly_api::security::omniguard_integrated::{OmniguardProtocol, ApiRequest};

let request = ApiRequest {
    method: "POST".to_string(),
    path: "/api/data".to_string(),
    headers: headers,
    body: Some(body),
    query_params: params,
};

match omniguard.protect(&request).await {
    Ok(_) => {
        // Request is safe, proceed
    }
    Err(e) => {
        // Threat detected, handle accordingly
    }
}

Features¶

1. Quantum Timeline Defense¶

Omniguard uses Kindly API's Quantum Superposition Cache to evaluate requests across 4 parallel security universes:

• Conservative Universe: Strict security policies
• Aggressive Universe: Pattern-based detection
• Balanced Universe: Hybrid approach
• Creative Universe: Novel threat detection

2. Integrated Threat Detection¶

Built-in detection for: - SQL Injection - XSS Attacks - Authentication Bypass - Command Injection - Novel AI-generated attacks

3. Hive Mind Intelligence¶

All Omniguard instances share threat intelligence: - Global threat DNA database - Evolution pattern tracking - Collective learning - Real-time threat sharing

4. Sub-Microsecond Performance¶

Leveraging Kindly API's atomic primitives: - Total security check: <1μs - Rate limiting: Atomic operations - Circuit breaking: Fault isolation - Zero-copy operations: Maximum efficiency

Configuration¶

Security Levels¶

pub enum ThreatLevel {
    Safe,        // Normal operation
    Suspicious,  // Monitor closely
    Dangerous,   // Block request
    Critical,    // Ban source
}

Security Actions¶

pub enum SecurityAction {
    Allow,                      // Permit request
    Challenge,                  // Require additional verification
    Block,                      // Deny request
    BanTemporary(Duration),     // Temporary ban
    BanPermanent,              // Permanent ban
}

Performance Optimization¶

1. Caching Strategy¶

Omniguard uses the Quantum Cache for threat assessments: - Automatic caching of assessments - Quantum prefetch for predicted threats - Confidence-based cache invalidation

2. Zero-Copy Operations¶

Threat patterns are stored in Zero-Copy Cache: - No memory allocation for lookups - Direct memory mapping - Hardware-optimized access

3. Atomic Operations¶

All state changes use atomic operations: - Lock-free progress - Wait-free algorithms - Cache-line aligned structures

Best Practices¶

1. Initialization¶

Initialize Omniguard once at startup:

lazy_static! {
    static ref OMNIGUARD: Arc<OmniguardProtocol> = {
        tokio::runtime::Runtime::new()
            .unwrap()
            .block_on(OmniguardProtocol::new())
            .unwrap()
    };
}

2. Request Conversion¶

Convert your requests to ApiRequest format:

impl From<HttpRequest> for ApiRequest {
    fn from(req: HttpRequest) -> Self {
        ApiRequest {
            method: req.method().to_string(),
            path: req.uri().path().to_string(),
            headers: extract_headers(&req),
            body: extract_body(&req),
            query_params: extract_query(&req),
        }
    }
}

3. Error Handling¶

Handle Omniguard errors appropriately:

match omniguard.protect(&request).await {
    Ok(_) => proceed_with_request(),
    Err(ApiError::Forbidden(msg)) => {
        log::warn!("Threat detected: {}", msg);
        return forbidden_response();
    }
    Err(ApiError::TooManyRequests(_)) => {
        return rate_limit_response();
    }
    Err(e) => {
        log::error!("Omniguard error: {:?}", e);
        return internal_error_response();
    }
}

Monitoring and Metrics¶

1. Security Metrics¶

Track key security metrics: - Threats detected per minute - Threat level distribution - Response time percentiles - Cache hit rates

2. Performance Metrics¶

Monitor performance: - Average protection latency - Circuit breaker state - Rate limiter capacity - Memory usage

3. Threat Intelligence¶

Access hive mind data:

let stats = omniguard.get_threat_stats().await;
println!("Global threats: {}", stats.total_threats);
println!("Evolution chains: {}", stats.evolution_patterns);

Advanced Usage¶

1. Custom Threat Patterns¶

Add custom threat detection:

omniguard.add_custom_pattern(
    "custom_attack",
    r"malicious.*pattern",
    ThreatLevel::Critical
).await;

2. Integration with Universal API¶

Use as a security provider:

#[async_trait]
impl SecurityProvider for OmniguardProtocol {
    async fn validate_request(&self, request: &UniversalRequest) -> Result<()> {
        // Custom validation logic
    }
}

3. Distributed Deployment¶

Share intelligence across instances:

omniguard.connect_to_hive_mind("redis://hive-mind:6379").await?;

Migration from Existing Security¶

From Basic Auth¶

// Before
if !validate_api_key(&request) {
    return Err(Unauthorized);
}

// After
omniguard.protect(&request).await?;

From Rate Limiting¶

// Before
if !rate_limiter.check(&client_ip) {
    return Err(TooManyRequests);
}

// After
// Omniguard includes rate limiting
omniguard.protect(&request).await?;

Troubleshooting¶

High Latency¶

If protection takes >1μs: 1. Check cache configuration 2. Verify atomic operations 3. Monitor circuit breaker state

False Positives¶

To reduce false positives: 1. Adjust threat thresholds 2. Train on legitimate traffic 3. Fine-tune quantum universes

Memory Usage¶

To optimize memory: 1. Configure cache sizes 2. Enable cache eviction 3. Monitor threat pattern growth

Conclusion¶

The Omniguard Protocol provides Kindly API with state-of-the-art security that operates at the speed of memory. By leveraging quantum superposition, atomic operations, and collective intelligence, your API is protected against both current and future threats.

For support or questions, consult the main Omniguard documentation or raise an issue in the repository.