Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

OSCAL Artifacts

The oscal artifacts command group lists and downloads validated OSCAL export artifacts — system security plans (SSP), assessment plans (SAP) and results (SAR), POA&Ms, and component definitions — that the Pretorin platform generates and validates for a system.

These are read-only over the public API: artifact generation stays on the platform (app surface). The CLI’s job is the consumer side — listing what exists and downloading the latest validated package, which is exactly what a CI/CD machine-readable export pipeline (e.g. the FedRAMP RFC-0024 flow) needs.

Not the same as pretorin frameworks export-oscal. That command converts a unified framework catalog to/from OSCAL catalog format. This group manages generated, document-level export artifacts for a system.

Only artifacts with generation_state = succeeded and validation_status = valid are returned — every listed artifact is downloadable and has passed validation. Authentication uses an API token with READ scope.

List Artifacts

# All validated artifacts for the active system
pretorin oscal artifacts list

# Filter by type and framework
pretorin oscal artifacts list --type ssp
pretorin oscal artifacts list --type sar --framework fedramp-moderate

# Explicit system, paginated
pretorin oscal artifacts list --system "My System" --limit 100 --offset 0
OptionDescription
--type / -tFilter by type: ssp, sap, sar, poam, component_definition, bundle
--framework / -fFilter by framework ID
--assessment / -aFilter by assessment ID
--system / -sSystem name or ID (uses active context if unset)
--limit / -lPage size, 1–100 (default 50)
--offsetPagination offset

Show Artifact Detail

pretorin oscal artifacts show <artifact_id>

Shows full metadata — oscal_version, generator_version, file size, checksum_sha256 — plus the two-tier validation report (tier 1 model validation, tier 2 metaschema validation).

Download an Artifact

pretorin oscal artifacts download <artifact_id>
pretorin oscal artifacts download <artifact_id> --output ssp.json
pretorin oscal artifacts download <artifact_id> --no-verify
OptionDescription
--output / -oOutput file or directory (default: <type>.json, e.g. ssp.json)
--verify / --no-verifyVerify SHA-256 against artifact metadata (default: on)
--system / -sSystem name or ID (uses active context if unset)

The download fetches the canonical stored bytes from a presigned URL and verifies their SHA-256 against the artifact’s checksum_sha256. On a checksum mismatch the file is not written and the command exits non-zero. The presigned URL is fetched without the platform API token, so your credentials never reach object storage.

Get the Latest Validated Artifact

The CI/CD sugar: fetch the newest validated artifact of a given type in one call.

# Print the latest SSP's metadata
pretorin oscal artifacts latest --type ssp

# Download it (checksum-verified) to ssp.json
pretorin oscal artifacts latest --type ssp --download --output ssp.json
OptionDescription
--type / -tArtifact type (required)
--download / -dDownload the latest artifact instead of just printing metadata
--output / -oOutput path (with --download)
--framework / -fFilter by framework ID
--assessment / -aFilter by assessment ID
--verify / --no-verifyVerify SHA-256 (with --download)

If no validated artifact of the requested type exists, the command prints a clear message and exits non-zero — so a pipeline step fails loudly rather than silently shipping nothing.

CI/CD Export Example

Download the latest validated SSP as part of a machine-readable export pipeline. The non-zero exit on “no valid artifact” gates the build automatically:

# .github/workflows/oscal-export.yml
name: OSCAL Export
on:
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * 1"   # weekly

jobs:
  export:
    runs-on: ubuntu-latest
    env:
      PRETORIN_API_KEY: ${{ secrets.PRETORIN_API_KEY }}   # READ scope is sufficient
      PRETORIN_SYSTEM_ID: ${{ vars.PRETORIN_SYSTEM_ID }}
    steps:
      - run: pipx install pretorin-cli

      # Fails the job if no validated SSP exists yet.
      - name: Download latest validated SSP
        run: pretorin oscal artifacts latest --type ssp --download --output ssp.json

      - name: Upload OSCAL package
        uses: actions/upload-artifact@v4
        with:
          name: oscal-ssp
          path: ssp.json

The downloaded JSON declares its own oscal_version (artifacts emit OSCAL 1.2.1, trestle-validated), so downstream consumers always know exactly what they got.

See Also