GovOps: Design

Design Document

Overview

Agama GovOps is a comprehensive continuous governance platform that provides automated oversight, compliance monitoring, and policy enforcement for AI agents and infrastructure systems. The platform is built on a distributed architecture that combines real-time monitoring, policy enforcement, and centralized management capabilities.

The system integrates three core technologies:

• Cedar-based authorization engine (via Cedarling) for fine-grained policy enforcement
• OSCAL compliance framework for standardized compliance management
• Protobuf Schema Registry to validate the shape of policy data

Architecture

High-Level Architecture

graph TB
    subgraph "Agama Lab Frontend"
        PolicyDesigner[Policy Designer UI]
        SchemaEditor[Protobuf Schema Editor]
        TrustManager[Trust Management UI]
        FormalAnalysis[Cedar Formal Analysis UI]
    end
    
    subgraph "Agama GovOps Platform"
        AgamaLabAPI[Agama Lab API]
        PolicyEngine[Policy Management Engine]
        ComplianceEngine[Compliance Engine]
        AuditEngine[Audit & Analytics Engine]
        DashboardEngine[Dashboard & KPI Engine]
        APIGateway[API Gateway]
    end
    
    subgraph "Analysis Services"
        CedarAnalyzer[Cedar Analysis Tools]
        ProtobufValidator[Protobuf Schema Validator]
        TrustValidator[Trust Relationship Validator]
        SchemaRegistry[Protobuf Schema Registry]
    end
    
    subgraph "Version Control & Distribution"
        GitHub[GitHub Repository]
        GitHubReleases[GitHub Releases]
        HubSystem[Hub System]
    end
    
    subgraph "Distributed Infrastructure"
        Agent1[AI Agent 1 + Cedarling]
        Agent2[AI Agent 2 + Cedarling]
    end
    
    subgraph "External Systems"
        CICD[CI/CD Pipelines]
        ExternalSystems[External Compliance Systems]
    end
    
    PolicyDesigner --> AgamaLabAPI
    SchemaEditor --> AgamaLabAPI
    TrustManager --> AgamaLabAPI
    FormalAnalysis --> AgamaLabAPI
    
    AgamaLabAPI --> CedarAnalyzer
    AgamaLabAPI --> ProtobufValidator
    AgamaLabAPI --> TrustValidator
    AgamaLabAPI --> SchemaRegistry
    
    SchemaEditor --> SchemaRegistry
    ProtobufValidator --> SchemaRegistry
    
    AgamaLabAPI --> GitHub
    AgamaLabAPI --> PolicyEngine
    AgamaLabAPI --> ComplianceEngine
    AgamaLabAPI --> AuditEngine
    AgamaLabAPI --> DashboardEngine
    
    DashboardEngine --> PolicyEngine
    DashboardEngine --> ComplianceEngine
    DashboardEngine --> AuditEngine
    DashboardEngine --> HubSystem
    
    GitHub --> GitHubReleases
    GitHubReleases --> HubSystem
    PolicyEngine --> HubSystem
    
    HubSystem --> Agent1
    HubSystem --> Agent2
    
    Agent1 --> HubSystem
    Agent2 --> HubSystem
    
    AgamaLabAPI --> CICD
    AgamaLabAPI --> ExternalSystems

Loading

Component Architecture

The platform follows a microservices architecture with the following MVP components:

1. Agama Lab Frontend - The primary user interface for policy authoring and validation
2. Agama Lab API - Backend services supporting policy management and GitHub integration
3. Cedar Analysis Tools - Formal reasoning and policy validation services
4. Protobuf Schema Registry - Basic schema management and validation (MVP scope)
5. Policy Management Engine - Handles policy authoring, validation, and GitHub-based distribution
6. Basic Compliance Engine - Minimal OSCAL component-definition builder for policy-to-control mapping
7. Dashboard & KPI Engine - Single MVP dashboard for real-time policy decisions and PESR KPI
8. Hub System Integration - Policy distribution and log collection from Cedarling instances
9. Distributed Cedarling Agents - Embedded policy enforcement points

Components and Interfaces

Agama Lab Frontend

Purpose: The primary customer experience and front door for all governance operations

Key Features:

• Policy Designer UI: Visual policy authoring with Cedar syntax support and real-time validation
• Protobuf Schema Editor: Schema definition and validation for structured data types
• Trust Management UI: Configuration of trusted JWT token issuers and trust relationships
• Cedar Formal Analysis UI: Interface for formal reasoning, policy verification, and analysis results
• OSCAL Content Authoring Suite: Comprehensive OSCAL artifact creation and management
  • Catalog Editor: Create and maintain security control catalogs with markdown-based agile authoring
  • Profile Builder: Visual interface for selecting controls from catalogs to build profiles and baselines
  • Component Definition Designer: Connect controls to policies and implementation details
  • OSCAL Artifact Viewer: Browse and navigate OSCAL documents with rich visualization
• Compliance Dashboard: Real-time compliance monitoring and assessment reporting
• Real-time Governance Dashboard: Monitoring of AI agents, infrastructure, and policy violations

Interfaces:

• Modern React-based SPA with TypeScript
• WebSocket connections for real-time policy validation and analysis feedback
• REST API integration with Agama Lab API backend
• Integration with Cedar Analysis Tools for formal verification

Agama Lab API

Purpose: Backend services supporting the frontend and providing policy management capabilities

Key Features:

• Policy authoring and validation services with GitHub integration
• Schema management and Protobuf validation
• Trust relationship management and JWT issuer configuration
• Integration with Cedar Analysis Tools for formal reasoning
• OSCAL Content Management: Full lifecycle management of OSCAL artifacts
  • Agile Authoring Integration: Compliance-trestle integration for markdown-based OSCAL editing
  • OSCAL Artifact Generation: Automatic conversion from markdown to OSCAL JSON
  • OSCAL Validation: Schema validation and content verification for all OSCAL artifacts
  • OSCAL Distribution: Publishing and distribution of OSCAL catalogs, profiles, and component definitions
• Real-time policy validation and syntax checking
• GitHub repository management for policy development
• GitHub Releases integration for versioned policy distribution

Interfaces:

• RESTful API for frontend integration
• GitHub API integration for policy storage and version control
• gRPC connections to Cedar Analysis Tools
• WebSocket support for real-time validation feedback
• Integration with Hub System for policy distribution via GitHub Releases

Cedar Analysis Tools

Purpose: Provides formal reasoning and advanced policy verification capabilities

Key Features:

• Formal Policy Verification: Uses Rust Cedar engine with CVC5 SMT solver for mathematical proofs
• Policy Error Analysis: Detects potential runtime errors before deployment
• Policy Set Behavior Analysis: Determines if policies always allow/deny access
• Cross-Policy Analysis: Policy implication, equivalence, and disjoint detection
• Multi-Store Analysis: Strategic analysis across multiple policy stores
• Symbolic Compilation: Translates Cedar policies into SMT-friendly mathematical formulas

Interfaces:

• Containerized sidecar service to Agama Lab API
• RESTful API endpoints for various analysis operations
• Integration with CVC5 binary for SMT solving
• Support for both real-time and strategic analysis operations

Protobuf Schema Registry

Purpose: Provides centralized management and validation of Protobuf schemas for structured data governance

Key Features:

• Schema Versioning: Manages multiple versions of Protobuf schemas with backward compatibility checking
• Schema Validation: Validates Protobuf schema syntax and semantic correctness
• Schema Evolution: Supports safe schema evolution with compatibility analysis
• Type Safety: Ensures type safety across policy definitions and data structures
• Schema Discovery: Provides searchable registry of available schemas and their documentation
• Integration with Policy Store: Links schemas to Cedar policies for comprehensive governance
• GitHub Integration: Stores schemas in GitHub repositories with version control

Interfaces:

• Schema Registry API (REST) for schema management operations
• Protobuf compiler integration for schema validation
• Schema compatibility checking API
• Integration with Agama Lab Schema Editor
• GitHub API integration for schema storage and versioning
• Cedar policy integration for schema-aware policy validation

Policy Store Authoring Tools

Purpose: Manages the complete lifecycle of governance policies with GitHub and Hub System integration

Key Features:

• Cedar policy lifecycle management (create, update, version, deploy) with GitHub storage
• Policy conflict detection and resolution across multiple stores
• Policy testing and simulation against historical data
• GitHub-based version control with automated release management
• Integration with Hub System for policy distribution via GitHub Releases
• Support for multi-policy store operations with GitHub repository organization

Interfaces:

• Policy Authoring API (REST) integrated with Agama Lab API
• GitHub API integration for policy storage, versioning, and releases
• Policy Distribution Service (gRPC to Hub System) consuming GitHub Releases
• Policy Validation Engine with Cedar Analysis Tools integration
• Policy Simulation Engine with historical data replay capabilities
• Multi-store policy management using GitHub repository structure

Compliance Engine

Purpose: Comprehensive OSCAL-based compliance content creation, management, and monitoring

Key Features:

• OSCAL Catalog Management: Create, edit, and maintain security control catalogs (NIST 800-53, custom frameworks)
• OSCAL Profile Creation: Build profiles by selecting controls from catalogs to create baselines and tailored control sets
• OSCAL Component Definition Authoring: Connect controls to policies and implementation details through component definitions
• Agile Authoring Workflows: Markdown-based editing of OSCAL content with automatic JSON generation via compliance-trestle
• Infrastructure Discovery and Inventory: Automated discovery and mapping of infrastructure components to OSCAL artifacts
• Automated Compliance Assessment: Continuous evaluation of infrastructure against OSCAL profiles and component definitions
• Evidence Collection and Reporting: Automated gathering of compliance evidence and generation of assessment reports
• OSCAL Artifact Lifecycle Management: Version control, release management, and distribution of OSCAL documents

Interfaces:

• OSCAL Catalog Authoring API (REST) - Create and manage security control catalogs
• OSCAL Profile Builder API (REST) - Select and tailor controls from catalogs
• OSCAL Component Definition API (REST) - Connect controls to implementation policies
• Agile Authoring Interface - Markdown-based editing with trestle integration
• Infrastructure Discovery API (REST) - Automated component discovery and mapping
• Compliance Assessment Engine - Continuous monitoring and evaluation
• OSCAL Document Distribution API - Publish and distribute OSCAL artifacts
• Report Generation Service - Compliance reports and evidence packages

OSCAL Content Management System

Purpose: Dedicated system for comprehensive OSCAL artifact lifecycle management with compliance-trestle integration

Key Features:

• Compliance-Trestle Integration: Full integration with compliance-trestle for agile authoring workflows
• OSCAL Template Library: Pre-built templates for NIST 800-53, ISO 27001, and custom security frameworks
• Markdown-to-OSCAL Pipeline: Automated conversion from markdown content to valid OSCAL JSON artifacts
• OSCAL Schema Validation: Real-time validation against official OSCAL schemas with detailed error reporting
• Collaborative Authoring: Multi-user editing with conflict resolution, review workflows, and approval processes
• OSCAL Artifact Relationships: Automatic management of dependencies between catalogs, profiles, and component definitions
• Version Control and Branching: Git-based version control with support for feature branches and release management
• OSCAL Distribution Pipeline: Automated publishing and distribution to downstream systems and repositories

Interfaces:

• OSCAL Authoring API (REST) - Comprehensive OSCAL artifact creation and editing
• Trestle Engine API (gRPC) - Direct integration with compliance-trestle processing engine
• OSCAL Template API (REST) - Manage and instantiate OSCAL templates
• OSCAL Validation API (REST) - Schema validation and content verification services
• OSCAL Relationship API (REST) - Manage dependencies and relationships between artifacts
• OSCAL Publishing API (REST) - Automated distribution and publishing workflows

Audit & Analytics Engine

Purpose: Processes and analyzes audit data from distributed sources

Key Features:

• Real-time log ingestion from Hub System
• Audit trail reconstruction and analysis
• Anomaly detection and alerting
• Compliance reporting and evidence generation

Interfaces:

• Log Ingestion API (streaming from Hub System)
• Analytics Query API (GraphQL)
• Alert Management API (REST)
• Report Export API (REST)

Dashboard & KPI Engine (MVP)

Purpose: Provides single MVP dashboard for real-time policy decisions and Policy Enforcement Success Rate (PESR) KPI

Key Features:

• Real-Time Policy Decisions Dashboard: Live decision stream showing permit/deny/error events in chronological order
• Policy Enforcement Success Rate (PESR): Single KPI tracking percentage of agent actions receiving valid decisions without errors
• Basic Filtering: Filter decisions by agent, action, and resource
• Error Highlighting: Visual indicators for policy evaluation errors
• Status Indicators: Policy store version (current vs. latest) and enforcement status (healthy/degraded)
• Top Policies Triggered: Shows which policies govern the most activity

Interfaces:

• Dashboard API (REST) for real-time policy decision queries
• PESR KPI calculation engine
• WebSocket connections for live decision stream updates
• Integration with Hub System for decision log data
• Basic filtering and search API

Hub System Integration

Purpose: Provides policy distribution and log aggregation with GitHub-based versioning

Key Features:

• GitHub-based Policy Distribution: Consumes policy releases from GitHub Releases for distribution to Cedarling instances
• Binary Policy Store Distribution: Converts GitHub releases into binary policy stores for efficient distribution
• Policy Version Management: Manages policy versioning based on GitHub release tags and rollback capabilities
• Centralized Log Collection: Collects logs from all distributed Cedarling instances
• Resilient Communication: Handles network partitions and connectivity issues gracefully

Interfaces:

• GitHub API integration for consuming releases and policy artifacts
• Policy Distribution API (HTTP/gRPC with binary release management)
• Log Collection API (gRPC streaming with buffering support)
• Authentication and Authorization (OAuth 2.0 with JWT validation)
• Real-time Status Monitoring (WebSocket connections for system health)

Testing Strategy

Unit Testing

• Policy Engine: Test Cedar policy validation, conflict detection, and simulation
• Compliance Engine: Test OSCAL document processing and compliance assessment
• Audit Engine: Test log processing, analysis, and reporting functions
• API Layer: Test all REST and GraphQL endpoints

Integration Testing

• Hub System Integration: Test policy distribution and log collection
• Cedarling Integration: Test policy enforcement and audit logging
• External System Integration: Test CI/CD pipeline integration and external APIs

End-to-End Testing

• Governance Workflows: Test complete policy lifecycle from authoring to enforcement
• Compliance Workflows: Test infrastructure assessment and reporting
• Incident Response: Test alert generation and investigation workflows

Performance Testing

• Policy Evaluation: Ensure sub-second response times for policy decisions
• Log Processing: Test high-volume log ingestion and processing
• Dashboard Responsiveness: Test real-time updates and query performance

Security Testing

• Authentication/Authorization: Test user access controls and token validation
• Policy Enforcement: Test that policies cannot be bypassed
• Audit Integrity: Test that audit logs cannot be tampered with

Test Data Management

// Test policy store for development and testing
const testPolicyStore = {
  policies: [
    {
      id: "test-policy-1",
      cedar: `
        permit (
          principal == AIAgent::"test-agent",
          action == Action::"Execute",
          resource == InfrastructureComponent::"test-resource"
        ) when {
          principal.riskLevel == "low" &&
          resource.securityLevel == "standard"
        };
      `
    }
  ],
  entities: [
    {
      uid: { type: "AIAgent", id: "test-agent" },
      attrs: { riskLevel: "low", type: "classifier" }
    }
  ]
};

Continuous Testing

• Policy Regression Testing: Automated testing of policy changes against historical decisions
• Compliance Drift Detection: Continuous monitoring of infrastructure compliance
• Performance Monitoring: Real-time monitoring of system performance metrics