prvng_platform/control-center/README.md

Control Center - Cedar Policy Engine

A comprehensive Cedar policy engine implementation with advanced security features, compliance checking, and anomaly detection.

Features

🔐 Cedar Policy Engine

• Policy Evaluation: High-performance policy evaluation with context injection
• Versioning: Complete policy versioning with rollback capabilities
• Templates: Configuration-driven policy templates with variable substitution
• Validation: Comprehensive policy validation with syntax and semantic checking

🛡️ Security & Authentication

• JWT Authentication: Secure token-based authentication
• Multi-Factor Authentication: MFA support for sensitive operations
• Role-Based Access Control: Flexible RBAC with policy integration
• Session Management: Secure session handling with timeouts

📊 Compliance Framework

• SOC2 Type II: Complete SOC2 compliance validation
• HIPAA: Healthcare data protection compliance
• Audit Trail: Comprehensive audit logging and reporting
• Impact Analysis: Policy change impact assessment

🔍 Anomaly Detection

• Statistical Analysis: Multiple statistical methods (Z-Score, IQR, Isolation Forest)
• Real-time Detection: Continuous monitoring of policy evaluations
• Alert Management: Configurable alerting through multiple channels
• Baseline Learning: Adaptive baseline calculation for improved accuracy

🗄️ Storage & Persistence

• SurrealDB Integration: High-performance graph database backend
• Policy Storage: Versioned policy storage with metadata
• Metrics Storage: Policy evaluation metrics and analytics
• Compliance Records: Complete compliance audit trails

Quick Start

1. Installation

cd src/control-center
cargo build --release

2. Configuration

Copy the example configuration:

cp config.toml.example config.toml

Edit config.toml for your environment:

[database]
url = "surreal://localhost:8000"  # Your SurrealDB instance
username = "root"
password = "your-password"

[auth]
jwt_secret = "your-super-secret-key"
require_mfa = true

[compliance.soc2]
enabled = true

[anomaly]
enabled = true
detection_threshold = 2.5

3. Start the Server

./target/release/control-center server --port 8080

4. Test Policy Evaluation

curl -X POST http://localhost:8080/policies/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"id": "user123", "roles": ["Developer"]},
    "action": {"id": "access"},
    "resource": {"id": "sensitive-db", "classification": "confidential"},
    "context": {"mfa_enabled": true, "location": "US"}
  }'

Policy Examples

Multi-Factor Authentication Policy

// Require MFA for sensitive resources
permit(
    principal,
    action == Action::"access",
    resource
) when {
    resource has classification &&
    resource.classification in ["sensitive", "confidential"] &&
    principal has mfa_enabled &&
    principal.mfa_enabled == true
};

Production Approval Policy

// Require approval for production operations
permit(
    principal,
    action in [Action::"deploy", Action::"modify", Action::"delete"],
    resource
) when {
    resource has environment &&
    resource.environment == "production" &&
    principal has approval &&
    principal.approval.approved_by in ["ProductionAdmin", "SRE"]
};

Geographic Restrictions

// Allow access only from approved countries
permit(
    principal,
    action,
    resource
) when {
    context has geo &&
    context.geo has country &&
    context.geo.country in ["US", "CA", "GB", "DE"]
};

CLI Commands

Policy Management

# Validate policies
control-center policy validate policies/

# Test policy with test data
control-center policy test policies/mfa.cedar tests/data/mfa_test.json

# Analyze policy impact
control-center policy impact policies/new_policy.cedar

Compliance Checking

# Check SOC2 compliance
control-center compliance soc2

# Check HIPAA compliance
control-center compliance hipaa

# Generate compliance report
control-center compliance report --format html

API Endpoints

Policy Evaluation

• POST /policies/evaluate - Evaluate policy decision
• GET /policies - List all policies
• POST /policies - Create new policy
• PUT /policies/{id} - Update policy
• DELETE /policies/{id} - Delete policy

Policy Versions

• GET /policies/{id}/versions - List policy versions
• GET /policies/{id}/versions/{version} - Get specific version
• POST /policies/{id}/rollback/{version} - Rollback to version

Compliance

• GET /compliance/soc2 - SOC2 compliance check
• GET /compliance/hipaa - HIPAA compliance check
• GET /compliance/report - Generate compliance report

Anomaly Detection

• GET /anomalies - List detected anomalies
• GET /anomalies/{id} - Get anomaly details
• POST /anomalies/detect - Trigger anomaly detection

Testing

Run Unit Tests

cargo test

Run Integration Tests

cargo test --test integration_tests

Run Policy Tests

cargo test --test policy_tests

Run Compliance Tests

cargo test --test compliance_tests

Architecture

Core Components

1. Policy Engine (src/policies/engine.rs)

   • Cedar policy evaluation
   • Context injection
   • Caching and optimization

2. Storage Layer (src/storage/)

   • SurrealDB integration
   • Policy versioning
   • Metrics storage

3. Compliance Framework (src/compliance/)

   • SOC2 checker
   • HIPAA validator
   • Report generation

4. Anomaly Detection (src/anomaly/)

   • Statistical analysis
   • Real-time monitoring
   • Alert management

5. Authentication (src/auth.rs)

   • JWT token management
   • Password hashing
   • Session handling

Configuration-Driven Design

The system follows PAP (Project Architecture Principles) with:

• No hardcoded values: All behavior controlled via configuration
• Dynamic loading: Policies and rules loaded from configuration
• Template-based: Policy generation through templates
• Environment-aware: Different configs for dev/test/prod

Security Features

• Audit Logging: All policy evaluations logged
• Encryption: Data encrypted at rest and in transit
• Rate Limiting: Protection against abuse
• Input Validation: Comprehensive validation of all inputs
• Error Handling: Secure error handling without information leakage

Production Deployment

Docker

FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates
COPY --from=builder /app/target/release/control-center /usr/local/bin/
EXPOSE 8080
CMD ["control-center", "server"]

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: control-center
spec:
  replicas: 3
  selector:
    matchLabels:
      app: control-center
  template:
    metadata:
      labels:
        app: control-center
    spec:
      containers:
      - name: control-center
        image: control-center:latest
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          value: "surreal://surrealdb:8000"

Environment Variables

# Override config values with environment variables
export CONTROL_CENTER_SERVER_PORT=8080
export CONTROL_CENTER_DATABASE_URL="surreal://prod-db:8000"
export CONTROL_CENTER_AUTH_JWT_SECRET="production-secret"
export CONTROL_CENTER_COMPLIANCE_SOC2_ENABLED=true

Monitoring & Observability

Metrics

• Policy evaluation latency
• Policy decision distribution
• Anomaly detection rates
• Compliance scores

Logging

// Structured logging with tracing
tracing::info!(
    policy_id = %policy.id,
    principal = %context.principal.id,
    decision = ?result.decision,
    duration_ms = evaluation_time,
    "Policy evaluation completed"
);

Health Checks

curl http://localhost:8080/health

Contributing

1. Follow the PAP principles documented in the codebase
2. Add tests for new features
3. Update documentation
4. Ensure compliance checks pass
5. Add appropriate logging and monitoring

License

This project follows the licensing specified in the parent repository.

Support

For questions and support, refer to the project documentation or create an issue in the repository.