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-suiteRun it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.
Contents
Discovered from sourceSkills 1
oscal-expert
You are the guide for OSCAL document authoring, validation, and conversion in this plugin. Your job:
- Help users pick the right OSCAL document type for their intent.
- Interpret
oscal validateerrors and propose fixes. - Explain how OSCAL integrates with the rest of the toolkit — especially
/grc-engineer:gap-assessment --output=oscal-ar, thefedramp-sspplugin, 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-arproduces 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
| Error | Meaning | Fix |
|---|---|---|
required property 'uuid' missing | every OSCAL object needs a UUID | generate with uuidgen and insert |
instance type (X) does not match schema type (Y) | wrong data type — usually a string vs array | check schema docs for that field |
enum value not allowed | you've used a value outside the allowed set (e.g. implementation-status) | consult nist.gov/OSCAL/concepts/ for the valid set |
additional property not allowed | FedRAMP/vendor namespacing required | use props with an ns URI, e.g. ns: "https://fedramp.gov/ns/oscal" |
oscal-version mismatch | your document says 1.0 but oscal-cli validates against 1.1.3 | update 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-sspplugin → takes FedRAMP DOCX SSP templates and produces OSCAL 1.2.0 SSP JSON. Pipe to/oscal:validatebefore 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-sspplugin. - 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, oryaml--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— success2— input file missing or unreadable5—oscalbinary not installed6— 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-arinto 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
-
Detects if
oscalis already onPATH. If so, records version + path and exits success. -
If
--from-sourceis passed (or no binary is available and Go is installed):git clone https://github.com/ethanolivertroy/oscal-cli ~/.local/share/claude-grc/tools/oscal-climake build- Symlinks the binary into
$PREFIX/bin
-
Otherwise, downloads the latest release binary for your platform from
gh release listunderethanolivertroy/oscal-cli. -
Runs
oscal --versionto verify. -
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
- No Go compiler and no release binary for platform: exit 5. Install Go or grab a binary manually from https://github.com/ethanolivertroy/oscal-cli/releases.
- Network unavailable: exit 2.
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— valid6— schema violation(s); details on stderr (or stdout JSON with--json)2— file not found / unreadable5—oscalbinary 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-sspplugin and thefedramp-docsMCP for spec lookups.
Sponsors
Details
- Marketplace
- GRCEngClub/claude-grc-engineering
- Source
- plugins/oscal
- Category
- Community
More from GRCEngClub/claude-grc-engineering
All 70- pbmmv0.1.0
- pci-dssv0.1.0
- poam-automationv0.1.0
- sg-mas-trmv0.1.0
- singapore-pdpav0.1.0
- slack-inspectorv0.1.0
- snowflake-inspectorv0.1.0
- soc2v0.1.0
- splunk-inspectorv0.1.0
- staterampv0.1.0
- teach-mev0.1.0
- tenable-inspectorv0.1.0
- testssl-inspectorv0.1.0
- trust-centerv0.1.0
- us-ccpav0.1.0
- us-exportv0.1.0
- us-finrav0.1.0
- us-hipaa-securityv0.1.0
- us-nerc-cipv0.1.0
- us-soxv0.1.0
- vault-kvv0.1.0
- wiz-inspectorv0.1.0
- academic-research-companionv0.1.0
- au-apra-cps-234v0.1.0
