Convert FedRAMP Rev 5 SSP DOCX templates to validated OSCAL 1.2.0 SSP JSON. Wraps ethanolivertroy/frdocx-to-froscal-ssp.

version
0.1.0
GitHub stars
436

Install

/plugin install fedramp-ssp@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

fedramp-ssp expert

You are the guide for turning FedRAMP Rev 5 Word-template SSPs into machine-readable OSCAL 1.2.0.

What FedRAMP SSP looks like

FedRAMP publishes three Word-template documents that CSPs fill in:

  1. SSP (main template) — system identification, authorization boundary, inventory, leveraged authorizations, roles, parties. Typically 60-80 pages.
  2. Appendix A (Moderate or High) — the 323 (Moderate) or 421 (High) NIST 800-53 Rev 5 control responses with FedRAMP-specific additional requirements. Each requirement has status, origination, and implementation narrative fields.
  3. Appendices B–N — data flow, inventory, separation of duties, IRP, privacy threshold, etc. This plugin does not convert these yet.

The DOCX→OSCAL pipeline here consumes the main SSP + Appendix A and produces an OSCAL 1.2.0 SSP JSON covering the most-critical content.

What the output contains

  • metadata: system name, authorization path, version, last-modified
  • system-characteristics: identification, authorization boundary, system information, data types (security objectives for confidentiality/integrity/availability)
  • system-implementation: users, components, leveraged authorizations, inventory items
  • control-implementation: 323 implemented-requirements, each with implementation status, control origination, responsible roles, and narrative by-component statements
  • back-matter: resources and references

The output uses FedRAMP-namespaced props (https://fedramp.gov/ns/oscal) for fields like implementation-status, control-origination, cloud deployment model.

When to use this plugin

  • First-time authoring: you've got FedRAMP templates filled in by your team and need to hand a machine-readable version to your 3PAO or AO.
  • Continuous compliance: re-run after every DOCX update and diff the OSCAL output — much easier than diffing 80-page Word documents.
  • FedRAMP 20X alignment: 20X workflows consume OSCAL directly; this is the bridge from traditional Rev 5 SSP authoring to 20X automation.
  • eMASS import: eMASS supports OSCAL imports for DoD environments.

When NOT to use this plugin

  • You're authoring from scratch with no DOCX source. Use Compliance Trestle for OSCAL-native authoring.
  • You need semantic verification against the profile (does this SSP actually implement Moderate?). Use Trestle or an AO review.
  • You want Appendix B-N conversion. Not supported yet; file an issue.

How this plugin composes with others

  • /oscal:validate — pass --validate to this plugin, or run /oscal:validate manually on the output.
  • /oscal:convert — convert the JSON output to XML for Compliance Trestle or to YAML for human review.
  • /grc-engineer:gap-assessment --output=oscal-ar — produces OSCAL Assessment Results. A full FedRAMP package is SSP + AR + POA&M; this plugin provides the SSP side.
  • Compliance Trestle skills — the OSCAL authored here round-trips cleanly through Trestle's workflow.

Common pitfalls

  • Placeholder text: FedRAMP DOCX templates have [CSP-specific: ...] placeholders. If your team hasn't filled them in, the pipeline propagates placeholder text into the OSCAL narratives. Review before submission.
  • Control Origination must be one of: sp-system, sp-corporate, customer-configured, customer-provided, inherited, shared. Values outside that set fail FedRAMP validation.
  • Leveraged authorization: if your system is on a leveraged cloud (AWS GovCloud, Azure Government), the SSP must declare the leveraging relationship. The default config assumes AWS GovCloud FedRAMP High P-ATO; override if you're on a different platform.
  • Version drift: the upstream tool currently targets OSCAL 1.2.0. /oscal:validate bundles 1.1.3. These are schema-compatible for the SSP subset used, but if you need strict 1.1.3, set oscal-version: "1.1.3" in the output or update the oscal-cli schema bundle.

Non-goals

  • Not a FedRAMP policy authoring tool: you still need your policies, procedures, and evidence. This generates the control-implementation narrative scaffolding from your DOCX inputs.
  • Not a control-effectiveness validator: producing a well-formed SSP doesn't mean the controls are effective. Use /grc-engineer:test-control + a 3PAO assessment.

Commands 2

/fedramp-ssp:convert

Runs the DOCX→OSCAL pipeline on a pair of FedRAMP Rev 5 SSP templates and emits a validated OSCAL 1.2.0 SSP JSON file.

How to run

bash plugins/fedramp-ssp/scripts/convert.sh \
  --ssp-docx=<path-to-FedRAMP-SSP-Template.docx> \
  --appendix-a-docx=<path-to-SSP-Appendix-A-Moderate.docx> \
  [--output=<path-to-ssp-output.json>] \
  [--validate]

Arguments

  • --ssp-docx=<path> (required) — official FedRAMP Rev 5 High/Moderate/Low LI-SaaS SSP template, filled in.
  • --appendix-a-docx=<path> (required) — FedRAMP Appendix A Moderate control responses document.
  • --output=<path> — where to write the OSCAL JSON (default: ./ssp-output.json).
  • --validate — after generation, run /oscal:validate on the result (requires the oscal plugin set up).

What the pipeline does

  1. Extract front matter from the main SSP DOCX: system identification, parties, roles, authorization boundary, data types, leveraged authorizations.
  2. Extract control responses from Appendix A: 323 implemented-requirements across 18 NIST SP 800-53 Rev 5 control families with FedRAMP-specific implementation narratives.
  3. Assemble an OSCAL 1.2.0 SSP document:
    • 9 components (this-system + 8 AWS infrastructure services)
    • 18 FedRAMP-standard roles, 7 parties, 3 locations, 3 user types
    • FedRAMP-namespaced props: implementation-status, control-origination, cloud deployment model
  4. Validate (optional) with oscal-cli — JSON-to-YAML round-trip must pass.

Where to get the DOCX templates

# Main SSP template (High/Moderate/Low/LI-SaaS)
curl -sLO "https://www.fedramp.gov/resources/templates/FedRAMP-High-Moderate-Low-LI-SaaS-Baseline-System-Security-Plan-%28SSP%29.docx"

# Appendix A Moderate
curl -sLO "https://www.fedramp.gov/resources/templates/FedRAMP-SSP-Appendix-A-Moderate-FedRAMP-Security-Controls.docx"

Both are published by fedramp.gov/resources/templates.

Typical output

fedramp-ssp:convert ✓
  source (SSP):       FedRAMP-SSP-Template.docx
  source (Appendix):  SSP-Appendix-A-Moderate.docx
  output:             ./ssp-output.json (783 KB)
  implemented:        323 requirements (18 families)
  narratives:         89 (0 placeholder)
  components:         9 (1 this-system + 8 AWS services)
  validation:         ✓ OSCAL 1.2.0 round-trip passes

Exit codes

  • 0 — success
  • 2 — missing or unreadable input DOCX
  • 3 — DOCX could not be parsed (malformed or not a FedRAMP template)
  • 4 — OSCAL assembly produced an output but validation failed
  • 5 — pipeline not installed (run /fedramp-ssp:setup)

Next steps

/oscal:validate ./ssp-output.json            # strict schema check
/oscal:convert ./ssp-output.json --to yaml    # human-readable review
# Hand to Compliance Trestle, eMASS, or FedRAMP 20X workflows.

Customization

The pipeline has config.json and narratives.json inside the tool directory that control defaults (AWS-centric components, leveraged authorization, narratives). Point a copy at your own overrides by setting FRDOCX_CONFIG=<path> and FRDOCX_NARRATIVES=<path> before running /fedramp-ssp:convert.

Non-goals

  • Not a substitute for authoring the DOCX: you still need to fill in the FedRAMP templates with your system's content. This plugin converts a filled-in DOCX.
  • Not a full 800-53 control generator: narratives that aren't provided default to the pipeline's canned text. Review and replace with organization-specific content before submission.

/fedramp-ssp:setup

Prepares the SSP DOCX→OSCAL pipeline. Clones ethanolivertroy/frdocx-to-froscal-ssp, installs its Python requirements into a dedicated virtualenv, and records the install path.

How to run

bash plugins/fedramp-ssp/scripts/setup.sh [--python=<python3-executable>]

What it does

  1. Detect Python ≥ 3.10. --python=/opt/homebrew/bin/python3.12 overrides.

  2. Clone/update ethanolivertroy/frdocx-to-froscal-ssp into ~/.local/share/claude-grc/tools/frdocx-to-froscal-ssp.

  3. Create a virtualenv at <tool-dir>/.venv and pip install -r requirements.txt (primarily python-docx).

  4. Verify that the entry-point script runs (python cli.py --help or equivalent).

  5. Warn (not fail) if Java 17 isn't available — it's only needed for optional oscal-cli validation inside the pipeline; the /oscal:validate command from this toolkit can fill that role.

  6. Write config:

    version: 1
    source: fedramp-ssp
    source_version: "0.1.0"
    python: "/opt/homebrew/bin/python3.12"
    venv: "~/.local/share/claude-grc/tools/frdocx-to-froscal-ssp/.venv"
    tool_dir: "~/.local/share/claude-grc/tools/frdocx-to-froscal-ssp"
    oscal_version: "1.2.0"
    

Typical output

fedramp-ssp:setup ✓
  python:      /opt/homebrew/bin/python3.12 (3.12.5)
  tool dir:    ~/.local/share/claude-grc/tools/frdocx-to-froscal-ssp
  venv:        ready (python-docx installed)
  java:        OpenJDK 17.0.11 (optional, available)
  config:      ~/.config/claude-grc/connectors/fedramp-ssp.yaml

Next:
  /fedramp-ssp:convert --ssp-docx=<path> --appendix-a-docx=<path>

Failure modes

  • Python < 3.10: exit 2. Install a newer Python or pass --python=<path>.
  • Network unreachable for git clone / pip: exit 2.
  • Java missing: warn only; the pipeline still produces OSCAL. Use /oscal:validate downstream instead of the tool's bundled validation step.

Sponsors

Details

Marketplace
GRCEngClub/claude-grc-engineering
Source
plugins/fedramp-ssp
Category
Community

More from GRCEngClub/claude-grc-engineering

All 70