williamzujkowski/OSCAL SSP Validator

Purpose & When-To-Use

Trigger conditions:

• You have an OSCAL System Security Plan (SSP) document in JSON, XML, or YAML format
• You need to verify schema compliance and structural validity
• You want to check profile alignment for control implementation
• You require cross-reference integrity validation for components and controls
• You need varying depth of validation (quick schema check vs. comprehensive audit)

Use this skill when:

• Integrating SSP documents into automated compliance pipelines
• Preparing SSP submissions for FedRAMP or other compliance frameworks
• Debugging SSP authoring or generation tools
• Conducting quality assurance on SSP documents before review

Pre-Checks

Time normalization:

NOW_ET = <NIST time.gov semantics, America/New_York, ISO-8601>
Example: 2025-10-25T21:04:34-04:00

Input validation:

• ssp_path must resolve to accessible file or reachable URL
• If file: check read permissions and non-zero size
• If URL: verify HTTPS and reachability (HEAD request)
• Document format must be detectable (.json, .xml, .yaml/.yml extension or MIME type)
• If profile specified: must be valid OSCAL profile identifier or resolvable path/URL
• strict must be boolean (default: false)

Schema freshness check:

• Verify OSCAL schema version in document metadata
• Current reference version: v1.1.2 (accessed 2025-10-25T21:04:34-04:00)
• Warn if schema version > 1.1.2 or < 1.0.0
• Schemas available at: https://github.com/usnistgov/OSCAL/tree/main/json/schema

Procedure

Tier 1: Fast Schema Validation (≤2k tokens)

Goal: Confirm well-formedness and basic schema compliance

Steps:

1. Load document

• Parse based on detected format (JSON/XML/YAML)
• Catch syntax errors; abort if malformed

1. Extract metadata

• Read metadata/version and metadata/oscal-version
• Identify document as SSP model type

1. Schema validation

• Fetch appropriate schema for OSCAL version + format
• Apply schema validator (JSON Schema for JSON/YAML, XSD for XML)
• Collect validation errors/warnings

1. Output quick report

• Status: valid, invalid, or error
• Error count and first 3 errors
• Schema version used

Stop condition: If document is malformed or has >10 schema errors, abort and report.

Tier 2: Profile Alignment + Citations (≤6k tokens)

Goal: Verify profile compliance and control implementation integrity

Steps (extends T1):

1. Profile resolution (if profile provided)

• Load or resolve profile document
• Extract required controls and parameters
• Compare against SSP control-implementation section

1. Control coverage check

• List all controls referenced in profile
• Verify each control has implementation statement in SSP
• Flag missing or incomplete implementations

1. Parameter validation

• Check parameter values against profile constraints
• Verify required parameters are set
• Validate data types and allowed values

1. Citation and source references

• NIST OSCAL SSP Model v1.1.2 (accessed 2025-10-25T21:04:34-04:00): https://pages.nist.gov/OSCAL-Reference/models/v1.1.2/system-security-plan/xml-reference/
• OSCAL Validation Concepts (accessed 2025-10-25T21:04:34-04:00): https://pages.nist.gov/OSCAL/learn/concepts/validation/
• OSCAL Layers of Validation - FedRAMP (accessed 2025-10-25T21:04:34-04:00): https://automate.fedramp.gov/documentation/general-concepts/oscal-layers-of-validation/
• NIST OSCAL GitHub Repository (accessed 2025-10-25T21:04:34-04:00): https://github.com/usnistgov/OSCAL

Output enhanced report:

• Profile alignment score (% controls implemented)
• Parameter validation results
• Control gap list

Tier 3: Deep Cross-Reference & Rationale (≤12k tokens)

Goal: Comprehensive integrity validation with detailed rationale

Steps (extends T2):

1. Component cross-reference validation

• Extract all component-definition UUIDs
• Verify all referenced components exist
• Check for orphaned components (defined but not used)
• Validate component-to-control mappings

1. Link integrity

• Validate all link/@href references
• Check internal UUID references (back-matter, responsible-parties)
• Verify external URLs are reachable (if strict mode)

1. Metadata consistency

• Check last-modified vs. published dates
• Verify party/role/location UUID references
• Validate responsible-party assignments

1. Generate rationale

• For each validation failure: explain constraint and fix suggestion
• Cite relevant OSCAL specification sections
• Provide example corrections

Decision Rules

• Abort threshold: >50 schema errors in T1 → stop, document is fundamentally broken
• Profile mismatch severity:
• strict=false: warn on missing controls
• strict=true: fail on any control gap
• Cross-reference tolerance:
• Missing internal UUIDs: always fail
• Unreachable external URLs: warn unless strict=true
• Tier escalation:
• T1 sufficient for schema-only validation
• T2 required if profile specified or control implementation needed
• T3 required for comprehensive audit or strict mode

Output Contract

JSON Report Schema:

json
{
  "validation_timestamp": "ISO-8601 timestamp",
  "ssp_path": "string",
  "oscal_version": "string",
  "tier": "1|2|3",
  "status": "valid|invalid|error",
  "summary": {
    "total_errors": "integer",
    "total_warnings": "integer",
    "schema_valid": "boolean",
    "profile_aligned": "boolean|null",
    "cross_refs_valid": "boolean|null"
  },
  "errors": [
    {
      "type": "schema|profile|cross-ref|metadata",
      "severity": "error|warning",
      "location": "JSONPath or XPath",
      "message": "string",
      "suggestion": "string|null"
    }
  ],
  "profile_report": {
    "controls_required": "integer",
    "controls_implemented": "integer",
    "coverage_percent": "float",
    "missing_controls": ["string"]
  },
  "sources": ["array of citation URLs with access dates"]
}

Markdown Summary Format:

markdown
# OSCAL SSP Validation Report

**Document:** `{ssp_path}`
**Timestamp:** {validation_timestamp}
**OSCAL Version:** {oscal_version}
**Status:** {status}

## Summary
- Errors: {total_errors}
- Warnings: {total_warnings}
- Schema Valid: {schema_valid}
- Profile Aligned: {profile_aligned}

## Details
{top 5 errors with suggestions}

## Sources
{clickable links with access dates}

Examples

Example 1: T1 validation of valid SSP

bash
# Input
ssp_path: "./my-ssp.json"
profile: null
strict: false

# Execution
1. Parse my-ssp.json → success
2. Extract metadata/oscal-version → "1.1.2"
3. Fetch JSON schema v1.1.2
4. Validate → 0 errors

# Output (JSON)
{
  "validation_timestamp": "2025-10-25T21:04:34-04:00",
  "ssp_path": "./my-ssp.json",
  "oscal_version": "1.1.2",
  "tier": "1",
  "status": "valid",
  "summary": {
    "total_errors": 0,
    "total_warnings": 0,
    "schema_valid": true
  },
  "errors": []
}

Quality Gates

Token budgets (mandatory):

• T1: ≤2,000 tokens (schema validation only)
• T2: ≤6,000 tokens (+ profile checks + 2-4 cited sources)
• T3: ≤12,000 tokens (+ cross-refs + rationale + examples)

Safety:

• No credential exposure in validation reports
• Sanitize file paths in error messages (remove sensitive directory names)
• Do not persist validation reports with PII/secrets

Auditability:

• All validation runs must log: timestamp, tier, status, error count
• Citation access dates must equal NOW_ET
• Schema version must be recorded in output

Determinism:

• Same SSP + profile + tier → identical validation result
• Schema fetch must use version-pinned URLs
• No random sampling or probabilistic checks

Resources

Official NIST OSCAL Documentation:

• System Security Plan Model Reference: https://pages.nist.gov/OSCAL/learn/concepts/layer/implementation/ssp/
• OSCAL Validation Concepts: https://pages.nist.gov/OSCAL/learn/concepts/validation/
• OSCAL v1.1.2 SSP XML Reference: https://pages.nist.gov/OSCAL-Reference/models/v1.1.2/system-security-plan/xml-reference/
• OSCAL GitHub Repository: https://github.com/usnistgov/OSCAL

Schemas:

• JSON Schema: https://github.com/usnistgov/OSCAL/tree/main/json/schema
• XML Schema: https://github.com/usnistgov/OSCAL/tree/main/xml/schema

Tools:

• OSCAL CLI (NIST): https://pages.nist.gov/OSCAL/resources/tools/
• FedRAMP OSCAL Layers of Validation: https://automate.fedramp.gov/documentation/general-concepts/oscal-layers-of-validation/

Profile Resolution Specification:

• https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/