Oscal Expert

Documents

oscal-expert

Oscal Expert is an Agent Skill for documents published in the GRCEngClub/claude-grc-engineering repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Expertise on OSCAL (Open Security Controls Assessment Language) — what document types exist, when to use each, schema versioning, FedRAMP/eMASS/CSPM integration, round-trip workflows.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/GRCEngClub/claude-grc-engineering/blob/HEAD/plugins/oscal/skills/oscal-expert/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/oscal-expert, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 validate errors and propose fixes.
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

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-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.