Custom Frameworks

The pretorin frameworks command group supports authoring, validating, and uploading custom and forked compliance frameworks through the platform’s revision-lifecycle endpoints.

The canonical artifact is unified.json. _index.json is not an upload format — it’s an internal index file used elsewhere in the data pipeline, but the platform’s revision lifecycle expects the full unified.json.

End-to-end workflow

init-custom ──► (edit) ──► validate-custom ──► upload-custom [--publish] ──► revisions
                                                          │
build-custom ◄────── (OSCAL or custom catalog as input) ──┘

Starting from scratch

Scaffold a minimal valid unified.json:

pretorin frameworks init-custom acme-soc2-tailored
# → writes unified.json with one sample family + one sample control

Edit the file, fill in your metadata, families, and controls, then run a local pre-flight check:

pretorin frameworks validate-custom unified.json

The bundled JSON Schema validator catches structural errors fast. The platform runs the authoritative validator on upload — additional issues may surface there.

Starting from OSCAL

Already have an OSCAL catalog? Convert it to unified.json:

pretorin frameworks build-custom my-oscal-catalog.json -f acme-iso27001 -o unified.json

The CLI auto-detects the input shape. OSCAL → unified preserves the _oscal blocks for lossless regeneration; you can round-trip back via export-oscal.

Starting from a custom catalog

Many compliance catalogs ship in custom (non-OSCAL) JSON shapes — control_families + controls, CIS-style nested safeguards, ISO control_themes, PCI-DSS, CSA-CCM domains, NIST AI RMF governance requirements, FIPS 140-3, DISA STIG wrappers, MITRE ATLAS, and more.

build-custom recognizes 12 known custom shapes and normalizes them all to unified.json:

pretorin frameworks build-custom catalog.json -f acme-soc2 -o unified.json

If the input shape isn’t recognized, the CLI tells you which shapes are supported. Use init-custom to scaffold instead and copy your data over manually.

build-custom runs the local schema validator on the result and exits 1 when it fails — but it writes the output file either way, and prints (or returns, in --json mode) the exact paths and messages. Fix them in place and re-run validate-custom rather than rebuilding from the source catalog.

Uploading

Upload a draft revision to the platform:

pretorin frameworks upload-custom unified.json

The platform validates synchronously. On a validation failure (HTTP 400) the CLI renders the platform’s structured validation_report as a readable table — you’ll see exact paths and messages for what to fix.

To upload and publish in one step:

pretorin frameworks upload-custom unified.json --publish

You can override the framework ID baked into the artifact and add a version label:

pretorin frameworks upload-custom unified.json -f acme-soc2-v2 -v "2026-Q1"

Linked forks

Fork a Pretorin-managed framework into your own draft. The platform records the lineage so you can rebase later when upstream advances.

pretorin frameworks fork-framework nist-800-53-r5 acme-nist-tailored
pretorin frameworks fork-framework fedramp-moderate acme-fedramp-mod -v initial

The fork starts as a draft anchored on the upstream’s current revision. Edit the resulting unified.json (export it from the platform UI or use revisions to find the draft), then re-upload via upload-custom.

Rebasing a fork

When upstream has advanced and you want to bring your fork forward:

pretorin frameworks rebase-fork acme-nist-tailored

The platform creates a fresh draft anchored on the latest upstream. You resolve any divergence locally and re-upload.

Listing revisions

See all drafts and published revisions for a framework:

pretorin frameworks revisions acme-nist-tailored

Exporting OSCAL

Regenerate an OSCAL catalog from a unified artifact:

pretorin frameworks export-oscal unified.json -o catalog.json

When the unified artifact retains the _oscal blocks (i.e., it was originally converted from OSCAL via build-custom), regeneration is lossless — props, parts, links, and back-matter are restored verbatim.

Command reference

All commands respect the global --json flag for machine-readable output.

-f means two different things. On init-custom it is the short form of --force; on build-custom and upload-custom it is the short form of --framework-id. build-custom and export-oscal have no short form for --force at all. Spell the long flag out in scripts.

Output paths

The three local commands that write a file default to a fixed name in the current directory and refuse to overwrite it unless you pass --force: init-custom and build-custom write unified.json, export-oscal writes catalog.json. Pass --output to write somewhere else.

Version labels

--version-label is an optional free-text label sent alongside the artifact and recorded on the revision the platform creates. It is a separate field from the framework’s own version inside unified.json — setting one does not change the other. Use it to tag a draft so revisions output is readable:

pretorin frameworks upload-custom unified.json -v v1.2 --publish
pretorin frameworks fork-framework fedramp-moderate acme-fedramp-mod -v initial
pretorin frameworks rebase-fork acme-fedramp-mod -v rebase-2026Q1

Omit it and the revision is created unlabeled.

Notes for tool authors

The vendored conversion and validation primitives are exposed at pretorin.frameworks and can be imported directly:

from pretorin.frameworks import (
    custom_to_unified,
    oscal_to_unified,
    unified_to_oscal,
)
from pretorin.frameworks.validate import validate_unified
from pretorin.frameworks.templates import minimal_unified

These are pure-data functions — no I/O, no platform calls. Good for embedding in CI pipelines, agent tools, or your own automation.