🏛️ Epic: Policy-as-Code Security & Compliance Automation Platform

Goal

Build a comprehensive Policy-as-Code platform that unifies all access control, authorization, and compliance mechanisms into a single, auditable, version-controlled system. This platform integrates existing policy engines (Cedar, OPA), implements the centralized RBAC/ABAC engine (#2019), and provides compliance automation for FedRAMP, HIPAA, SOC2, and other frameworks.

Why Now?

As ContextForge matures into an enterprise-grade gateway, organizations demand robust, auditable, and compliant access control:

1. Scattered Access Control: Currently, authorization is spread across RBAC middleware, token scoping, service-layer filters, and plugins—no single source of truth
2. Compliance Pressure: Enterprises need demonstrable compliance with FedRAMP, HIPAA, SOC2, PCI-DSS—requiring centralized policy management and audit trails
3. Policy Engine Investment: Cedar and OPA plugins exist but aren't integrated into a unified framework with consistent APIs
4. Bell-LaPadula MAC: The Security Clearance Levels Plugin ([EPIC][SECURITY]: Security clearance levels plugin - Bell-LaPadula MAC implementation #1245) implements MAC but needs integration with RBAC for a complete security model
5. Audit Gap: Access decisions are logged inconsistently; compliance auditors need comprehensive decision logs
6. Policy Drift: Without version control and testing, policies degrade over time, introducing security gaps
7. Zero Trust Adoption: Modern security requires every request to be evaluated against policy—not just authenticated

By building a Policy-as-Code platform, ContextForge becomes a policy-enforced gateway where every action is authorized, logged, and auditable.

🎯 Platform Components

┌────────────────────────────────────────────────────────────────────────────────┐
│              Policy-as-Code Security & Compliance Platform                     │
├────────────────────────────────────────────────────────────────────────────────┤
│                                                                                │
│  ┌─────────────────────────────────────────────────────────────────────────┐  │
│  │                        Policy Decision Layer                             │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐    │  │
│  │  │  Cedar   │  │   OPA    │  │  Native  │  │  Security Clearance  │    │  │
│  │  │  Plugin  │  │  Plugin  │  │  RBAC    │  │  (Bell-LaPadula MAC) │    │  │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────────┬───────────┘    │  │
│  │       └──────────────┴──────────────┴──────────────────┘               │  │
│  │                            ▼                                            │  │
│  │              ┌─────────────────────────────┐                            │  │
│  │              │  Unified Policy Decision    │                            │  │
│  │              │  Point (PDP) Interface      │                            │  │
│  │              └─────────────────────────────┘                            │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                │
│  ┌─────────────────────────────────────────────────────────────────────────┐  │
│  │                        Policy Management Layer                           │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │  │
│  │  │   Policy     │  │   Policy     │  │   Policy     │  │  Policy    │  │  │
│  │  │   Editor     │  │   Testing    │  │   Versioning │  │  Import/   │  │  │
│  │  │   (Admin UI) │  │   Sandbox    │  │   & Rollback │  │  Export    │  │  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  └────────────┘  │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                │
│  ┌─────────────────────────────────────────────────────────────────────────┐  │
│  │                        Compliance & Audit Layer                          │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │  │
│  │  │  Decision    │  │  Compliance  │  │  Audit       │  │  SIEM      │  │  │
│  │  │  Audit Log   │  │  Reports     │  │  Dashboard   │  │  Export    │  │  │
│  │  │  (Every)     │  │  (FedRAMP,   │  │  (Real-time) │  │  (Splunk,  │  │  │
│  │  │              │  │  HIPAA, etc) │  │              │  │  ELK)      │  │  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  └────────────┘  │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                │
│  ┌─────────────────────────────────────────────────────────────────────────┐  │
│  │                        Access Control Mechanisms                         │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │  │
│  │  │   RBAC       │  │   ABAC       │  │   MAC        │  │  JIT       │  │  │
│  │  │  (Roles)     │  │ (Attributes) │  │ (Clearance)  │  │  Access    │  │  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  └────────────┘  │  │
│  └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘

📖 User Stories

Given I access /admin/policies
When I view the policy dashboard:
Then I see:
  - All active policies (Cedar, OPA, native RBAC, MAC)
  - Policy status (active, draft, disabled)
  - Policy evaluation metrics
  - Recent policy changes
And I can create new policies using a visual editor or code
And I can test policies before deployment
And I can rollback to previous policy versions

Given I need to produce FedRAMP compliance evidence:
When I generate a compliance report:
Then the report includes:
  - Access control policy inventory
  - Decision audit logs (who accessed what, when)
  - Policy change history
  - Separation of duties evidence
  - Least privilege demonstration
  - Incident response logs
And the report is exportable in PDF, CSV, JSON formats
And the report maps to specific FedRAMP controls (AC-2, AC-3, etc.)

Given I have a new ABAC policy to deploy:
When I enter the policy testing sandbox:
Then I can:
  - Simulate requests from any user/role/context
  - See which policies would allow/deny the request
  - View the decision explanation (matching rules)
  - Test against historical access patterns
  - Run regression tests against known scenarios
And the sandbox is isolated from production
And I can promote tested policies to production

Given a developer needs temporary admin access for incident response:
When I grant JIT access:
  grant_jit_access:
    user: developer@example.com
    role: incident-responder
    duration: 4h
    reason: "INC-1234: Production database issue"
    approver: security-lead@example.com
Then the user receives elevated privileges immediately
And access is automatically revoked after 4 hours
And all actions are logged with enhanced audit detail
And an alert is sent when JIT access is used

Given my tool invocation was denied:
When I query the access explanation endpoint:
  GET /access/explain?request_id=req-123
Then I receive:
  - The specific policy that denied access
  - My effective permissions at the time
  - What permissions would be required
  - How to request access (if applicable)
And sensitive policy details are not leaked
And I can initiate an access request workflow

🏗 Architecture

Policy Evaluation Flow

sequenceDiagram
    participant Client as Client
    participant Gateway as Gateway
    participant PDP as Policy Decision Point
    participant Cedar as Cedar Engine
    participant OPA as OPA Engine
    participant MAC as MAC Engine
    participant Audit as Audit Logger
    participant DB as Policy Store

    Client->>Gateway: Request (user, action, resource)
    Gateway->>PDP: check_access(subject, action, resource, context)
    
    par Parallel Policy Evaluation
        PDP->>Cedar: evaluate(request)
        Cedar-->>PDP: CedarDecision
    and
        PDP->>OPA: evaluate(request)
        OPA-->>PDP: OPADecision
    and
        PDP->>MAC: check_clearance(user, resource)
        MAC-->>PDP: MACDecision
    end
    
    PDP->>PDP: Combine decisions (AND/OR logic)
    PDP->>Audit: log_decision(request, decision, policies)
    PDP->>DB: store_decision(audit_record)
    
    alt Access Granted
        PDP-->>Gateway: Allow + metadata
        Gateway-->>Client: Response
    else Access Denied
        PDP-->>Gateway: Deny + reason
        Gateway-->>Client: 403 Forbidden
    end

Policy Store Schema

-- Policy definitions (version controlled)
CREATE TABLE policies (
    id UUID PRIMARY KEY,
    name VARCHAR(255) UNIQUE NOT NULL,
    version INTEGER NOT NULL DEFAULT 1,
    engine VARCHAR(50) NOT NULL,  -- cedar | opa | native | mac
    
    -- Policy content
    policy_code TEXT NOT NULL,  -- Cedar/Rego/DSL code
    policy_config JSONB,
    
    -- Metadata
    description TEXT,
    author VARCHAR(255),
    tags JSONB,
    
    -- Status
    status VARCHAR(30) DEFAULT 'draft',  -- draft | active | disabled | archived
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP,
    activated_at TIMESTAMP,
    
    INDEX idx_name (name),
    INDEX idx_engine (engine),
    INDEX idx_status (status)
);

-- Policy version history
CREATE TABLE policy_versions (
    id UUID PRIMARY KEY,
    policy_id UUID REFERENCES policies(id),
    version INTEGER NOT NULL,
    policy_code TEXT NOT NULL,
    policy_config JSONB,
    change_reason TEXT,
    changed_by VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(policy_id, version)
);

-- Policy decision audit log
CREATE TABLE policy_decisions (
    id UUID PRIMARY KEY,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    request_id VARCHAR(100),
    
    -- Subject
    subject_type VARCHAR(50),  -- user | token | agent | service
    subject_id VARCHAR(255),
    subject_email VARCHAR(255),
    subject_roles JSONB,
    subject_teams JSONB,
    subject_clearance INTEGER,
    
    -- Action & Resource
    action VARCHAR(100) NOT NULL,
    resource_type VARCHAR(100),
    resource_id VARCHAR(255),
    resource_server VARCHAR(255),
    
    -- Decision
    decision VARCHAR(20) NOT NULL,  -- allow | deny
    decision_reason TEXT,
    matching_policies JSONB,  -- [{id, name, engine, result}]
    
    -- Context
    context JSONB,  -- ip, time, mfa, custom attributes
    
    -- Metadata
    duration_ms INTEGER,
    gateway_node VARCHAR(100),
    
    INDEX idx_timestamp (timestamp),
    INDEX idx_subject_email (subject_email),
    INDEX idx_decision (decision),
    INDEX idx_resource_type (resource_type)
);

-- JIT access grants
CREATE TABLE jit_access_grants (
    id UUID PRIMARY KEY,
    user_email VARCHAR(255) NOT NULL,
    granted_role VARCHAR(100) NOT NULL,
    granted_permissions JSONB,
    
    -- Approval
    reason TEXT NOT NULL,
    approved_by VARCHAR(255),
    approved_at TIMESTAMP,
    
    -- Duration
    starts_at TIMESTAMP NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    
    -- Status
    status VARCHAR(30) DEFAULT 'pending',  -- pending | active | expired | revoked
    revoked_by VARCHAR(255),
    revoked_at TIMESTAMP,
    revoke_reason TEXT,
    
    -- Audit
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    INDEX idx_user_email (user_email),
    INDEX idx_status (status),
    INDEX idx_expires_at (expires_at)
);

-- Compliance report metadata
CREATE TABLE compliance_reports (
    id UUID PRIMARY KEY,
    framework VARCHAR(50) NOT NULL,  -- fedramp | hipaa | soc2 | pci-dss
    period_start DATE NOT NULL,
    period_end DATE NOT NULL,
    
    -- Content
    controls_evaluated INTEGER,
    controls_passed INTEGER,
    controls_failed INTEGER,
    findings JSONB,
    
    -- Storage
    report_path VARCHAR(500),
    
    -- Metadata
    generated_by VARCHAR(255),
    generated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    INDEX idx_framework (framework),
    INDEX idx_generated_at (generated_at)
);

📋 Implementation Tasks

Phase 1: Foundation & Unified PDP

• Create Unified Policy Decision Point

  • Define PolicyDecisionPoint interface
  • Implement adapter for Cedar plugin
  • Implement adapter for OPA plugin
  • Implement adapter for native RBAC ([FEATURE]: Centralized configurable RBAC/ABAC policy engine #2019)
  • Implement adapter for MAC plugin ([EPIC][SECURITY]: Security clearance levels plugin - Bell-LaPadula MAC implementation #1245)
  • Add decision combination logic (AND/OR)

• Policy Store

  • Create database schema for policies
  • Implement version control for policies
  • Add policy import/export functionality
  • Create policy repository service

Phase 2: Audit & Logging

• Decision Audit Logging

  • Create audit log schema
  • Implement comprehensive decision logging
  • Add structured JSON logging
  • Implement log retention policies
  • Add SIEM export (Splunk, ELK)

• Audit Dashboard

  • Real-time decision stream view
  • Filter by user, resource, decision
  • Decision explanation viewer
  • Trend analysis charts

Phase 3: Compliance Automation

• Compliance Report Generator

  • FedRAMP control mapping
  • HIPAA control mapping
  • SOC2 control mapping
  • Report template system
  • Evidence collection automation

• Control Evidence

  • Access control evidence (AC-2, AC-3)
  • Audit evidence (AU-2, AU-3)
  • Separation of duties evidence
  • Least privilege evidence

Phase 4: Policy Testing & Sandbox

• Policy Testing Sandbox

  • Isolated test environment
  • Request simulation
  • Decision explanation
  • Regression test suite
  • Policy diff visualization

• Policy Promotion Workflow

  • Draft → Review → Staging → Production
  • Approval workflow
  • Rollback capability
  • Canary deployment support

Phase 5: Just-in-Time Access

• JIT Access System
  • Temporary privilege grants
  • Approval workflow
  • Automatic expiration
  • Enhanced audit for JIT access
  • Break-glass emergency access

Phase 6: Admin UI Integration

• Policy Management UI

  • Visual policy editor
  • Policy list with status
  • Version history viewer
  • Policy testing interface

• Compliance UI

  • Report generation wizard
  • Evidence dashboard
  • Compliance status overview

⚙️ Configuration Example

# Policy-as-Code platform configuration
policy_platform:
  enabled: true
  
  # Policy Decision Point
  pdp:
    # Engine priority (first match wins, or combine)
    engines:
      - cedar
      - opa
      - native
      - mac
    combination_mode: "all_must_allow"  # all_must_allow | any_allow
    cache_decisions: true
    cache_ttl_seconds: 60
    
  # Decision auditing
  audit:
    enabled: true
    log_all_decisions: true
    log_allowed: true
    log_denied: true
    include_context: true
    retention_days: 365
    
    # SIEM integration
    siem:
      enabled: false
      type: "splunk"  # splunk | elasticsearch | webhook
      endpoint: "https://splunk.example.com:8088"
      token_env: "SIEM_TOKEN"
      
  # Compliance
  compliance:
    frameworks:
      - fedramp-moderate
      - hipaa
      - soc2-type2
    auto_evidence_collection: true
    report_schedule: "monthly"
    
  # JIT Access
  jit_access:
    enabled: true
    max_duration_hours: 8
    require_approval: true
    approver_roles: ["security-admin", "platform-admin"]
    notify_on_grant: true
    notify_on_use: true
    
  # Policy testing
  sandbox:
    enabled: true
    isolation_mode: "memory"
    test_data_path: "/etc/mcpgateway/test-data"

✅ Success Criteria

• Unified PDP: Single interface for Cedar, OPA, native RBAC, and MAC policies
• Decision Logging: 100% of access decisions logged with full context
• Compliance Reports: Automated FedRAMP, HIPAA, SOC2 report generation
• Policy Testing: Sandbox environment for safe policy testing
• Version Control: All policies versioned with rollback capability
• JIT Access: Temporary privilege elevation with automatic expiration
• Admin UI: Visual policy management and compliance dashboard
• Performance: Policy evaluation <10ms for 95th percentile
• Audit Export: SIEM integration for security monitoring

🏁 Definition of Done

• Unified PDP interface implemented
• Cedar, OPA, native, and MAC adapters functional
• Policy store with version control
• Comprehensive decision audit logging
• Compliance report generator (FedRAMP, HIPAA, SOC2)
• Policy testing sandbox
• JIT access system with approval workflow
• Admin UI for policy management
• Admin UI for compliance dashboard
• SIEM export integration
• 80%+ test coverage
• Documentation complete
• Code passes make verify checks

📝 Additional Notes

🔹 Policy Engines: The platform supports multiple policy engines that can work independently or in combination:

• Cedar: AWS-developed policy language, RBAC/ABAC focused
• OPA/Rego: CNCF-graduated, general-purpose policy engine
• Native RBAC: Built-in role-based access control ([FEATURE]: Centralized configurable RBAC/ABAC policy engine #2019)
• MAC (Bell-LaPadula): Mandatory access control for classified data ([EPIC][SECURITY]: Security clearance levels plugin - Bell-LaPadula MAC implementation #1245)

🔹 Compliance Frameworks Supported:

• FedRAMP (Low, Moderate, High)
• HIPAA Security Rule
• SOC2 Type II
• PCI-DSS
• ISO 27001
• NIST 800-53

🔹 Zero Trust Architecture: This platform implements Zero Trust principles:

• Never trust, always verify
• Least privilege access
• Continuous verification
• Assume breach mindset

🔹 Existing Plugins Integration: This epic integrates with:

• Cedar Plugin (plugins/external/cedar)
• OPA Plugin (plugins/external/opa)

🔗 Related Issues

Core Components (Part of this Epic)

• [FEATURE]: Centralized configurable RBAC/ABAC policy engine #2019 - Centralized configurable RBAC/ABAC policy engine
• [EPIC][SECURITY]: Security clearance levels plugin - Bell-LaPadula MAC implementation #1245 - Security Clearance Levels Plugin - Bell-LaPadula MAC
• [EPIC][PLUGIN]: Per-virtual-server plugin selection with multi-level RBAC #1247 - Per-Virtual-Server Plugin Selection with Multi-Level RBAC
• [EPIC][AUTH]: Agent and tool authentication and authorization plugin #1422 - Agent and Tool Authentication and Authorization Plugin
• [FEATURE][PLUGIN]: Create JWT claims and metadata extraction plugin #1439 - JWT claims and metadata extraction plugin
• [FEATURE][SECURITY]: Generic IP-based access control (allowlist) #536 - Generic IP-Based Access Control (allowlist)
• [FEATURE][AUTH]: Generic OIDC group to team mapping for SSO #2120 - Generic OIDC Group to Team mapping for SSO

Security Posture (Related Epic)

• [EPIC][SECURITY]: MCP server security posture assessment - Pre-deployment scanning and validation #2215 - MCP Server Security Posture Assessment

📚 References

• AWS Cedar
• Open Policy Agent
• Bell-LaPadula Model
• NIST 800-53 Controls
• FedRAMP Security Assessment Framework
• HIPAA Security Rule
• SOC2 Trust Services Criteria
• Google Zanzibar