Skip to content

GovOps: MVP ‐ OSCAL Compass

Jump to bottom
Michael Schwartz edited this page Nov 20, 2025 · 1 revision

OSCAL Compass Tools - MVP Design Requirements

Overview

This document defines the detailed requirements for integrating OSCAL Compass tools into the Agama GovOps MVP. OSCAL Compass provides compliance-as-code capabilities through compliance-trestle (agile authoring) and compliance-to-policy (C2P) tools, enabling organizations to manage compliance artifacts using Git-based workflows and connect compliance controls to policy enforcement.

Background

OSCAL Compass is a CNCF sandbox project that provides:

  • compliance-trestle: Agile authoring tools for creating and managing OSCAL artifacts (catalogs, profiles, component definitions) using markdown/CSV with automatic JSON generation
  • compliance-to-policy (C2P): Tools for pushing policies to systems and pulling assessment results
  • Git-based workflows: Version-controlled compliance artifact management with automated distribution

MVP Scope

The MVP focuses on integrating OSCAL Compass tools to enable:

  1. Component Definition Builder: Minimal UI for mapping Cedar policies to OSCAL controls
  2. Agile Authoring Integration: Basic support for markdown-based OSCAL content editing
  3. Evidence Export: Basic export of compliance mappings in CSV/JSON formats

Architecture Integration

graph TB
    subgraph AgamaLab["Agama Lab Frontend"]
        ComplianceUI[Compliance Section UI]
        ComponentDefBuilder[Component Definition Builder]
        EvidenceExport[Evidence Export]
    end
    
    subgraph AgamaAPI["Agama Lab API"]
        ComplianceEngine[Compliance Engine]
        OSCALManager[OSCAL Manager]
    end
    
    subgraph CompassTools["OSCAL Compass Tools"]
        TrestleEngine[compliance-trestle Engine]
        C2PTools[C2P Tools]
    end
    
    subgraph Storage["Storage"]
        GitHub[GitHub Repositories]
        PolicyStore[Policy Store]
    end
    
    ComplianceUI --> ComplianceEngine
    ComponentDefBuilder --> OSCALManager
    EvidenceExport --> OSCALManager
    
    ComplianceEngine --> OSCALManager
    OSCALManager --> TrestleEngine
    OSCALManager --> C2PTools
    
    TrestleEngine --> GitHub
    OSCALManager --> PolicyStore
    C2PTools --> PolicyStore
    
    style ComplianceUI fill:#e8f5e9
    style TrestleEngine fill:#e3f2fd
    style C2PTools fill:#fff4e1
Loading

Requirements

REQ-COMP-001: Component Definition Builder

User Story: As a Compliance_Manager, I want to create OSCAL component definitions that map Cedar policies to compliance controls, so that I can demonstrate how governance policies satisfy regulatory requirements.

Functional Requirements

  1. Component Definition Creation

    • THE Component Definition Builder SHALL provide a UI for creating new OSCAL component definitions
    • THE Component Definition Builder SHALL allow users to specify component metadata (title, description, type, version)
    • THE Component Definition Builder SHALL support linking to existing OSCAL profiles
    • THE Component Definition Builder SHALL validate component definition structure against OSCAL schema

  2. Policy-to-Control Mapping

    • THE Component Definition Builder SHALL allow users to select Cedar policies from the Policy Store
    • THE Component Definition Builder SHALL allow users to select OSCAL controls from linked profiles
    • THE Component Definition Builder SHALL create mappings between policies and controls
    • THE Component Definition Builder SHALL support multiple policies mapping to a single control
    • THE Component Definition Builder SHALL support a single policy mapping to multiple controls

  3. Implementation Details

    • THE Component Definition Builder SHALL allow users to add implementation descriptions for each policy-control mapping
    • THE Component Definition Builder SHALL support adding rationale statements explaining why a policy satisfies a control
    • THE Component Definition Builder SHALL allow users to specify control parameters and their values

  4. Validation and Error Handling

    • THE Component Definition Builder SHALL validate that all required OSCAL fields are present
    • THE Component Definition Builder SHALL validate that referenced policies exist in the Policy Store
    • THE Component Definition Builder SHALL validate that referenced controls exist in the linked profile
    • THE Component Definition Builder SHALL display clear error messages for validation failures

Technical Requirements

  • Component definitions SHALL be stored in OSCAL JSON format
  • Component definitions SHALL be version-controlled in GitHub repositories
  • Component definitions SHALL reference policies by unique identifier
  • Component definitions SHALL reference controls using standard OSCAL control identifiers

Acceptance Criteria

  1. WHEN a Compliance_Manager creates a component definition, THE system SHALL generate valid OSCAL JSON
  2. WHEN a Compliance_Manager maps a policy to a control, THE system SHALL create a valid OSCAL implemented-requirement
  3. WHEN a Compliance_Manager saves a component definition, THE system SHALL commit it to GitHub
  4. WHERE validation fails, THE system SHALL prevent saving and display specific error messages

REQ-COMP-002: Agile Authoring Integration

User Story: As a Compliance_Manager, I want to edit OSCAL component definitions using markdown or CSV formats, so that I can manage compliance artifacts in a more accessible format.

Functional Requirements

  1. Markdown/CSV Editing Support

    • THE Agile Authoring Integration SHALL support editing component definitions in CSV format
    • THE Agile Authoring Integration SHALL provide a CSV template for component definition creation
    • THE Agile Authoring Integration SHALL convert CSV input to OSCAL JSON using compliance-trestle
    • THE Agile Authoring Integration SHALL validate CSV structure before conversion

  2. Trestle Engine Integration

    • THE system SHALL integrate with compliance-trestle for CSV-to-OSCAL conversion
    • THE system SHALL use trestle's validation capabilities to ensure OSCAL compliance
    • THE system SHALL handle trestle conversion errors and display user-friendly messages

  3. Bidirectional Conversion

    • THE system SHALL support converting OSCAL JSON to CSV for editing
    • THE system SHALL preserve all data during JSON-to-CSV and CSV-to-JSON conversions
    • THE system SHALL maintain mapping relationships during conversion

Technical Requirements

  • CSV format SHALL follow compliance-trestle CSV schema for component definitions
  • Conversion SHALL use compliance-trestle Python library or API
  • CSV files SHALL be stored alongside OSCAL JSON in GitHub repositories
  • Conversion SHALL be performed server-side for security and consistency

Acceptance Criteria

  1. WHEN a Compliance_Manager uploads a CSV file, THE system SHALL convert it to valid OSCAL JSON
  2. WHEN a Compliance_Manager edits a CSV file, THE system SHALL update the corresponding OSCAL JSON
  3. WHERE CSV conversion fails, THE system SHALL display specific line and column errors
  4. WHERE trestle validation fails, THE system SHALL prevent saving and show validation errors

REQ-COMP-003: Profile and Catalog Management

User Story: As a Compliance_Manager, I want to import and link OSCAL profiles and catalogs, so that I can reference standard compliance frameworks like NIST 800-53.

Functional Requirements

  1. Catalog Import

    • THE system SHALL support importing OSCAL catalogs from external sources (e.g., NIST OSCAL Content)
    • THE system SHALL support importing catalogs from GitHub repositories
    • THE system SHALL validate imported catalogs against OSCAL schema
    • THE system SHALL store imported catalogs in GitHub repositories

  2. Profile Import and Creation

    • THE system SHALL support importing OSCAL profiles from external sources
    • THE system SHALL support creating profiles by selecting controls from catalogs
    • THE system SHALL support linking profiles to component definitions
    • THE system SHALL validate profile structure and control references

  3. Catalog and Profile Browsing

    • THE system SHALL provide a UI for browsing available catalogs
    • THE system SHALL provide a UI for browsing controls within catalogs
    • THE system SHALL provide a UI for browsing profiles and their selected controls
    • THE system SHALL support searching controls by ID, title, or description

Technical Requirements

  • Catalogs and profiles SHALL be stored in OSCAL JSON format
  • Catalogs and profiles SHALL be version-controlled in GitHub repositories
  • The system SHALL support NIST 800-53 Rev 5 catalog and profiles
  • The system SHALL support custom catalogs and profiles

Acceptance Criteria

  1. WHEN a Compliance_Manager imports a catalog, THE system SHALL validate and store it
  2. WHEN a Compliance_Manager creates a profile, THE system SHALL generate valid OSCAL JSON
  3. WHEN a Compliance_Manager links a profile to a component definition, THE system SHALL validate control references
  4. WHERE catalog/profile import fails, THE system SHALL display specific validation errors

REQ-COMP-004: Evidence Export

User Story: As a Compliance_Manager, I want to export compliance evidence in standard formats, so that I can share compliance mappings with auditors and stakeholders.

Functional Requirements

  1. CSV Export

    • THE Evidence Export SHALL support exporting component definitions to CSV format
    • THE CSV export SHALL include all policy-to-control mappings
    • THE CSV export SHALL include implementation details and rationale
    • THE CSV export SHALL be compatible with compliance-trestle CSV format

  2. JSON Export

    • THE Evidence Export SHALL support exporting component definitions to OSCAL JSON format
    • THE JSON export SHALL be valid OSCAL and pass schema validation
    • THE JSON export SHALL include all metadata and relationships

  3. Report Generation

    • THE Evidence Export SHALL generate human-readable reports showing policy-to-control mappings
    • THE reports SHALL include control coverage statistics
    • THE reports SHALL be exportable as PDF or Markdown

Technical Requirements

  • CSV exports SHALL follow compliance-trestle CSV schema
  • JSON exports SHALL be valid OSCAL component-definition documents
  • Exports SHALL include all referenced policies and controls
  • Exports SHALL be downloadable as files

Acceptance Criteria

  1. WHEN a Compliance_Manager exports to CSV, THE system SHALL generate a valid CSV file
  2. WHEN a Compliance_Manager exports to JSON, THE system SHALL generate valid OSCAL JSON
  3. WHEN a Compliance_Manager downloads an export, THE file SHALL be complete and valid
  4. WHERE export fails, THE system SHALL display error messages

REQ-COMP-005: GitHub Integration for OSCAL Artifacts

User Story: As a Compliance_Manager, I want OSCAL artifacts stored in GitHub, so that I can leverage version control and collaboration features.

Functional Requirements

  1. Repository Management

    • THE system SHALL create GitHub repositories for component definitions
    • THE system SHALL organize OSCAL artifacts in standard directory structures
    • THE system SHALL support multiple component definitions in separate repositories
    • THE system SHALL maintain develop and main branches for agile authoring workflows

  2. Version Control

    • THE system SHALL commit OSCAL artifacts to GitHub on save
    • THE system SHALL create releases when component definitions are published
    • THE system SHALL maintain version history for all OSCAL artifacts
    • THE system SHALL support semantic versioning for component definitions

  3. Agile Authoring Workflow

    • THE system SHALL support develop branch for work-in-progress changes
    • THE system SHALL support main branch for published releases
    • THE system SHALL trigger automated OSCAL validation on commits
    • THE system SHALL support pull request workflows for review

Technical Requirements

  • GitHub repositories SHALL follow compliance-trestle directory structure
  • Commits SHALL include meaningful commit messages
  • Releases SHALL be tagged with semantic versions
  • GitHub Actions SHALL be configured for automated validation

Acceptance Criteria

  1. WHEN a Compliance_Manager saves a component definition, THE system SHALL commit to GitHub
  2. WHEN a Compliance_Manager publishes a component definition, THE system SHALL create a GitHub release
  3. WHERE GitHub operations fail, THE system SHALL display error messages and allow retry
  4. WHERE validation fails in CI/CD, THE system SHALL prevent merge to main branch

REQ-COMP-006: Policy-Control Mapping UI

User Story: As a Compliance_Manager, I want an intuitive UI for mapping policies to controls, so that I can efficiently create compliance mappings.

Functional Requirements

  1. Mapping Interface

    • THE Mapping UI SHALL display a list of available Cedar policies
    • THE Mapping UI SHALL display a list of controls from the linked profile
    • THE Mapping UI SHALL allow drag-and-drop or click-to-map interactions
    • THE Mapping UI SHALL show existing mappings visually

  2. Mapping Details

    • THE Mapping UI SHALL allow editing implementation descriptions
    • THE Mapping UI SHALL allow adding rationale statements
    • THE Mapping UI SHALL allow specifying control parameters
    • THE Mapping UI SHALL show policy details when mapping

  3. Mapping Validation

    • THE Mapping UI SHALL validate that policies exist before mapping
    • THE Mapping UI SHALL validate that controls exist in the profile
    • THE Mapping UI SHALL prevent duplicate mappings
    • THE Mapping UI SHALL show validation errors in real-time

Technical Requirements

  • UI SHALL be responsive and work on desktop browsers
  • UI SHALL provide keyboard shortcuts for common actions
  • UI SHALL support undo/redo for mapping operations
  • UI SHALL auto-save draft mappings

Acceptance Criteria

  1. WHEN a Compliance_Manager maps a policy to a control, THE system SHALL create the mapping immediately
  2. WHEN a Compliance_Manager views mappings, THE system SHALL display all relationships clearly
  3. WHERE mapping validation fails, THE system SHALL highlight errors and prevent saving
  4. WHERE auto-save succeeds, THE system SHALL preserve work without explicit save

REQ-COMP-007: Control Coverage Analysis

User Story: As a Compliance_Manager, I want to see which controls are covered by policies, so that I can identify compliance gaps.

Functional Requirements

  1. Coverage Visualization

    • THE system SHALL display a coverage report showing mapped vs. unmapped controls
    • THE system SHALL show coverage percentage per control family
    • THE system SHALL highlight controls with no policy mappings
    • THE system SHALL show controls with multiple policy mappings

  2. Gap Analysis

    • THE system SHALL identify controls in the profile with no policy mappings
    • THE system SHALL suggest policies that might satisfy unmapped controls
    • THE system SHALL calculate overall compliance coverage percentage
    • THE system SHALL export gap analysis reports

Technical Requirements

  • Coverage calculations SHALL be performed server-side
  • Coverage data SHALL be cached for performance
  • Coverage reports SHALL update in real-time as mappings change

Acceptance Criteria

  1. WHEN a Compliance_Manager views coverage, THE system SHALL display accurate coverage statistics
  2. WHEN a Compliance_Manager views gaps, THE system SHALL list all unmapped controls
  3. WHERE coverage changes, THE system SHALL update reports immediately
  4. WHERE gap analysis is exported, THE report SHALL be complete and accurate

Data Models

Component Definition Structure

component-definition:
  uuid: string
  metadata:
    title: string
    version: string
    oscal-version: string
  components:
    - uuid: string
      type: string (e.g., "service", "validation")
      title: string
      description: string
      control-implementations:
        - uuid: string
          source: string (profile reference)
          description: string
          implemented-requirements:
            - uuid: string
              control-id: string (e.g., "ac-3")
              description: string
              statements:
                - statement-id: string
                  uuid: string
                  description: string
                  by-components:
                    - component-uuid: string
                      uuid: string
                      description: string
                      props:
                        - name: string
                          value: string (policy reference)

Policy-Control Mapping

mapping:
  policy-id: string (Cedar policy identifier)
  control-id: string (OSCAL control identifier)
  implementation-description: string
  rationale: string
  parameters:
    - name: string
      value: string

Integration Points

compliance-trestle Integration

  1. CSV-to-OSCAL Conversion

    • Use trestle's csv-to-oscal-cd task for component definition conversion
    • Validate CSV structure before conversion
    • Handle trestle validation errors

  2. OSCAL Validation

    • Use trestle's validation capabilities
    • Validate against OSCAL schemas
    • Report validation errors to users

  3. Agile Authoring Workflows

    • Support trestle's directory structure
    • Support develop/main branch workflow
    • Integrate with trestle's release management

GitHub Integration

  1. Repository Structure

    component-definitions/
  {component-name}/
    component-definition.json
    data/
      {component-name}.csv
      csv-to-oscal-cd.config

  2. Workflow Automation

    • GitHub Actions for CSV-to-OSCAL conversion
    • Automated validation on commits
    • Release creation on main branch merges

User Interface Requirements

Component Definition Builder UI

graph TB
    A[Component Definition Builder] --> B[Component Metadata Form]
    A --> C[Profile Selector]
    A --> D[Policy-Control Mapping Interface]
    A --> E[Implementation Details Editor]
    A --> F[Save/Export Actions]
    
    B --> B1[Title Input]
    B --> B2[Description Input]
    B --> B3[Version Input]
    
    C --> C1[Profile List]
    C --> C2[Control Browser]
    
    D --> D1[Policy List]
    D --> D2[Control List]
    D --> D3[Mapping Canvas]
    
    E --> E1[Implementation Description]
    E --> E2[Rationale Editor]
    E --> E3[Parameters Editor]
    
    F --> F1[Save to GitHub]
    F --> F2[Export CSV]
    F --> F3[Export JSON]
Loading

Key UI Components

  1. Component Metadata Form

    • Title, description, version fields
    • Component type selector
    • Profile link selector

  2. Policy-Control Mapping Interface

    • Split view: policies on left, controls on right
    • Drag-and-drop or click-to-map
    • Visual indicators for mapped/unmapped items
    • Search and filter capabilities

  3. Implementation Details Panel

    • Rich text editor for descriptions
    • Rationale statement editor
    • Parameter value inputs
    • Policy reference display

  4. Coverage Dashboard

    • Coverage percentage display
    • Control family breakdown
    • Gap analysis visualization
    • Export options

API Requirements

Component Definition API

POST /api/v1/compliance/component-definitions
  - Create new component definition
  - Body: Component definition metadata
  - Response: Component definition with UUID

GET /api/v1/compliance/component-definitions/{id}
  - Get component definition by ID
  - Response: Full OSCAL component definition

PUT /api/v1/compliance/component-definitions/{id}
  - Update component definition
  - Body: Updated component definition
  - Response: Updated component definition

POST /api/v1/compliance/component-definitions/{id}/mappings
  - Create policy-control mapping
  - Body: Mapping details
  - Response: Created mapping

GET /api/v1/compliance/component-definitions/{id}/coverage
  - Get coverage analysis
  - Response: Coverage statistics and gaps

POST /api/v1/compliance/component-definitions/{id}/export
  - Export component definition
  - Query params: format (csv|json)
  - Response: File download

Trestle Integration API

POST /api/v1/compliance/trestle/csv-to-oscal
  - Convert CSV to OSCAL JSON
  - Body: CSV file or content
  - Response: OSCAL JSON or validation errors

POST /api/v1/compliance/trestle/validate
  - Validate OSCAL document
  - Body: OSCAL JSON
  - Response: Validation results

Error Handling

Validation Errors

  • OSCAL Schema Validation: Display specific field and path errors
  • Control Reference Validation: Show which controls are missing or invalid
  • Policy Reference Validation: Show which policies don't exist
  • CSV Format Validation: Show line and column numbers for errors

GitHub Integration Errors

  • Authentication Errors: Prompt for token refresh
  • Repository Access Errors: Display permission issues
  • Commit Errors: Allow retry with error details
  • Network Errors: Queue operations for retry

Performance Requirements

  • Component definition loading: < 2 seconds
  • Mapping creation: < 500ms
  • Coverage calculation: < 1 second
  • CSV-to-OSCAL conversion: < 5 seconds for typical files
  • Export generation: < 3 seconds

Security Requirements

  • Component definitions SHALL be stored in user-accessible GitHub repositories
  • Access control SHALL be managed through GitHub permissions
  • OSCAL artifacts SHALL not contain sensitive policy details
  • Export files SHALL be generated server-side to prevent data leakage

Testing Requirements

Unit Tests

  • Component definition creation and validation
  • Policy-control mapping logic
  • CSV-to-OSCAL conversion
  • Coverage calculation algorithms

Integration Tests

  • Trestle engine integration
  • GitHub API integration
  • End-to-end mapping workflow
  • Export functionality

Acceptance Tests

  • User can create component definition
  • User can map policies to controls
  • User can export evidence
  • User can view coverage analysis

Future Enhancements (Out of MVP Scope)

  1. C2P Integration: Push policies to systems and pull assessment results
  2. Assessment Results Processing: Convert XCCDF results to OSCAL Assessment Results
  3. Compliance Posture Calculation: Automated compliance posture from assessment results
  4. Multi-Framework Mapping: Map NIST 800-53 results to other frameworks (HIPAA, GDPR, etc.)
  5. Automated Evidence Collection: Integration with evidence fetchers
  6. Advanced Reporting: Custom report templates and dashboards
  7. Collaborative Workflows: Multi-user editing with conflict resolution
  8. Profile Builder UI: Visual interface for creating profiles from catalogs

Dependencies

  • compliance-trestle Python library or API
  • OSCAL schema definitions
  • GitHub API access
  • Policy Store API access
  • Cedar policy identifiers

References

Clone this wiki locally