OSCAL toolkit: validate and convert catalogs, profiles, SSPs, SAPs, SARs, POA&Ms, assessment results, component definitions. Wraps ethanolivertroy/oscal-cli.

version
0.1.0
GitHub stars
436

Install

/plugin install oscal@grc-engineering-suite

Run it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.

Contents

Discovered from source

Skills 1

oscal-expert

You are the guide for OSCAL document authoring, validation, and conversion in this plugin. Your job:

  1. Help users pick the right OSCAL document type for their intent.
  2. Interpret oscal validate errors and propose fixes.
  3. Explain how OSCAL integrates with the rest of the toolkit — especially /grc-engineer:gap-assessment --output=oscal-ar, the fedramp-ssp plugin, and downstream tools like Compliance Trestle, eMASS, and FedRAMP 20X.

The OSCAL model in one screen

OSCAL defines seven document types, all interlinked by UUID references:

 catalog         → list of controls (e.g., NIST 800-53)
    ▲
    │ imports
 profile         → baseline (a set of catalog controls + tailoring, e.g., FedRAMP Moderate)
    ▲
    │ imports
 ssp             → System Security Plan: how *this* system implements the profile
    ▲
    │ imports-ssp
 ap              → Assessment Plan: what the assessor will test
    │
    ▼
 ar              → Assessment Results: findings + observations from executing the AP
    │
    ▼
 poam            → Plan of Action and Milestones: remediation schedule for failed findings

 component-definition → reusable "this is how this product implements controls" catalog

When to use each

  • Catalog: almost never author new ones; consume NIST's.
  • Profile: you're defining a baseline (FedRAMP Moderate, DoD IL4, org-specific). Usually imports NIST 800-53 and tailors.
  • SSP: every system getting authorized. This is the big document.
  • AP / AR / POA&M: assessment artifacts. /grc-engineer:gap-assessment --output=oscal-ar produces AR-shaped output.
  • Component Definition: vendor publishing "here's how our product satisfies these controls." Great for reusing across customers.

Common validation errors and fixes

ErrorMeaningFix
required property 'uuid' missingevery OSCAL object needs a UUIDgenerate with uuidgen and insert
instance type (X) does not match schema type (Y)wrong data type — usually a string vs arraycheck schema docs for that field
enum value not allowedyou've used a value outside the allowed set (e.g. implementation-status)consult nist.gov/OSCAL/concepts/ for the valid set
additional property not allowedFedRAMP/vendor namespacing requireduse props with an ns URI, e.g. ns: "https://fedramp.gov/ns/oscal"
oscal-version mismatchyour document says 1.0 but oscal-cli validates against 1.1.3update oscal-version to 1.1.3

Integration with other plugins

  • /grc-engineer:gap-assessment --output=oscal-ar → emits minimal OSCAL Assessment Results. Validate with /oscal:validate; convert to XML for Compliance Trestle with /oscal:convert.
  • fedramp-ssp plugin → takes FedRAMP DOCX SSP templates and produces OSCAL 1.2.0 SSP JSON. Pipe to /oscal:validate before delivering to your FedRAMP PMO.
  • Compliance Trestle (ethanolivertroy/compliance-trestle-skills): IBM's OSCAL authoring toolchain. This plugin's output is designed to round-trip through Trestle.

OSCAL version note

The bundled schema in oscal-cli is 1.1.3. frdocx-to-froscal-ssp produces 1.2.0. These are schema-compatible for the SSP subset used, but declare "oscal-version": "1.1.3" in output if you need strict 1.1.3 compliance, or call /oscal:setup --from-source to get the latest schema bundle.

Non-goals

  • Not a catalog resolver: doesn't merge profile inheritance or flatten ITSM control sets.
  • Not an SSP authoring UI: use Trestle or the fedramp-ssp plugin.
  • Not a compliance verdict engine: validation checks structure, not semantics.

Commands 3

/oscal:convert

Converts an OSCAL document between JSON, XML, and YAML. The input format is auto-detected from file extension or content.

How to run

bash plugins/oscal/scripts/convert.sh <input> --to <json|xml|yaml> [--output <path>] [--overwrite]

Arguments

  • <input> — path to OSCAL document
  • --to <fmt> — target format: json, xml, or yaml
  • --output <path> — write to this path (otherwise stdout)
  • --overwrite — allow overwriting an existing output file

Example

# NIST publishes the 800-53 catalog as XML; convert to JSON for programmatic use:
curl -LO https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/xml/NIST_SP-800-53_rev5_catalog.xml
/oscal:convert NIST_SP-800-53_rev5_catalog.xml --to json --output nist-catalog.json

# Round-trip to YAML for human review:
/oscal:convert nist-catalog.json --to yaml --output nist-catalog.yaml

# Convert gap-assessment output to XML for Compliance Trestle import:
/oscal:convert gap-report.oscal-ar --to xml --output gap-report.xml

Round-trip fidelity

oscal-cli preserves all semantic content across format conversions. Whitespace and ordering may differ but the deserialized model is byte-equivalent. This is verified by the underlying tool's round-trip tests.

Exit codes

  • 0 — success
  • 2 — input file missing or unreadable
  • 5 — oscal binary not installed
  • 6 — input is not a recognized OSCAL document

When to use

  • Integrate with tools that want a specific format: some GRC platforms ingest only XML; others JSON. This plugin lets you keep authoring in whichever format your team prefers and export to whatever the downstream wants.
  • Move assessment results from /grc-engineer:gap-assessment --output=oscal-ar into OSCAL SAR consumers that only speak XML.
  • Human review of machine-authored OSCAL — YAML is usually the most readable.

/oscal:setup

Installs the OSCAL CLI binary (a fast Go rewrite of NIST's Java oscal-cli) and records its path in ~/.config/claude-grc/connectors/oscal.yaml.

How to run

bash plugins/oscal/scripts/setup.sh [--from-source] [--prefix=$HOME/.local]

What it does

  1. Detects if oscal is already on PATH. If so, records version + path and exits success.

  2. If --from-source is passed (or no binary is available and Go is installed):

    • git clone https://github.com/ethanolivertroy/oscal-cli ~/.local/share/claude-grc/tools/oscal-cli
    • make build
    • Symlinks the binary into $PREFIX/bin
  3. Otherwise, downloads the latest release binary for your platform from gh release list under ethanolivertroy/oscal-cli.

  4. Runs oscal --version to verify.

  5. Writes config:

    version: 1
    source: oscal
    source_version: "0.1.0"
    binary: "/Users/you/.local/bin/oscal"
    binary_version: "1.0.0"
    oscal_schema_version: "1.1.3"
    

Typical output

oscal:setup ✓
  binary:         /Users/you/.local/bin/oscal v1.0.0
  OSCAL schema:   1.1.3
  config:         ~/.config/claude-grc/connectors/oscal.yaml

Next:
  /oscal:validate <file>
  /oscal:convert  <file> --to json|xml|yaml

Failure modes

Safe to re-run

Yes.

/oscal:validate

Validates an OSCAL document against the NIST JSON schemas bundled with oscal-cli. Supports JSON, XML, and YAML input (XML/YAML are auto-converted internally for validation).

How to run

bash plugins/oscal/scripts/validate.sh <file> [--quiet] [--json]

Arguments

  • <file> — path to the OSCAL document to validate.
  • --quiet — only emit on failure.
  • --json — structured JSON output {ok: bool, errors: [...], schema_version: "1.1.3"} for CI pipelines.

What it validates

  • JSON schema conformance (structural + type)
  • Required fields present
  • Enum values valid
  • UUID format for all identifiers
  • OSCAL version declared and supported

Exit codes

  • 0 — valid
  • 6 — schema violation(s); details on stderr (or stdout JSON with --json)
  • 2 — file not found / unreadable
  • 5 — oscal binary not installed (run /oscal:setup)

Example

/oscal:validate gap-assessment-20260413/gap-report.oscal-ar

This checks that /grc-engineer:gap-assessment's OSCAL Assessment Results output is well-formed before handing it to downstream tooling (Compliance Trestle, eMASS, FedRAMP 20X).

Non-goals

  • Semantic validation (e.g., does this SSP actually align with its referenced catalog?). Use oscal-cli resolve (coming in a future release) or Compliance Trestle for that.
  • FedRAMP-specific constraint checking. For that, combine this with the fedramp-ssp plugin and the fedramp-docs MCP for spec lookups.

Sponsors

Details

Marketplace
GRCEngClub/claude-grc-engineering
Source
plugins/oscal
Category
Community

More from GRCEngClub/claude-grc-engineering

All 70