User Guide

Complete guide to using the OSCAL UX interface

Table of Contents

Getting Started Features API Automation Guide →How to Validate Documents How to Convert Document Formats How to Resolve Profiles How to Process Multiple Files How to Use Operation History How to Use the OSCAL Library How to Visualize OSCAL Documents How to Create System Authorizations How to Create and Use Service Account Tokens OSCAL Model Types Keyboard Shortcuts Troubleshooting Additional Resources

Getting Started

What is OSCAL UX?

OSCAL UX is a comprehensive web-based interface for working with OSCAL (Open Security Controls Assessment Language) documents. It provides a visual, user-friendly way to validate, convert, resolve, and process OSCAL content without needing command-line expertise.

Requirements

Java 11 or higher (installed via SDKMAN)
Maven 3.9 or higher (installed via SDKMAN)
Node.js 18 or higher
Modern web browser (Chrome, Firefox, Safari, Edge)

Accessibility

OSCAL UX is fully accessible and compliant with WCAG 2.1 Level AA and Section 508 standards:

Full keyboard navigation support (Tab, Enter, Escape)
Screen reader compatible (NVDA, JAWS, VoiceOver)
Skip navigation links for efficient browsing
High contrast and readable text
Semantic HTML and ARIA labels throughout

Features

✅ Document Validation

Validate OSCAL documents against official schemas to ensure compliance.

Supports all 7 OSCAL model types
Works with JSON, XML, and YAML formats
Real-time error detection with line numbers
Automatic format detection
Document preview with syntax highlighting

✅ Format Conversion

Convert OSCAL documents between XML, JSON, and YAML formats seamlessly.

Side-by-side preview of original and converted content
Automatic format detection from file extension
One-click download of converted files
Real-time conversion feedback

✅ Profile Resolution

Resolve OSCAL profiles into fully resolved catalogs with control selection and tailoring.

Automatic profile resolution with catalog imports
Preview resolved catalog before download
Supports all OSCAL profile features
Choose output format (JSON, XML, YAML)

✅ Batch Processing

Process multiple OSCAL files simultaneously with progress tracking.

Upload multiple files at once
Real-time progress tracking for each file
Bulk validation, conversion, or resolution
Download all results as a ZIP archive
Clear error reporting for failed operations

✅ Operation History

Track and manage all your OSCAL operations in one place.

View all past operations with timestamps
See success/failure status for each operation
Track operation duration and performance
Delete operations from history
Statistics dashboard with success rates

✅ OSCAL Library

Browse, share, and download example OSCAL documents from the community.

Upload OSCAL documents to share with the community
Browse and download example documents
Version control for uploaded documents
Search by type, tag, or keyword
View analytics and popular downloads

✅ Data Visualization

Explore and understand OSCAL documents through interactive visualizations.

Visual representation of catalog controls
Control family distribution charts
Interactive data exploration
Export visualization data
Support for all OSCAL model types

✅ Service Account Tokens

Generate JWT tokens for programmatic API access from external applications.

Create named service account tokens
Configurable expiration periods (1-3650 days)
Secure JWT-based authentication
Use tokens for CI/CD pipelines and automation
Full API access with service account tokens

✅ System Authorizations

Create professional system authorization documents using customizable templates.

Create reusable markdown templates with variables
Multi-step wizard for generating authorization documents
Link authorizations to System Security Plans (SSPs)
Live preview with variable substitution
Track authorization history and metadata
Search and filter authorizations by system

How to Validate Documents

Navigate to Validate
Click the "Validate" card on the dashboard.
Upload Your File
Drag and drop your OSCAL file onto the upload area, or click to browse. The format (XML, JSON, YAML) will be auto-detected from the file extension.
Select Model Type
Choose the appropriate OSCAL model type from the dropdown: Catalog, Profile, Component Definition, System Security Plan, Assessment Plan, Assessment Results, or Plan of Action and Milestones.
Validate
Click "Validate Document". The document will be checked against the OSCAL schema. Any errors or warnings will be displayed with line numbers and detailed messages.
Review Results
Click on any error to jump to that line in the document preview. A summary shows total errors and warnings detected.

How to Convert Document Formats

Navigate to Convert
Click the "Convert" card on the dashboard.
Upload Your File
Upload your OSCAL document. The source format will be auto-detected.
Select Target Format
Choose the format you want to convert to (XML, JSON, or YAML).
Convert
Click "Convert Document". The converted document will appear in a side-by-side view with the original, allowing you to compare them.
Download
Click "Download Converted" to save the converted file to your computer.

How to Resolve Profiles

Navigate to Resolve
Click the "Resolve" card on the dashboard.
Upload Your Profile
Upload an OSCAL profile document. The profile defines which controls to include and how to tailor them from source catalogs.
Select Output Format
Choose the format for the resolved catalog (XML, JSON, or YAML).
Resolve
Click "Resolve Profile". The system will fetch referenced catalogs, apply control selections and modifications, and generate a resolved catalog.
Download Resolved Catalog
Review the resolved catalog in the preview, then download it.

How to Process Multiple Files

Navigate to Batch
Click the "Batch" card on the dashboard.
Upload Multiple Files
Drag and drop multiple OSCAL files, or click to select multiple files from your computer.
Choose Operation Type
Select what you want to do: Validate, Convert, or Resolve.
Configure Settings
Set model types, formats, and other options depending on the operation type.
Process
Click "Process Files". Watch the progress in real-time as each file is processed.
Download Results
When complete, download all results as a ZIP file, or download individual files.

How to Use Operation History

Navigate to History
Click the "History" card on the dashboard.
View Statistics
See your operation statistics at the top: total operations, successful operations, failed operations, and overall success rate.
Browse Operations
Scroll through the table of past operations. Each entry shows the operation type, file name, status, model type, duration, and timestamp.
Delete Operations
Click the delete button on any operation to remove it from history. You'll be asked to confirm before deletion.
Navigate Pages
Use the pagination controls at the bottom to browse through older operations.

How to Use the OSCAL Library

Browsing the Library

Navigate to Library
Click the "Library" card on the dashboard.
Browse Items
View all available OSCAL documents in the library. Each card shows the title, type, tags, and download count.
Download Items
Click the "Download" button on any item to save it to your computer, or click the card to view detailed information.

Uploading to the Library

Go to Upload Tab
Click the "Upload" tab in the Library page.
Fill in Metadata
Provide a title, description, OSCAL type, and optional tags for your document.
Select File
Choose your OSCAL file (JSON, XML, or YAML format). The format will be auto-detected.
Upload
Click "Upload to Library". Your document will be added to the community library.

Searching the Library

Use the Search tab to filter library items by keyword, OSCAL type, or tag. The Analytics tab provides insights into library usage and popular downloads.

How to Visualize OSCAL Documents

Navigate to Visualize
Click the "Visualize" card on the dashboard.
Upload Your Document
Upload an OSCAL document (JSON, XML, or YAML). The format will be auto-detected.
Select Model Type
Choose the appropriate OSCAL model type. The visualization will be customized based on the document structure.
Generate Visualization
Click "Visualize Document". Interactive charts and graphs will be generated showing document structure, control families, and relationships.
Explore the Data
Interact with the visualizations to explore your OSCAL data. For catalogs, view control family distribution. For SSPs, see implementation status.
Export Data
Download the visualization data or export charts for presentations and reports.

How to Create System Authorizations

The Authorization feature allows you to create professional system authorization documents using customizable templates with variable substitution. Perfect for ATO (Authority to Operate) decisions, FedRAMP authorizations, and internal system approvals.

Creating Authorization Templates

Navigate to Authorizations
Click the "Authorizations" card on the dashboard with the ShieldCheck icon.
Go to Templates Tab
Click the "Templates" tab to view and manage authorization templates.
Create New Template
Click "Create New Template" to start creating a reusable template.
Enter Template Details
Provide a template name (e.g., "FedRAMP ATO Template" or "Internal Authorization").
Write Template Content with Variables
Use markdown formatting and insert variables using double curly braces. Variables can contain letters, numbers, hyphens, underscores, spaces, and special characters.
# System Authorization for {{ system_name }} **System Owner:** {{ system_owner }} **Environment:** {{ environment }} ## Authorization Decision This system is **{{ decision }}** for {{ environment }} operations. **Authorizing Official:** {{ authorizing_official }} **Date:** {{ authorization_date }} **Period:** {{ authorization_period }} ## Risk Level {{ risk_level }} ## Special Conditions {{ conditions }}
Preview Template
View the live preview on the right side. Variables are automatically detected and highlighted in amber. The list of variables appears below the editor.
Save Template
Click "Save Template" to save your template for reuse.

Creating an Authorization Document

Go to Authorizations Tab
Click the "Authorizations" tab and then "Create New Authorization".
Step 1: Select SSP
Choose a System Security Plan from your library. This links the authorization to a specific system.
Step 2: Choose Template
Select an authorization template. You'll see the template preview and list of variables that need to be filled.
Step 3: Fill Variable Values
Enter values for each variable. As you type, the preview on the right updates in real-time to show your completed document. All variables must be filled before proceeding.
Step 4: Review and Name
Review the final document, enter a name for this authorization, and click "Create Authorization" to save it.

Managing Authorizations

View Authorizations:

Browse all authorization documents in the Authorizations tab. Each card shows the authorization name, linked SSP, template used, and creation date.

Search:

Use the search box to find authorizations by name or filter by system.

Delete:

Click the delete button to remove an authorization. You'll be asked to confirm.

Variable Naming Best Practices

Supported Variable Formats:

{{ system_name }} - Letters, numbers, underscores, hyphens
{{ Low, Moderate, or High }} - Spaces and commas allowed
{{ Federal Agency/Office }} - Special characters allowed
{{ agency logo }} - Spaces for multi-word variables

Tips:

Use descriptive variable names that clearly indicate what should be filled in
Keep variable names concise but meaningful
Use consistent naming conventions across templates
Variables are case-sensitive: {{ Date }} ≠ {{ date }}

Example: FedRAMP Authorization Template

{{ agency logo }}

{{ Insert Date }}

To: {{ CSP System Owner Name }}

The {{ Federal Agency/Office }} has completed review of the
{{ Insert CSP and cloud service name }} system and grants
Authority to Operate based on categorization of
"{{ Low, Moderate, or High }}".

This authorization is valid for {{ authorization period }}
and is subject to {{ special conditions }}.

SIGNED:
{{ Authorizing Official }}
{{ Title }}
{{ Date }}

Common Use Cases

FedRAMP Authorizations:

Create formal ATO documents for cloud service providers seeking FedRAMP authorization.

Internal System Approvals:

Generate authorization documents for internal systems with standardized templates.

Conditional Authorizations:

Document ATOs with specific conditions, requirements, or limitations.

Authorization Renewals:

Track authorization periods and create renewal documents when needed.

How to Create and Use Service Account Tokens

Creating a Service Account Token

Navigate to Profile
Click your username in the top-right corner and select "Profile".
Scroll to Service Account Tokens
Find the "Service Account Tokens" section at the bottom of the profile page.
Enter Token Details
Provide a descriptive name (e.g., "CI/CD Pipeline") and set the expiration period in days (1-3650 days).
Generate Token
Click "Generate Service Account Token". The token will be displayed once and cannot be retrieved later.
Copy and Store Securely
Copy the token immediately and store it in a secure location such as a password manager or secrets vault. Never commit tokens to version control.

Using Service Account Tokens with the API

Service account tokens provide full API access and can be used for automation, CI/CD pipelines, and external applications.

Example: Validate a Document

curl -X POST http://localhost:8080/api/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "content": "{ \"catalog\": { ... } }",
    "modelType": "catalog",
    "format": "JSON",
    "fileName": "my-catalog.json"
  }'

Example: Convert Format

curl -X POST http://localhost:8080/api/convert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "content": "<catalog>...</catalog>",
    "fromFormat": "XML",
    "toFormat": "JSON",
    "modelType": "catalog"
  }'

Security Best Practices

Store tokens in environment variables or secure vaults
Use different tokens for different applications/environments
Set appropriate expiration periods based on usage
Rotate tokens regularly for better security
Never share tokens or commit them to source control
Revoke tokens immediately if compromised

API Documentation

For complete API documentation with all available endpoints, visit:

http://localhost:8080/swagger-ui/index.html

OSCAL Model Types

Catalog

Collection of security controls and control baselines

Profile

Selection and tailoring of controls from catalogs (can be resolved into a catalog)

Component Definition

Description of system components and their control implementations

System Security Plan (SSP)

Documentation of security implementation for a system

Assessment Plan

Plan for assessing system security controls

Assessment Results

Results from security control assessments

Plan of Action and Milestones (POA&M)

Remediation tracking for identified security issues

Keyboard Shortcuts

Tab

Navigate between interactive elements

Shift + Tab

Navigate backward

Enter

Activate buttons and links

Escape

Close dialogs and dropdowns

Space

Toggle checkboxes and select items

Arrow Keys

Navigate within dropdowns

Troubleshooting

Backend Not Responding

If you see connection errors, ensure the backend server is running:

cd front-end
./dev.sh

This will start both the Java backend (port 8080) and the Next.js frontend (port 3000).

Validation Errors

Read error messages carefully - they indicate what's wrong with your OSCAL document. Common issues include missing required fields, incorrect UUIDs, malformed structure, or wrong model type selected. Click on errors to jump to the problematic line in the preview.

Conversion Fails

Ensure your source document is valid OSCAL before attempting conversion. Use the Validate feature first to check for errors. Malformed documents may fail to convert.

Profile Resolution Fails

Profile resolution requires access to referenced catalogs. Ensure the catalog URIs in your profile are valid and accessible. The backend must be able to fetch these resources.

Large Files

The current upload limit is 10MB per file. For larger files, consider splitting them. Batch operations can handle multiple smaller files more efficiently than one large file.

Browser Compatibility

OSCAL UX works best on modern browsers (Chrome, Firefox, Safari, Edge). If you experience issues, try clearing your browser cache or using a different browser.

Additional Resources

API Documentation (Swagger UI)

Interactive API documentation for the OSCAL CLI backend

NIST OSCAL Website

Official OSCAL documentation and specifications from NIST

OSCAL Foundation

Community resources, tools, and ecosystem

OSCAL GitHub Repository

Source code, schemas, tools, and issue tracking

OSCAL Sample Content

Example OSCAL documents and catalogs for testing