From 7a553220c24c973ba5bbafc0c0cb320535c70ae4 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Fri, 27 Aug 2021 17:45:02 -0400 Subject: [PATCH 1/9] Adding link to XML Jelly Sandwich OSCAL demos (#1016) --- docs/content/tools/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content/tools/_index.md b/docs/content/tools/_index.md index b38619ef30..64273b4111 100644 --- a/docs/content/tools/_index.md +++ b/docs/content/tools/_index.md @@ -35,3 +35,4 @@ See the [NIST Software Disclaimer](https://www.nist.gov/disclaimer) for more inf | [OSCAL React Component Library](https://github.com/EasyDynamics/oscal-react-library) | Easy Dynamics | A library of reusable React components and an [example user interface application](https://oscal-viewer.msd.easydynamics.com/catalog) that provides a direct UI into OSCAL. | | [OSCAL REST API](https://github.com/EasyDynamics/oscal-rest) | Easy Dynamics | An initial OpenAPI definition of an OSCAL REST API that describes how systems might manipulate catalogs, profiles, components, and SSPs. | | [XSLT Tooling](https://github.com/usnistgov/oscal-tools/tree/master/xslt) | NIST OSCAL Project | A variety of Extensible Stylesheet Language (XSL) Transformations (XSLT), Cascading Style Sheets (CSS), and related utilities for authoring, converting, and publishing OSCAL content in various forms. | +| [XML Jelly Sandwich](https://github.com/wendellpiez/XMLjellysandwich) | Wendell Piez (NIST) | Interactive XSLT in the browser includes [OSCAL demonstrations](https://wendellpiez.github.io/XMLjellysandwich/oscal/). | From 6381eeebe15d0138e27f7d4a079afd7e7256d716 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Fri, 27 Aug 2021 18:34:26 -0400 Subject: [PATCH 2/9] Adding Component Tutorial to Website (#1015) - Addressed issue #854 creating a tutorial based on component definition content from PR #935. - Linked the tutorial in the learn and concepts sections of the website. - Adjusting deployment workflows. - Adding new website GitHub actions workflow. - Adjusting workflows to decompose specific activities. Co-authored-by: Rene Tshiteya Co-authored-by: Rene2mt <76444659+Rene2mt@users.noreply.github.com> --- .github/workflows/metaschema-artifacts.yml | 150 +--- .github/workflows/validate-repo-markdown.yml | 55 ++ .github/workflows/website-artifacts.yml | 178 ++++ .github/workflows/website-deploy.yml | 4 +- .../concepts/layer/control/catalog/_index.md | 6 + .../component-definition/_index.md | 13 + .../layer/implementation/ssp/_index.md | 6 + docs/content/learn/tutorials/_index.md | 4 +- .../content/learn/tutorials/catalog/other.mdx | 78 -- .../tutorials/component-definition/_index.md | 777 ++++++++++++++++++ 10 files changed, 1045 insertions(+), 226 deletions(-) create mode 100644 .github/workflows/validate-repo-markdown.yml create mode 100644 .github/workflows/website-artifacts.yml delete mode 100644 docs/content/learn/tutorials/catalog/other.mdx create mode 100644 docs/content/learn/tutorials/component-definition/_index.md diff --git a/.github/workflows/metaschema-artifacts.yml b/.github/workflows/metaschema-artifacts.yml index 12f23ce7c6..5e3f73ee6f 100644 --- a/.github/workflows/metaschema-artifacts.yml +++ b/.github/workflows/metaschema-artifacts.yml @@ -2,26 +2,29 @@ on: push: branches: - main + paths: + - 'src/metaschema/**' + - '.github/workflows/metaschema-artifacts.yml' pull_request: types: [opened, synchronize, reopened] + paths: + - 'src/metaschema/**' + - '.github/workflows/metaschema-artifacts.yml' workflow_dispatch: branches: - main -name: Build Artifacts and Documentation +name: Build OSCAL Artifacts env: # the name of the repo HOME_REPO: usnistgov/OSCAL HOME_BRANCH: main # dependency versions SAXON_VERSION: 9.9.1-3 - HUGO_VERSION: 0.69.2 # build-specific environment - CONTENT_CONFIG_PATH: src/config SCHEMATRON_HOME: git-content/schematron OSCAL_HOME: git-content/oscal OSCAL_CICD_PATH: git-content/oscal/build/ci-cd OSCAL_WORKING_PATH: git-content/oscal - OSCAL_WEBSITE_PATH: git-content/oscal/docs OSCAL_SCRATCH_PATH: oscal-scratch jobs: check-skip: @@ -134,142 +137,3 @@ jobs: commit_user_name: OSCAL GitHub Actions Bot commit_user_email: oscal@nist.gov commit_author: OSCAL GitHub Actions Bot - validate-repo-markdown: - name: Validate Repo Markdown Content - needs: check-skip - if: ${{ needs.check-skip.outputs.skip == 'false' }} - runs-on: ubuntu-18.04 - steps: - # use this for pulls where checkout is anonymous - - uses: actions/checkout@v2 - with: - path: ${{ env.OSCAL_HOME }} - submodules: recursive - # Setup runtime environment - # ------------------------- - - name: Get markdown-link-check - run: | - sudo npm install -g markdown-link-check - # Build Artifacts - # --------------- - - name: Validate repo Markdown content instances - run: | - cd "$OSCAL_HOME" - # this command will filter out any docs Markdown files, which are checked in a different job - git ls-files "*/*.md" -z | grep --null-data -v "^docs/" | xargs -0 -n1 markdown-link-check -q -c "build/config/.markdown-link-check/config.json" -# build-and-publish-website: -# name: Build and Publish Website -# needs: build-and-publish-metaschema-artifacts -# runs-on: ubuntu-18.04 -# steps: -# # use this for main repo master builds -# - uses: actions/checkout@v2 -# if: ${{ github.repository == env.HOME_REPO && github.ref == format('refs/heads/{0}',env.HOME_BRANCH) }} -# with: -# path: ${{ env.OSCAL_HOME }} -# submodules: recursive -# token: ${{ secrets.COMMIT_TOKEN }} -# - name: Get latest from repo -# if: ${{ github.repository == env.HOME_REPO && github.ref == format('refs/heads/{0}',env.HOME_BRANCH) }} -# # This will ensure that any files committed by the previous job, will be updated -# run: | -# git pull --ff-only -# working-directory: ${{ env.OSCAL_HOME }} -# # use this for pull request builds where checkout uses the builtin token -# - uses: actions/checkout@v2 -# if: ${{ github.repository != env.HOME_REPO || github.ref != format('refs/heads/{0}',env.HOME_BRANCH) }} -# with: -# path: ${{ env.OSCAL_HOME }} -# submodules: recursive -# # Setup runtime environment -# # ------------------------- -# # Operating System packages -# - name: Update APT package metadata -# run: | -# sudo rm -rf /var/lib/apt/lists/* && sudo apt-get update -# # Java JDK 11 -# - name: Set up JDK 11 -# uses: actions/setup-java@v2 -# with: -# java-version: 11 -# distribution: 'adopt' -# - name: Cache Maven packages -# uses: actions/cache@v2 -# with: -# path: ~/.m2/repository -# key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} -# restore-keys: ${{ runner.os }}-m2- -# - name: Get Saxon-HE -# run: | -# mvn org.apache.maven.plugins:maven-dependency-plugin:2.10:get -DartifactId=Saxon-HE -DgroupId=net.sf.saxon -Dversion=$SAXON_VERSION -# # Ruby and Bundler -# - uses: ruby/setup-ruby@v1 -# with: -# ruby-version: 2.6 # Not needed with a .ruby-version file -# bundler-cache: true # runs 'bundle install' and caches installed gems automatically -# working-directory: ${{ env.OSCAL_WEBSITE_PATH }} -# # Hugo -# - name: Get Hugo -# run: | -# wget https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.deb -# - name: Install Hugo -# run: | -# sudo apt-get install ./hugo_extended_${HUGO_VERSION}_Linux-64bit.deb -# # Build Artifacts -# # --------------- -# - name: Generate specification documentation -# run: | -# bash "${OSCAL_CICD_PATH}/generate-specification-documentation.sh" -# - uses: actions/upload-artifact@v2 -# with: -# name: specification-docs -# path: | -# ${{ env.OSCAL_HOME }}/docs/content/documentation/processing/profile-resolution.html -# retention-days: 5 -# # job-generate-docs -# - name: Generate Model Documentation -# run: | -# echo "PWD: ${PWD}" -# echo "OSCAL_HOME: ${OSCAL_HOME}" -# echo "Github Workspace: ${{ github.workspace }}" -# echo "Branch: $(git branch --show-current)" - -# BRANCH="${GITHUB_REF}" -# echo "Branch(1): ${BRANCH}" -# if [[ "$BRANCH" =~ ^refs/pull/.* ]]; then -# BRANCH="${GITHUB_HEAD_REF}" -# echo "Branch(2): ${BRANCH}" -# elif [[ "$BRANCH" =~ ^refs/heads/.* ]]; then -# BRANCH="${GITHUB_REF#refs/heads/}" -# echo "Branch(3): ${BRANCH}" -# fi -# echo "Branch(4): ${BRANCH}" -# bash "../build/ci-cd/generate-model-documentation.sh" -b "${BRANCH}" -# working-directory: ${{ github.workspace }}/${{ env.OSCAL_HOME }}/docs -# # - uses: actions/upload-artifact@v2 -# # with: -# # name: model-docs -# # path: | -# # ${{ env.OSCAL_HOME }}/docs/layouts/partials/generated -# # retention-days: 5 -# - name: Run Hugo -# run: | -# cd "${OSCAL_WEBSITE_PATH}" -# hugo -v --debug --minify -# - uses: actions/upload-artifact@v2 -# with: -# name: website -# path: | -# ${{ env.OSCAL_WEBSITE_PATH }}/public -# retention-days: 5 -# # - name: Run HTMLProofer -# # run: | -# # cd "${OSCAL_WEBSITE_PATH}" -# # #--allow-hash-href -# # bundle exec htmlproofer --check-external-hash public/ --url-swap "https\://pages.nist.gov/OSCAL/:/" --assume-extension --log-level :debug --url-ignore "/\/OSCAL\/docs\/\/reference\/[^/]+\/[^/]+\/(?:json|xml)-(?:outline|reference|index|definitions)/,/#/,/pages.nist.gov\/(?:nist-header-footer|leaveNotice)\/.+/" -# # - name: Run deploy script -# # if: ${{ github.repository == env.HOME_REPO && github.ref == format('refs/heads/{0}',env.HOME_BRANCH) }} -# # run: | -# # cd "$OSCAL_WEBSITE_PATH" -# # git config user.name "Deployment Bot" -# # bash ./deploy.sh --push-only -v -m "Deploying website [ci deploy skip]" diff --git a/.github/workflows/validate-repo-markdown.yml b/.github/workflows/validate-repo-markdown.yml new file mode 100644 index 0000000000..df1cf4b6a2 --- /dev/null +++ b/.github/workflows/validate-repo-markdown.yml @@ -0,0 +1,55 @@ +on: + push: + branches: + - main + paths: + - '!docs/**' + - '**.md' + - '.github/workflows/validate-repo-markdown.yml' + pull_request: + types: [opened, synchronize, reopened] + paths: + - '!docs/**' + - '**.md' + - '.github/workflows/validate-repo-markdown.yml' + workflow_dispatch: + branches: + - main +name: Validate Repo Markdown +env: + # build-specific environment + OSCAL_HOME: git-content/oscal +jobs: + check-skip: + runs-on: ubuntu-latest + outputs: + skip: ${{ steps.ci-skip-step.outputs.ci-skip }} + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + - id: ci-skip-step + uses: mstachniuk/ci-skip@v1 + validate-repo-markdown: + name: Validate Repo Markdown Content + needs: check-skip + if: ${{ needs.check-skip.outputs.skip == 'false' }} + runs-on: ubuntu-18.04 + steps: + # use this for pulls where checkout is anonymous + - uses: actions/checkout@v2 + with: + path: ${{ env.OSCAL_HOME }} + submodules: recursive + # Setup runtime environment + # ------------------------- + - name: Get markdown-link-check + run: | + sudo npm install -g markdown-link-check + # Build Artifacts + # --------------- + - name: Validate repo Markdown content instances + run: | + cd "$OSCAL_HOME" + # this command will filter out any docs Markdown files, which are checked in a different job + git ls-files "*/*.md" -z | grep --null-data -v "^docs/" | xargs -0 -n1 markdown-link-check -q -c "build/config/.markdown-link-check/config.json" diff --git a/.github/workflows/website-artifacts.yml b/.github/workflows/website-artifacts.yml new file mode 100644 index 0000000000..f992bd084f --- /dev/null +++ b/.github/workflows/website-artifacts.yml @@ -0,0 +1,178 @@ +on: + push: + branches: + - main + - develop + tags: + - "v*" + paths: + - 'src/metaschema/**_metaschema.xml' + - 'build/ci-cd/metaschema' + - 'build/ci-cd/metaschema-docs' + - 'build/ci-cd/generate-model-documentation.sh' + - 'build/metaschema' + - '.github/workflows/website-artifacts.yml' + pull_request: + types: [opened, synchronize, reopened] + paths: + - 'src/metaschema/**_metaschema.xml' + - 'build/ci-cd/metaschema' + - 'build/ci-cd/metaschema-docs' + - 'docs/**' + - 'build/ci-cd/generate-model-documentation.sh' + - 'build/metaschema' + - '.github/workflows/website.yml' + workflow_dispatch: + branches: + - main +name: Build and Push Website Contents +env: + # the name of the repo + HOME_REPO: usnistgov/OSCAL + HOME_BRANCH: main + # dependency versions + SAXON_VERSION: 9.9.0-1 + HUGO_VERSION: 0.83.1 + CALABASH_VERSION: 1.2.5-100 + # build-specific environment + OSCAL_HOME: git-content/oscal + CONTENT_CONFIG_PATH: src/config + SCHEMATRON_HOME: git-content/schematron + CALABASH_HOME: dependencies/calabash + OSCAL_CICD_PATH: git-content/oscal/build/ci-cd + OSCAL_WORKING_PATH: git-content/oscal + OSCAL_WEBSITE_PATH: git-content/oscal/docs + OSCAL_SCRATCH_PATH: oscal-scratch +jobs: + build-and-push-website: + name: Build and Push Website Contents + runs-on: ubuntu-20.04 + steps: + # use this for main repo builds on branches + - name: Checkout working branch or Tag + uses: actions/checkout@v2 + if: ${{ github.repository == env.HOME_REPO && github.event_name == 'push' }} + with: + path: ${{ env.OSCAL_HOME }} + submodules: recursive + token: ${{ secrets.COMMIT_TOKEN }} + - name: Get latest from repo + if: ${{ github.repository == env.HOME_REPO && github.event_name == 'push' }} + # This will ensure that any files committed by the previous job, will be updated + run: | + git pull --ff-only + working-directory: ${{ env.OSCAL_HOME }} + # use this for pull request builds where checkout uses the builtin token + - name: Checkout PR + uses: actions/checkout@v2 + if: ${{ github.repository != env.HOME_REPO || github.event_name != 'push' }} + with: + path: ${{ env.OSCAL_HOME }} + submodules: recursive + # Setup runtime environment + # ------------------------- + # Operating System packages + - name: Update APT package metadata + run: | + sudo rm -rf /var/lib/apt/lists/* && sudo apt-get update + # Java JDK 11 + - name: Set up JDK 11 + uses: actions/setup-java@v2 + with: + java-version: 11 + distribution: 'adopt' + - name: Cache Maven packages + uses: actions/cache@v2 + with: + path: ~/.m2/repository + key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} + restore-keys: ${{ runner.os }}-m2- + - name: Get Saxon-HE + run: | + mvn org.apache.maven.plugins:maven-dependency-plugin:2.10:get -DartifactId=Saxon-HE -DgroupId=net.sf.saxon -Dversion=$SAXON_VERSION +# # Ruby and Bundler +# - name: Install Ruby and Bundler +# uses: ruby/setup-ruby@v1 +# with: +# ruby-version: 2.6 # Not needed with a .ruby-version file +# bundler-cache: true # runs 'bundle install' and caches installed gems automatically +# working-directory: ${{ env.OSCAL_WEBSITE_PATH }} + # Install Calabash + - name: Install Calabash + run: | + wget https://github.com/ndw/xmlcalabash1/releases/download/${CALABASH_VERSION}/xmlcalabash-${CALABASH_VERSION}.zip + mkdir -p "${CALABASH_HOME}" + unzip -d "${CALABASH_HOME}" "xmlcalabash-${CALABASH_VERSION}.zip" && f=("${CALABASH_HOME}"/*) && mv "${CALABASH_HOME}"/*/* "${CALABASH_HOME}" && rmdir "${f[@]}" + # Install Hugo + - name: Install Hugo + run: | + wget https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.deb + sudo apt-get install ./hugo_extended_${HUGO_VERSION}_Linux-64bit.deb + # Build Artifacts + # --------------- + - name: Generate specification documentation + run: | + bash "${OSCAL_CICD_PATH}/generate-specification-documentation.sh" + - uses: actions/upload-artifact@v2 + with: + name: specification-docs + path: | + ${{ env.OSCAL_HOME }}/docs/content/documentation/processing/profile-resolution.html + retention-days: 5 + # job-generate-docs + - name: Generate Model Documentation + run: | + echo "PWD: ${PWD}" + echo "OSCAL_HOME: ${OSCAL_HOME}" + echo "Github Workspace: ${{ github.workspace }}" + echo "Branch: $(git branch --show-current)" + + BRANCH="${GITHUB_REF}" + echo "Branch(1): ${BRANCH}" + if [[ "$BRANCH" =~ ^refs/pull/.* ]]; then + BRANCH="${GITHUB_HEAD_REF}" + echo "Branch(2): ${BRANCH}" + elif [[ "$BRANCH" =~ ^refs/heads/.* ]]; then + BRANCH="${GITHUB_REF#refs/heads/}" + echo "Branch(3): ${BRANCH}" + fi + echo "Branch(4): ${BRANCH}" + CALABASH_HOME="${{ github.workspace }}/${CALABASH_HOME}" bash "../build/ci-cd/generate-model-documentation.sh" -b "${BRANCH}" + working-directory: ${{ github.workspace }}/${{ env.OSCAL_HOME }}/docs + - name: Run Hugo + run: | + cd "${OSCAL_WEBSITE_PATH}" + hugo --config "config.yaml,development-config.yaml" -v --debug --minify + - uses: actions/upload-artifact@v2 + with: + name: website + path: | + ${{ env.OSCAL_WEBSITE_PATH }}/public + retention-days: 5 + - name: Check internal links + uses: untitaker/hyperlink@0.1.15 + with: + args: ${{ env.OSCAL_WEBSITE_PATH }}/public/ --sources ${{ env.OSCAL_WEBSITE_PATH }}/content --check-anchors +# - name: Run HTMLProofer +# run: | +# cd "${OSCAL_WEBSITE_PATH}" +# bundle exec htmlproofer --check-external-hash public/ --url-swap "https\://pages.nist.gov/OSCAL/:/" --assume-extension --log-level :debug --url-ignore "/pages.nist.gov\/(?:nist-header-footer|leaveNotice)\/.+/" +# - uses: actions/upload-artifact@v2 +# with: +# name: generated-docs +# path: | +# ${{ env.OSCAL_HOME }}/docs +# retention-days: 5 + - name: Publish Artifacts + # only do this on master + if: ${{ github.repository == env.HOME_REPO && github.ref == format('refs/heads/{0}',env.HOME_BRANCH) }} + uses: stefanzweifel/git-auto-commit-action@v4.9.2 + with: + repository: ${{ env.OSCAL_HOME }} + file_pattern: docs + # push_options: --force-with-lease + skip_dirty_check: false + commit_message: Publishing Generated Website Content [ci skip] + commit_user_name: OSCAL GitHub Actions Bot + commit_user_email: oscal@nist.gov + commit_author: OSCAL GitHub Actions Bot diff --git a/.github/workflows/website-deploy.yml b/.github/workflows/website-deploy.yml index d62763ac31..f8e48f772d 100644 --- a/.github/workflows/website-deploy.yml +++ b/.github/workflows/website-deploy.yml @@ -5,12 +5,10 @@ on: paths: - 'docs/**' - '.github/workflows/website-deploy.yml' - - 'xml' - - 'json' workflow_dispatch: branches: - main -name: Build and Publish Website +name: Publish Website env: # the name of the repo HOME_REPO: usnistgov/OSCAL diff --git a/docs/content/concepts/layer/control/catalog/_index.md b/docs/content/concepts/layer/control/catalog/_index.md index 8604f12132..bc2f001074 100644 --- a/docs/content/concepts/layer/control/catalog/_index.md +++ b/docs/content/concepts/layer/control/catalog/_index.md @@ -293,3 +293,9 @@ Comparing the ISO 27002 and NIST SP 800-53 examples illustrates obvious differen To address these differences, OSCAL is designed to take disparate control definitions from different sources and express them in a standardized way using the catalog model. The OSCAL catalog model defines structured, machine-readable XML, JSON, and YAML representations of the information contained within a control. A control defined using the OSCAL catalog model supports including control statements, guidance, assessment objectives, and many other features. By combining all of this information in a single model, the OSCAL catalog model simplifies the entire control-based operational model. {{}} + +## Related Tutorials + +The following tutorial is provided related to the catalog model. + +- [Creating a Control Catalog](/learn/tutorials/catalog/): Covers overs creating a basic OSCAL control catalog. diff --git a/docs/content/concepts/layer/implementation/component-definition/_index.md b/docs/content/concepts/layer/implementation/component-definition/_index.md index 6b0f22bd50..2cd4000a82 100644 --- a/docs/content/concepts/layer/implementation/component-definition/_index.md +++ b/docs/content/concepts/layer/implementation/component-definition/_index.md @@ -95,3 +95,16 @@ The figure below expresses represents the portion of the OSCAL stack as it relat ### Modeling Validation Information OSCAL is designed to allow capture relevant details related to independent validation of components. See the [Validation Modeling](/learn/tutorials/validation-modeling/) tutorial for details. + +## Related Tutorials + +The following tutorials are provided that are related to the component definition model. + +- [Creating a Component Definition](/learn/tutorials/component-definition/): Covers creating a basic OSCAL component definition for a software product. +- [Representing Test Validation Information](/learn/tutorials/validation-modeling/): Explains how to represent test validation information (e.g., FIPS-140-2) for a component in an OSCAL component definition. + +## Content Examples + +Multiple examples of component definitions expressed using the OSCAL component definitions model can be found in the OSCAL GitHub repository in [XML]({{< param "contentRepoPath" >}}/examples/component-definition/xml), +[JSON]({{< param "contentRepoPath" >}}/examples/component-definition/json), +and [YAML]({{< param "contentRepoPath" >}}/examples/component-definition/yaml/) formats. diff --git a/docs/content/concepts/layer/implementation/ssp/_index.md b/docs/content/concepts/layer/implementation/ssp/_index.md index 8c620ff6d4..3a2f7875a6 100644 --- a/docs/content/concepts/layer/implementation/ssp/_index.md +++ b/docs/content/concepts/layer/implementation/ssp/_index.md @@ -74,3 +74,9 @@ OSCAL is designed to allow capture relevant details related to independent valid Multiple examples of SSP expressed using the OSCAL SSP model can be found in the OSCAL GitHub repository in [XML]({{< param "contentRepoPath" >}}/examples/ssp/xml), [JSON]({{< param "contentRepoPath" >}}/examples/ssp/json), and [YAML]({{< param "contentRepoPath" >}}/examples/ssp/yaml/) formats. + +## Related Tutorials + +The following tutorial is provided related to the catalog model. + +- [Representing Test Validation Information](/learn/tutorials/validation-modeling/): Explains how to represent test validation information (e.g., FIPS-140-2) for a component in an OSCAL SSP. diff --git a/docs/content/learn/tutorials/_index.md b/docs/content/learn/tutorials/_index.md index e38c4488b4..95d795560b 100644 --- a/docs/content/learn/tutorials/_index.md +++ b/docs/content/learn/tutorials/_index.md @@ -3,8 +3,8 @@ title: Walkthrough Tutorials suppresstopiclist: true --- -The following tutorials provide a step-by-step walkthrough on explaining how to create OSCAL content of various types: +The following tutorials provide a step-by-step walkthrough on explaining how to create OSCAL content of various types. - [Creating a Basic Control Catalog](/learn/tutorials/catalog/): A tutorial on creating a [catalog](/concepts/terminology/#catalog) of [controls](/concepts/terminology/#control) using the OSCAL [catalog model](/concepts/layer/control/catalog/). +- [Creating a Basic Component Definition](/learn/tutorials/component-definition/): A tutorial on creating a component-definition using the OSCAL [component definition model](/concepts/layer/implementation/component-definition/). - [Representing Test Validation Information](/learn/tutorials/validation-modeling/): A mini-tutorial on providing test validation information (e.g., FIPS 140-2 validation) as an OSCAL component in a [component definition](/concepts/layer/implementation/component-definition/) or [system security plan](/concepts/layer/implementation/ssp/). - diff --git a/docs/content/learn/tutorials/catalog/other.mdx b/docs/content/learn/tutorials/catalog/other.mdx deleted file mode 100644 index 539680a22e..0000000000 --- a/docs/content/learn/tutorials/catalog/other.mdx +++ /dev/null @@ -1,78 +0,0 @@ -{{% tab %}} -{{< highlight json "linenos=table" >}} -{ - "metadata": { - "title": "Sample Security Catalog", - "published": "2020-02-02T11:01:04.736-04:00", - "last-modified": "2020-10-02T11:01:04.736-04:00", - "version": "1.0", - "oscal-version": "1.0.0-milestone3" - } -} -{{< /highlight >}} -{{% /tab %}} - - - - -When necessary, revision history can be also documented. See additional information [here](https://pages.nist.gov/OSCAL/documentation/schema/catalog/xml-model-map/) - -The `metadata` is also designed to accommodate the representation of other information related to the content of the catalog and the entity (individual or organization) that created it in OSCAL. -For example, we can select and represent *keywords* using the property tag ``, for which we define the `name` of the property as being *keywords*. -The *keywords* will be a `string` comprised of a comma-separated list of significant words, in alphabetical order. - -The information will look as follows: -```xml - Assurance, computer security, FISMA, Privacy Act, Risk Management Framework, security controls, security requirements -``` - -To do so, one can use the tags ` and `` each instance with a distinct `id`, and the tag `` with the field `role-id` that identifies the id of the pointed role and the tag `` that points to the `id` of the defined ``. -In this example the `` is an organization (NIST) for which the name is provided using the tag ``, an email address is listed using the tag `` and the URL using the tag ``. -Below is all this information assembled in OSCAL. - -```xml - - Document creator - - - Contact - - - - National Institute of Standards and Technology - oscal@nist.gov - https://www.nist.gov/oscal - - - - NIST - - - NIST - -``` - -#### Formatting a Back-matter - -Often documents have references, links to other documents, diagrams/images, citations, remarks. -OSCAL defines elements that can be used to represent such information. - -Back-matters are optional elements and therefore often the OSCAL Catalogs will not contain any. - -A back-matter element is identified by the tag ``. -This element may have `resources` which are identified with the tag ``. - -Each `resource` may have: - -``` - * `title` identified by the tags - * `description` identified by the tags - * `property` identified by the tags - * `document id` identified by the tags - * `citation` identified by the tags - * `link` identified by the tags - * `base64-binary-data` identified by the tags - * `remarks` identified by the tags -``` -Our catalog does not contain any back-matter, but additional information about the available -elements and their fields, can be found [here](https://pages.nist.gov/OSCAL/documentation/schema/catalog/xml-model-map/) diff --git a/docs/content/learn/tutorials/component-definition/_index.md b/docs/content/learn/tutorials/component-definition/_index.md new file mode 100644 index 0000000000..e6248360a6 --- /dev/null +++ b/docs/content/learn/tutorials/component-definition/_index.md @@ -0,0 +1,777 @@ +--- +title: Creating a Component Definition +description: A tutorial on creating an OSCAL component definition. +weight: 6 +suppresstopiclist: true +toc: + enabled: true +--- + +This tutorial covers creating a basic OSCAL component definition. Before reading this tutorial you should: + +- Have some familiarity with the [XML](https://www.w3.org/standards/xml/core), [JSON](https://www.json.org/), or [YAML](https://yaml.org/spec/) formats. +- Read the OSCAL implementation layer [overview](/concepts/layer/implementation/). +- Review the OSCAL [component definition](/concepts/layer/implementation/component-definition/) model overview. +- Be familiar with the use of OSCAL properties and links. + +## What is an OSCAL Component Definition? + +An OSCAL [component definition](/concepts/layer/implementation/component-definition/) contains a collection of components. Each component in a component definition describes how a given implementation of a hardware, software, service, policy, process, or procedure asset can support or provide implementations of specific controls. The asset described by a component in a component definition is called a *component subject*"* in this tutorial. + +By publishing a set of components in a component definition, product and service vendors, capability owners, policy and process owners, and [others](/concepts/layer/implementation/component-definition/#component-definition-authors) can share control implementation information for a component subject they maintain. The information about a component subject can then be [used](/concepts/layer/implementation/component-definition/#component-definition-consumers) when implementing that subject in an information system. This allows the control narrative for the subject to be imported into the System Security Plan (SSP). + +It is important to note that component definitions do not describe actual implementations; rather, component definitions describe possible implementations which can be instantiated within an information system. Thus, component definitions serve as references with content that can be (re)used (e.g., in the SSP OSCAL model) to develop comprehensive and consistent control implementations within an SSP. + +In this tutorial, we will walk through the process of creating an OSCAL component definition model instance for [MongoDB](https://docs.mongodb.com/). Our goal is to demonstrate how to provide standard control implementations for the benefit of system owners and SSP authors that use a similar software application. + +As potential components in information systems that may need to meet the OMB A-130 Authorization to Operate requirements, the component definition in this tutorial will show proper implementation of a couple [NIST SP 800-53 rev 5 controls](https://github.com/usnistgov/oscal-content/tree/master/nist.gov/SP800-53/rev5/xml) deemed necessary for high, moderate, or low impact systems. While this example focuses on NIST controls, the same approach could be applied to any catalog of controls (e.g., ISO/IEC 27002). + +For the purposes of this tutorial we'll presume the MongoDB component can partially or fully satisfy the following controls: + +| NIST 800-53 rev5 Control | Description | +| -------- | -------- | +| SA-4(9) | Acquisition Process - Functions, Ports, Protocols, and Services in Use | +| SC-8(1) | Transmission Confidentiality and Integrity | + +This tutorial demonstrates how to document a set of implemented controls as an OSCAL component definition for these controls. + +## Creating an OSCAL Component Definition Instance + +The examples below illustrate the top-level structure of the OSCAL Component Definition Model. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + + + + + + +{{< /highlight >}} + +The root of the OSCAL component definition model is [``](/reference/latest/component-definition/xml-reference/#/component-definition). Note that the schema location attribute is omitted for this example. The `@uuid` attribute (on line 3) is the document's universally unique identifier (UUID), a unique 128-bit number displayed as a string of hyphenated hexadecimal digits as defined by RFC 4122. OSCAL documents use a version 4 UUID (randomly generated) to uniquely identify the document. + +A `` contains the following elements: + +- `` (required) - Provides document metadata for the component definition. This is covered in the [next section](/learn/tutorials/component-definition/#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. +- `` (optional) – Identifies a collection of external component definitions from other resources from which related information is referenced within this component definition. Use of `` is not covered in this tutorial. +- `` (optional) - Defines a given component in the component definition. Zero or more `` elements may be used. Use of this element is [discussed later](http://localhost:1313/OSCAL/learn/tutorials/component-definition/#defining-the-mongodb-component) in this tutorial. +- `` (optional) - Defines a given capability in the component definition. Zero or more `` elements may be used. Capabilities are not covered in this tutorial. +- `` (optional) – Contains resources which are referenced within the component definition. Use of `` is not covered in this tutorial. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "component-definition": { + "uuid": "a7ba800c-a432-44cd-9075-0862cd66da6b", + "metadata": {}, + "import-component-definitions": [{}], + "components": [{}], + "capabilities": [{}], + "back-matter": {} + } +} +{{< /highlight >}} + +The root of the OSCAL component definition model is [`component-definition`](/reference/latest/component-definition/json-reference/#/component-definition). The `uuid` property (on line 3) is the document's universally unique identifier (UUID), a unique 128-bit number displayed as a string of hyphenated hexadecimal digits as defined by RFC 4122. OSCAL documents use a version 4 UUID (randomly generated) to uniquely identify the document. + +A `component-definition` contains the following properties: + +- `metadata` (required) - Provides document metadata for the component definition. This is covered in the [next section](/learn/tutorials/component-definition/#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. +- `import-component-definitions` (optional) – Identifies a collection of external component definitions from other resources from which related information is referenced within this component definition. Use of `import-component-definitions` is not covered in this tutorial. +- `components` (optional) - Groups `component` objects which each define a given component in the component definition. One or more `component` objects may be provided. Use of this property is [discussed later](http://localhost:1313/OSCAL/learn/tutorials/component-definition/#defining-the-mongodb-component) in this tutorial. +- `capabilities` (optional) - Defines a group of given capabilities in the component definition. One or more `capability` objects may be used. Capabilities are not covered in this tutorial. +- `back-matter` (optional) – Contains references which are referenced within the component definition. Use of `back-matter` is not covered in this tutorial. +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} + +--- +component-definition: + uuid: a7ba800c-a432-44cd-9075-0862cd66da6b + metadata: ~ + import-component-definitions: ~ + components: ~ + capabilities: ~ + back-matter: ~ +{{< /highlight >}} + +The root of the OSCAL component definition model is [`component-definition`](/reference/latest/component-definition/json-reference/#/component-definition). The `uuid` key (on line 3) is the document's universally unique identifier (UUID), a unique 128-bit number displayed as a string of hyphenated hexadecimal digits as defined by RFC 4122. OSCAL documents use a version 4 UUID (randomly generated) to uniquely identify the document. + +A `component-definition` contains the following keys: + +- `metadata` (required) - Provides document metadata for the component definition. This is covered in the [next section](/learn/tutorials/component-definition/#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. +- `import-component-definitions` (optional) – Identifies a collection of external component definitions from other resources from which related information is referenced within this component definition. Use of `import-component-definitions` is not covered in this tutorial. +- `components` (optional) - Groups `component` items which define given component(s) in the component definition. One or more `component` items may be used. Use of this key is [discussed later](http://localhost:1313/OSCAL/learn/tutorials/component-definition/#defining-the-mongodb-component) in this tutorial. +- `capabilities` (optional) - Defines a group of given capabilities in the component definition. One or more `capability` items may be used. Capabilities are not covered in this tutorial. +- `back-matter` (optional) – Contains references which are referenced within the component definition. Use of `back-matter` is not covered in this tutorial. +{{% /tab %}} +{{< /tabs >}} + +For simplicity of this tutorial, we will only discuss certain data structures in the sections that follow and identify how they can be used to represent our component definition. + +### Defining the Component Definition’s Metadata + +Most OSCAL models have a standard metadata syntax, therefore, this is not covered extensively in this tutorial. There are a few considerations however when authoring metadata for a component definition, such as the `role` and `party` data items illustrated in the example below. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + MongoDB Component Definition Example + 2001-08-26T23:11:47Z + 20210826 + 1.0.0 + + Provider + + + MongoDB + + + + +{{< /highlight >}} + +The [``](/reference/latest/component-definition/xml-reference/#/component-definition/metadata/role) element defines a function assumed or expected to be assumed by a party in a specific situation. In this case the role `provider` has been standardized by OSCAL to be used for [component definition authors](/concepts/layer/implementation/component-definition/#component-definition-authors). This element has a required `@id` attribute which expects an [token](/reference/datatypes/#token) data type. A `` is also provided. + +The `<party>` element represents either a person or organization that serves as the responsible entity. A party must have an associated `@uuid` which is used to reference this party, a `<name>` which provides a formal label, and a `@type` which defines the nature of the party. There are prescribed types, including *"person"*, and *"organization"*. In this case we are defining the MongoDB project as an organization. A pointer to the organization's website is also included. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "component-definition": { + "uuid": "a7ba800c-a432-44cd-9075-0862cd66da6b", + "metadata": { + "title": "MongoDB Component Definition Example", + "last-modified": "2001-12-17T09:30:47Z", + "version": 20210507, + "oscal-version": "1.0.0", + "roles": [{ + "id": "provider", + "title": "Provider" + }], + "parties": [{ + "uuid": "ef7c799a-c50e-49ab-83e0-515e989e6df1", + "type": "organization", + "name": "MongoDB", + "links": [{ + "href": "https://www.mongodb.com", + "rel": "website" + }] + }] + } + } +} +{{< /highlight >}} + +The [`roles`](/reference/latest/component-definition/json-reference/#/component-definition/metadata/roles) property provides a grouping of role objects that each defines a function assumed or expected to be assumed by a party in a specific situation. In this case the role `provider` has been standardized by OSCAL to be used for [component definition authors](/concepts/layer/implementation/component-definition/#component-definition-authors). This element has a required `id` attribute which expects an [token](/reference/datatypes/#token) data type. A `title` is also provided. + +The [`parties`](/reference/latest/component-definition/json-reference/#/component-definition/metadata/parties) property provides a grouping of party objects that each represent either a person or organization that serves as the responsible entity. A party must have an associated `uuid` which is used to reference this party, a `name` which provides a formal label, and a `type` which defines the nature of the party. There are prescribed types, including *"person"*, and *"organization"*. In this case we are defining the MongoDB project as an organization. A pointer to the organization's website is also included. + +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- + +component-definition: + uuid: a7ba800c-a432-44cd-9075-0862cd66da6b + metadata: + title: MongoDB Component Definition Example + last-modified: '2001-12-17T09:30:47Z' + version: 20210507 + oscal-version: 1.0.0 + roles: + - id: provider + title: Provider + parties: + - uuid: ef7c799a-c50e-49ab-83e0-515e989e6df1 + type: organization + name: MongoDB + links: + - href: <https://www.mongodb.com> + rel: website +{{< /highlight >}} + +The [`roles`](/reference/latest/component-definition/json-reference/#/component-definition/metadata/roles) key provides a grouping of role items that each defines a function assumed or expected to be assumed by a party in a specific situation. In this case the role `provider` has been standardized by OSCAL to be used for [component definition authors](/concepts/layer/implementation/component-definition/#component-definition-authors). A role item has a required `id` attribute which expects an [token](/reference/datatypes/#token) data type. A `title` is also provided. + +The [`parties`](/reference/latest/component-definition/json-reference/#/component-definition/metadata/parties) key provides a grouping of party objects that each represent either a person or organization that serves as the responsible entity. A party must have an associated `uuid` which is used to reference this party, a `name` which provides a formal label, and a `type` which defines the nature of the party. There are prescribed types, including *"person"*, and *"organization"*. In this case we are defining the MongoDB project as an organization. A pointer to the organization's website is also included. +{{% /tab %}} +{{% /tabs %}} + +### Defining the MongoDB Component + +Within the component definition model, components provide a way to describe subject assets which may be used as parts of an information system. A component allows potential control implementations to be described for an subject asset, which can then be used when implementing an information system. While components are optional in a component definition, a typical component definition will include at least one component. In this example, we'll demonstrate how the control implementation of the MongoDB software is represented using the OSCAL component definition model. The snippet below provides an example of the minimum data needed to define a component. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} +<component-definition xmlns="http://csrc.nist.gov/ns/oscal/1.0" + uuid="a7ba800c-a432-44cd-9075-0862cd66da6b"> + <component uuid="91f646c5-b1b6-4786-9ec3-2305a044e217" type="software"> + <title>MongoDB + +

MongoDB is a source-available, cross-platform document-oriented + database program. Classified as a NoSQL database program, MongoDB + uses JSON-like documents with optional schemas.

+ + Provides a NoSQL database service + + ef7c799a-c50e-49ab-83e0-515e989e6df1 + + + + + +{{< /highlight >}} + +A component is represented using the [``](/reference/latest/component-definition/xml-reference/#/component-definition/component) element (on line 3). This element requires a unique identifier, which is provided using the `@uuid` attribute. + +The required `@type` attribute categorizes the component by asset type. Some common examples include interconnection, hardware, software, service, policy, process/procedure, plan, guidance, standard, and validation. In our example, we’ll set the MongoDB component as the "*software*" type, since MongoDB is a software application. + +Next, the component needs to have title and description elements that help to support human-readability of this information. + +The optional `` element can be used to reference one or more roles with responsibility for performing a function relative to the component. In this tutorial, will reference the `provider` and map this role to the mongoDB party. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "component-definition": { + "components": [{ + "uuid": "91f646c5-b1b6-4786-9ec3-2305a044e217", + "type": "software", + "title": "MongoDB", + "description": "MongoDB is a source-available, cross-platform document-oriented database program. Classified as a NoSQL database program, MongoDB uses JSON-like documents with optional schemas.", + "purpose": "Provides a NoSQL database service", + "responsible-roles": [{ + "role-id": "provider", + "party-uuid": "ef7c799a-c50e-49ab-83e0-515e989e6df1" + }], + "protocols": [{}], + "control-implementations": [{}] + }] + } +} +{{< /highlight >}} + +A component is represented in the [components](/reference/latest/component-definition/json-reference/#/component-definition/components) object array shown in line 4. Each component requires a unique identifier, which is provided using the `uuid` property. + +The required `type` property categorizes the component by asset type. Some common examples include interconnection, hardware, software, service, policy, process/procedure, plan, guidance, standard, and validation. In our example, we’ll set the MongoDB component as the "*software*" type, since MongoDB is a software application. + +Next, the component needs to have title and description properties that help to support human-readability of this information. + +The optional `responsible-roles` property can be used to reference one or more roles with responsibility for performing a function relative to the component. In this tutorial, will reference the `provider` and map this role to the mongoDB party. + +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- + +component-definition: + components: + - uuid: 91f646c5-b1b6-4786-9ec3-2305a044e217 + type: software + title: MongoDB + description: >- + MongoDB is a source-available, cross-platform document-oriented + database program. Classified as a NoSQL database program, MongoDB + uses JSON-like documents with optional schemas. + purpose: Provides a NoSQL database service + responsible-roles: + - role-id: provider + party-uuid: ef7c799a-c50e-49ab-83e0-515e989e6df1 + protocols: ~ + control-implementations: ~ +{{< /highlight >}} + +A component is represented in the [components](/reference/latest/component-definition/json-reference/#/component-definition/components) object array shown in line 4. Each component requires a unique identifier, which is provided using the `uuid` property. + +The required `type` key categorizes the component by asset type. Some common examples include interconnection, hardware, software, service, policy, process/procedure, plan, guidance, standard, and validation. In our example, we’ll set the MongoDB component to a "*software*" type. + +Next, the component needs to have title and description keys that help to support human-readability of this information. + +The optional `responsible-roles` key can be used to reference one or more roles with responsibility for performing a function relative to the component. In this tutorial, will reference the `provider` and map this role to the mongoDB party. +{{% /tab %}} +{{% /tabs %}} + +### Defining Protocols Used in a Component + +Another optional but valuable sub-element of `` is [``](/reference/latest/component-definition/xml-reference/#/component-definition/component/protocol). Generally, `` elements are applicable when dealing with a `` of types *"service"*, but they can also be provided for component types *"software"*, *"hardware"*, or *"interconnection"*. In our example, we'll assume that installations of MongoDB will result in an installation of mongod (Mongo Daemon) which runs the MongoDB database as a process and uses the following protocols: + +| Port| Transport | Direction | Description | +| ----- | --------- | --------- | ----------- | +| 27017 | TCP | Inbound | The default port for mongod and mongos instances. | +| 27018 | TCP | Inbound | The default port when running with --shardsvr runtime operation. | +| 27019 | TCP | Inbound-Outbound | The default port when running with --configsvr runtime operation | + +This is represented below. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + MongoDB + + Primary daemon process for the MongoDB system. + + + + MongoDB protocol for sharding with shardsrv option. + + + + MongoDB protocol for configsrv operation. + + + + + +{{< /highlight >}} + +The [``](/reference/latest/component-definition/xml-reference/#/component-definition/component/protocol) element has a mandatory `@uuid` and mandatory `@name` attribute that should be set to the common name of the protocol, which should be the appropriate "service name" from the [IANA Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=27017). In this example, we set it to "mongodb", which is registered with IANA. The `@name` attribute accepts [string](/reference/datatypes/#string) data types and can be set to other values when there is no corresponding IANA service name for the port (e.g., lines 10 and 15). Descriptive text for the protocol can be provided using the `title` element. The `` element is where we can specify the port number(s) and associated transport. If the protocol uses multiple contiguous port numbers, a single `` element with `start="27017" end="27019"` is sufficient, however; when the component has several protocols, it is acceptable to have multiple `` and `` elements as shown in the example XML above. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "component-definition": { + "components": [{ + "uuid": "91f646c5-b1b6-4786-9ec3-2305a044e217", + "type": "service", + "title": "MongoDB", + "protocols": [{ + "uuid": "2b4a1b3a-cbc5-4cc8-bde6-7437c28c4e54", + "name": "mongodb", + "title": "Primary daemon process for the MongoDB system.", + "port-ranges": [{ + "start": 27017, + "end": 27017, + "transport": "TCP" + }] + }, + { + "uuid": "99d8d4e5-e734-4e05-a2f9-7353097b8b61", + "name": "mongodb-shardsrv", + "title": "MongoDB protocol for sharding with shardsrv option.", + "port-ranges": [{ + "start": 27018, + "end": 27018, + "transport": "TCP" + }] + }, + { + "uuid": "6fa762f1-09ca-44d5-a94c-cfceb57debd5", + "name": "mongodb-configsvr", + "title": "MongoDB protocol for configsrv operation.", + "port-ranges": [{ + "start": 27019, + "end": 27019, + "transport": "TCP" + }] + }] + }] + } +} +{{< /highlight >}} + +The [`protocols`](/reference/latest/component-definition/json-reference/#/component-definition/components/protocols) grouping has objects with mandatory `uuid` and mandatory `name` properties that should be set to the common name of the protocol, which should be the appropriate "service name" from the [IANA Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=27017). In this example, we set it to "mongodb", which is registered with IANA. The `name` property accepts [string](/reference/datatypes/#string) data types and can be set to other values when there is no corresponding IANA service name for the port (e.g., lines 19 and 29). Descriptive text for the protocol can be provided using the `title` property. The `port-ranges` object grouping is where you can specify the port number(s) and associated transport. If the protocol uses multiple contiguous port numbers, a single `port-ranges` object with `"start":"27017"` and `"end":"27019"` is sufficient; however, when the component has several protocols, it is acceptable to have multiple `protocols` and `port-ranges` objects as shown in the example XML above. + +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- + +component-definition: + components: + - uuid: 91f646c5-b1b6-4786-9ec3-2305a044e217 + type: service + title: MongoDB + protocols: + - uuid: 2b4a1b3a-cbc5-4cc8-bde6-7437c28c4e54 + name: mongodb + title: Primary daemon process for the MongoDB system. + port-ranges: + - start: 27017 + end: 27017 + transport: TCP + - uuid: 99d8d4e5-e734-4e05-a2f9-7353097b8b61 + name: mongodb-shardsrv + title: MongoDB protocol for sharding with shardsrv option. + port-ranges: + - start: 27018 + end: 27018 + transport: TCP + - uuid: 6fa762f1-09ca-44d5-a94c-cfceb57debd5 + name: mongodb-configsvr + title: MongoDB protocol for configsrv operation. + port-ranges: + - start: 27019 + end: 27019 + transport: TCP +{{< /highlight >}} + +The [`protocols`](/reference/latest/component-definition/json-reference/#/component-definition/components/protocols) key has items with mandatory `uuid` and mandatory `name` keys that should be set to the common name of the protocol, which should be the appropriate "service name" from the [IANA Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=27017). In this example, we set it to "mongodb", which is registered with IANA. The `name` key accepts [string](/reference/datatypes/#string) data types and can be set to other values when there is no corresponding IANA service name for the port (e.g., lines 17 and 24). Descriptive text for the protocol can be provided using the `title` key. The `port-ranges` key can contain items where you can specify the port number(s) and associated transport. If the protocol uses multiple contiguous port numbers, a single `port-ranges` key with `start: 27017` and `end: 27019` is sufficient; however, when the component has several protocols, it is acceptable to have multiple `protocols` and `port-ranges` items as shown in the example XML above. +{{% /tab %}} +{{% /tabs %}} + +### Defining Control Implementation Details + +By providing control implementation details in a component, information is provided about how the given component target can satisfy controls with an associated OSCAL [catalog](/concepts/layer/control/catalog/) in general, or an associated OSCAL [profile](/concepts/layer/control/profile/) to describe how the component subject can satisfy controls from a specific baseline. In this example, we document how the MongoDB component may satisfy **SC-8(1)** which requires the implementation of cryptographic mechanisms to prevent unauthorized disclosure of information and/or detect changes to information during transmission. + +An example of providing control implementation details for SC-8(1) is provided below. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + + +

MongoDB control implementations for NIST SP 800-53 revision 5.

+ + + +

MongoDB supports TLS 1.x to encrypt data in transit, + preventing unauthorized disclosure or changes to information + during transmission. To implement TLS, set the PEMKeyFile + option in the configuration /etc/mongod.conf to the + certificate file's path and restart the the component.

+ + + + + +{{< /highlight >}} + +To document this, we use the [``](/reference/latest/component-definition/xml-reference/#/component-definition/component/control-implementation) element. This element requires a unique identifier, which is provided using the `@uuid` attribute. This element also has a `@source` attribute that is used to provide a URI reference to the appropriate OSCAL catalog or profile. The URI reference can be a URI, a relative reference, or a fragment that points to a [``](/reference/latest/component-definition/xml-reference/#/component-definition/back-matter) resource. The `` element on line 10 is where we can specify the control (e.g., SC-8(1)) and the implementation description. The `` element also has its own unique identifier `@uuid`, and the control is specified in the `@control-id` attribute on line 12. We then use the `` element to describe how this component can satisfy the specified control. + +In the example above, we demonstrated how to use OSCAL to document the MongoDB software component's control implementation for NIST control SC-8(1). However, one could document how the same component also satisfies controls from other security risk management frameworks (e.g., FedRAMP, ISO 27002, etc.) by simply adding additional [``](/reference/latest/component-definition/xml-reference/#/component-definition/component/control-implementation) elements for each catalog or profile. Likewise, for each ``, we can add additional `` elements for every control that can be implemented by the component. Additionally, we can address implementations at the control statement-level using the [``](/reference/latest/component-definition/xml-reference/#/component-definition/component/control-implementation/implemented-requirement/statement) element, allowing implementation details to be provided in a more fine-grained way. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "component-definition": { + "uuid": "a7ba800c-a432-44cd-9075-0862cd66da6b", + "components": [{ + "uuid": "91f646c5-b1b6-4786-9ec3-2305a044e217", + "type": "software", + "control-implementations": [{ + "uuid": "49f0b690-ed9f-4f32-aae0-625b77aa6d27", + "source": "https://github.com/usnistgov/oscal-content/blob/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_MODERATE-baseline_profile.json", + "description": "MongoDB control implementations for NIST SP 800-53 + revision 5.", + "implemented-requirements" [{ + "uuid": "cf8338c5-fb6e-4593-a4a8-b3c4946ee2a0", + "control-id": "sc-8.1", + "description": "MongoDB supports TLS 1.x to encrypt data in transit, + preventing unauthorized disclosure or changes to information + during transmission. To implement TLS, set the PEMKeyFile option + in the configuration file /etc/mongod.conf to the certificate + file's path and restart the the component." + }] + }] + }] + } +} +{{< /highlight >}} + +To document this, we use the [`control-implementations`](/reference/latest/component-definition/json-reference/#/component-definition/components/control-implementations) grouping. Objects within this grouping require a unique identifier, which is provided using the `uuid` property. This object also has a `source` property that is used to provide a URI reference to the appropriate OSCAL catalog or profile. The URI reference can be a URI, a relative reference, or a fragment that points to a [`back-matter`](/reference/latest/component-definition/json-reference/#/component-definition/back-matter) resource. The `implemented-requirements` grouping on line 12 is where we can specify the control (e.g., SC-8(1)) and the implementation description. Each object in the `implemented-requirements` grouping also has its own unique identifier `uuid`, and the control is specified using the `control-id` property on line 14. We then use the `description` property to describe how this component can satisfy the specified control. + +In the example above, we demonstrated how to use OSCAL to document the MongoDB software component's control implementation for NIST control SC-8(1). However, one could document how the same component also satisfies controls from other security risk management frameworks (e.g., FedRAMP, ISO 27002, etc.) by simply adding additional [`control-implementations`](/reference/latest/component-definition/json-reference/#/component-definition/components/control-implementations) objects for each catalog or profile. Likewise, for each `control-implementations` object, we can add additional `implemented-requirements` objects for every control that can be implemented by the component. Additionally, we can address implementations at the control statement-level using the [`statements`](/reference/latest/component-definition/json-reference/#/component-definition/components/control-implementations/implemented-requirements/statements) grouping, allowing implementation details to be provided in a more fine-grained way. + +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- + +component-definition: + uuid: a7ba800c-a432-44cd-9075-0862cd66da6b, + components: + - uuid: 91f646c5-b1b6-4786-9ec3-2305a044e217 + type: software + control-implementations: + - uuid: 49f0b690-ed9f-4f32-aae0-625b77aa6d27 + source: + description: >- + MongoDB control implementations for NIST SP 800-53rev5. + implemented-requirements: + - uuid: cf8338c5-fb6e-4593-a4a8-b3c4946ee2a0 + control-id: sc-8.1 + description: >- + MongoDB supports TLS 1.x to encrypt data in transit, preventing + unauthorized disclosure or changes to information during + transmission. To implement TLS, set the PEMKeyFile option in the + configuration file /etc/mongod.conf to the certificate file's path + and restart the the component. +{{< /highlight >}} + +To document this, we use the [`control-implementations`](/reference/latest/component-definition/json-reference/#/component-definition/components/control-implementations) key. Items associated with this key require a unique identifier, which is provided using the `uuid` key. These items also have a `source` key that is used to provide a URI reference to the appropriate OSCAL catalog or profile. The URI reference can be a URI, a relative reference, or a fragment that points to a [`back-matter`](/reference/latest/component-definition/json-reference/#/component-definition/back-matter) resource. The `implemented-requirements` key on line 13 is where we can specify the control (e.g., SC-8(1)) and the implementation description. Each item under the `implemented-requirements` key also has its own unique identifier `uuid`, and the control is specified using the `control-id` key on line 15. We then use the `description` key to describe how this component can satisfy the specified control. + +In the example above, we demonstrated how to use OSCAL to document the MongoDB software component's control implementation for NIST control SC-8(1). However, one could document how the same component also satisfies controls from other security risk management frameworks (e.g., FedRAMP, ISO 27002, etc.) by simply adding additional [`control-implementations`](/reference/latest/component-definition/json-reference/#/component-definition/components/control-implementations) items for each catalog or profile. Likewise, for each `control-implementations` item, we can add additional `implemented-requirements` items for every control that can be implemented by the component. Additionally, we can address implementations at the control statement-level using the [`statements`](/reference/latest/component-definition/json-reference/#/component-definition/components/control-implementations/implemented-requirements/statements) key, allowing implementation details to be provided in a more fine-grained way. +{{% /tab %}} +{{% /tabs %}} + +## The Final Component Definition + +Combining all the content described in this tutorial, we can produce a completed component definition instance. Provided below are well-formed complete examples. Having these implementation details readily available in an OSCAL component definition means they can be used to populate an OSCAL SSP and should give SSP authors helpful content for their control implementation statements. These examples can also be downloaded in [XML]({{< param "contentRepoPath" >}}/examples/component-definition/xml/example-component-definition.xml), +[JSON]({{< param "contentRepoPath" >}}/examples/component-definition/json/example-component-definition.json), +and [YAML]({{< param "contentRepoPath" >}}/examples/component-definition/yaml/example-component-definition.yaml). + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + + + MongoDB Component Definition Example + 2001-08-26T23:11:47Z + 20210826 + 1.0.0 + + Provider + + + MongoDB + + + + + MongoDB + +

MongoDB is a source-available, cross-platform document-oriented + database program. Classified as a NoSQL database program, MongoDB + uses JSON-like documents with optional schemas.

+ + Provides a NoSQL database service + + ef7c799a-c50e-49ab-83e0-515e989e6df1 + + + Primary daemon process for the MongoDB system. + + + + MongoDB protocol for sharding with shardsrv option. + + + + MongoDB protocol for configsrv operation. + + + + +

MongoDB control implementations for NIST SP 800-53 revision 5.

+ + + +

MongoDB supports TLS 1.x to encrypt data in transit, + preventing unauthorized disclosure or changes to information + during transmission. To implement TLS, set the PEMKeyFile + option in the configuration /etc/mongod.conf to the + certificate file's path and restart the the component.

+ + + + +

Must ensure that MongoDB only listens for network + connections on authorized interfaces by configuring the MongoDB + configuration file to limit the services exposure to only the + network interfaces on which MongoDB instances should listen for + incoming connections.

+ + + + + +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "component-definition": { + "uuid": "a7ba800c-a432-44cd-9075-0862cd66da6b", + "metadata": { + "title": "MongoDB Component Definition Example", + "last-modified": "2001-12-17T09:30:47Z", + "version": 20210507, + "oscal-version": "1.0.0", + "roles": [{ + "id": "supplier", + "title": "Supplier" + }], + "parties": [{ + "uuid": "ef7c799a-c50e-49ab-83e0-515e989e6df1", + "type": "organization", + "name": "MongoDB", + "links": "https://www.mongodb.com" + }] + }, + "components": [{ + "uuid": "91f646c5-b1b6-4786-9ec3-2305a044e217", + "type": "software", + "title": "MongoDB", + "description": "MongoDB is a source-available, cross-platform document-oriented database program. Classified as a NoSQL database program, MongoDB uses JSON-like documents with optional schemas.", + "purpose": "Provides a NoSQL database service", + "responsible-roles": [{ + "role-id": "provider", + "party-uuid": "ef7c799a-c50e-49ab-83e0-515e989e6df1" + }], + "protocols": [{ + "uuid": "2b4a1b3a-cbc5-4cc8-bde6-7437c28c4e54", + "name": "mongodb", + "title": "Primary daemon process for the MongoDB system.", + "port-ranges": [{ + "start": 27017, + "end": 27017, + "transport": "TCP" + }] + }, + { + "uuid": "99d8d4e5-e734-4e05-a2f9-7353097b8b61", + "name": "mongodb-shardsrv", + "title": "MongoDB protocol for sharding with shardsrv option.", + "port-ranges": [{ + "start": 27018, + "end": 27018, + "transport": "TCP" + }] + }, + { + "uuid": "6fa762f1-09ca-44d5-a94c-cfceb57debd5", + "name": "mongodb-configsvr", + "title": "MongoDB protocol for configsrv operation.", + "port-ranges": [{ + "start": 27019, + "end": 27019, + "transport": "TCP" + }] + }], + "control-implementations": [{ + "uuid": "49f0b690-ed9f-4f32-aae0-625b77aa6d27", + "source": "https://github.com/usnistgov/oscal-content/blob/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_MODERATE-baseline_profile.json", + "description": "MongoDB control implementations for NIST SP 800-53 + revision 5.", + "implemented-requirements" [{ + "uuid": "cf8338c5-fb6e-4593-a4a8-b3c4946ee2a0", + "control-id": "sc-8.1", + "description": "MongoDB supports TLS 1.x to encrypt data in transit, + preventing unauthorized disclosure or changes to information + during transmission. To implement TLS, set the PEMKeyFile option + in the configuration file /etc/mongod.conf to the certificate + file's path and restart the the component." + }] + }] + }] + } +} +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- +component-definition: + uuid: a7ba800c-a432-44cd-9075-0862cd66da6b + metadata: + title: MongoDB Component Definition Example + last-modified: '2001-12-17T09:30:47Z' + version: 20210507 + oscal-version: 1.0.0 + roles: + - id: provider + title: Provider + parties: + - uuid: ef7c799a-c50e-49ab-83e0-515e989e6df1 + type: organization + name: MongoDB + links: + - href: + rel: website + components: + - uuid: 91f646c5-b1b6-4786-9ec3-2305a044e217 + type: software + title: MongoDB + description: >- + MongoDB is a source-available, cross-platform document-oriented + database program. Classified as a NoSQL database program, MongoDB + uses JSON-like documents with optional schemas. + purpose: Provides a NoSQL database service + responsible-roles: + - role-id: provider + party-uuid: ef7c799a-c50e-49ab-83e0-515e989e6df1 + protocols: + - uuid: 2b4a1b3a-cbc5-4cc8-bde6-7437c28c4e54 + name: mongodb + title: Primary daemon process for the MongoDB system. + port-ranges: + - start: 27017 + end: 27017 + transport: TCP + - uuid: 99d8d4e5-e734-4e05-a2f9-7353097b8b61 + name: mongodb-shardsrv + title: MongoDB protocol for sharding with shardsrv option. + port-ranges: + - start: 27018 + end: 27018 + transport: TCP + - uuid: 6fa762f1-09ca-44d5-a94c-cfceb57debd5 + name: mongodb-configsvr + title: MongoDB protocol for configsrv operation. + port-ranges: + - start: 27019 + end: 27019 + transport: TCP + control-implementations: + - uuid: 49f0b690-ed9f-4f32-aae0-625b77aa6d27 + source: + description: >- + MongoDB control implementations for NIST SP 800-53rev5. + implemented-requirements: + - uuid: cf8338c5-fb6e-4593-a4a8-b3c4946ee2a0 + control-id: sc-8.1 + description: >- + MongoDB supports TLS 1.x to encrypt data in transit, preventing + unauthorized disclosure or changes to information during + transmission. To implement TLS, set the PEMKeyFile option in the + configuration file /etc/mongod.conf to the certificate file's path + and restart the the component. +{{< /highlight >}} +{{% /tab %}} +{{% /tabs %}} + +## Summary + +This concludes the tutorial. You should now be familiar with: + +- The basic structure of a component definition in OSCAL. +- How to provide the basic metadata required in an OSCAL component definition. +- How to define a component within an OSCAL component definition. +- How to use the protocol elements in a component. +- How to specify the control implementation for a component. + +For more information, you can review the OSCAL component definition model [documentation](/concepts/layer/implementation/component-definition/). From 80ae9d4c1f3f6aa6cab257454235ab8ae47428fb Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Sun, 29 Aug 2021 10:58:59 -0400 Subject: [PATCH 3/9] Adding unique constraint to enforce unique set-parameter entries. --- src/metaschema/oscal_profile_metaschema.xml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index a573ee5ef5..c1774c4838 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -246,6 +246,14 @@ + + + + +

Since multiple set-parameter entries can be provided, each parameter must be set only once.

+ + + From ca7337d3a8f07b07262a72d9683359a49aac2a6c Mon Sep 17 00:00:00 2001 From: Michaela Iorga Date: Tue, 14 Sep 2021 17:08:37 -0400 Subject: [PATCH 4/9] added XACTA 360 to the Tools page. --- docs/content/tools/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content/tools/_index.md b/docs/content/tools/_index.md index 64273b4111..02a19bf0c0 100644 --- a/docs/content/tools/_index.md +++ b/docs/content/tools/_index.md @@ -36,3 +36,4 @@ See the [NIST Software Disclaimer](https://www.nist.gov/disclaimer) for more inf | [OSCAL REST API](https://github.com/EasyDynamics/oscal-rest) | Easy Dynamics | An initial OpenAPI definition of an OSCAL REST API that describes how systems might manipulate catalogs, profiles, components, and SSPs. | | [XSLT Tooling](https://github.com/usnistgov/oscal-tools/tree/master/xslt) | NIST OSCAL Project | A variety of Extensible Stylesheet Language (XSL) Transformations (XSLT), Cascading Style Sheets (CSS), and related utilities for authoring, converting, and publishing OSCAL content in various forms. | | [XML Jelly Sandwich](https://github.com/wendellpiez/XMLjellysandwich) | Wendell Piez (NIST) | Interactive XSLT in the browser includes [OSCAL demonstrations](https://wendellpiez.github.io/XMLjellysandwich/oscal/). | +| [Xacta 360](https://www.telos.com/offerings/xacta-360-continuous-compliance-assessment/) | Telos | Xacta 360 is a cyber risk management and compliance analytics platform that enables users to create and submit FedRAMP system security plans (SSPs) in OSCAL format. Future OSCAL capabilities are forthcoming as the standard evolves. | \ No newline at end of file From 1282467803fdc796372fc3488b50e97e061f29ab Mon Sep 17 00:00:00 2001 From: Michaela Iorga Date: Thu, 16 Sep 2021 16:48:25 -0400 Subject: [PATCH 5/9] Updated the tools table on the website. --- docs/content/tools/_index.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/content/tools/_index.md b/docs/content/tools/_index.md index 02a19bf0c0..6c41d02649 100644 --- a/docs/content/tools/_index.md +++ b/docs/content/tools/_index.md @@ -26,14 +26,14 @@ If you have produced a tool that supports the OSCAL formats that you would like See the [NIST Software Disclaimer](https://www.nist.gov/disclaimer) for more information. -## Open Source Tools and Libraries - -| Name | Provider/Developer | Description | -|:---|:---|:---| -| [Compliance trestle](https://github.com/IBM/compliance-trestle) | IBM | A python SDK and command line tool which manipulates OSCAL structures and supports transformation of data into OSCAL. | -| [OSCAL Java Library](https://github.com/usnistgov/liboscal-java) | NIST OSCAL Project | A Java-based programming API for reading and writing content conformant to the OSCAL XML, JSON, and YAML based models. | -| [OSCAL React Component Library](https://github.com/EasyDynamics/oscal-react-library) | Easy Dynamics | A library of reusable React components and an [example user interface application](https://oscal-viewer.msd.easydynamics.com/catalog) that provides a direct UI into OSCAL. | -| [OSCAL REST API](https://github.com/EasyDynamics/oscal-rest) | Easy Dynamics | An initial OpenAPI definition of an OSCAL REST API that describes how systems might manipulate catalogs, profiles, components, and SSPs. | -| [XSLT Tooling](https://github.com/usnistgov/oscal-tools/tree/master/xslt) | NIST OSCAL Project | A variety of Extensible Stylesheet Language (XSL) Transformations (XSLT), Cascading Style Sheets (CSS), and related utilities for authoring, converting, and publishing OSCAL content in various forms. | -| [XML Jelly Sandwich](https://github.com/wendellpiez/XMLjellysandwich) | Wendell Piez (NIST) | Interactive XSLT in the browser includes [OSCAL demonstrations](https://wendellpiez.github.io/XMLjellysandwich/oscal/). | -| [Xacta 360](https://www.telos.com/offerings/xacta-360-continuous-compliance-assessment/) | Telos | Xacta 360 is a cyber risk management and compliance analytics platform that enables users to create and submit FedRAMP system security plans (SSPs) in OSCAL format. Future OSCAL capabilities are forthcoming as the standard evolves. | \ No newline at end of file +## OSCAL Tools and Libraries + +| Name | Provider/Developer | Description | Type | +|:---|:---|:---|:---| +| [Compliance trestle](https://github.com/IBM/compliance-trestle) | IBM | A python SDK and command line tool which manipulates OSCAL structures and supports transformation of data into OSCAL. | open source | +| [OSCAL Java Library](https://github.com/usnistgov/liboscal-java) | NIST OSCAL Project | A Java-based programming API for reading and writing content conformant to the OSCAL XML, JSON, and YAML based models. | open source | +| [OSCAL React Component Library](https://github.com/EasyDynamics/oscal-react-library) | Easy Dynamics | A library of reusable React components and an [example user interface application](https://oscal-viewer.msd.easydynamics.com/catalog) that provides a direct UI into OSCAL. | open source | +| [OSCAL REST API](https://github.com/EasyDynamics/oscal-rest) | Easy Dynamics | An initial OpenAPI definition of an OSCAL REST API that describes how systems might manipulate catalogs, profiles, components, and SSPs. | open source | +| [XSLT Tooling](https://github.com/usnistgov/oscal-tools/tree/master/xslt) | NIST OSCAL Project | A variety of Extensible Stylesheet Language (XSL) Transformations (XSLT), Cascading Style Sheets (CSS), and related utilities for authoring, converting, and publishing OSCAL content in various forms. | open source | +| [XML Jelly Sandwich](https://github.com/wendellpiez/XMLjellysandwich) | Wendell Piez (NIST) | Interactive XSLT in the browser includes [OSCAL demonstrations](https://wendellpiez.github.io/XMLjellysandwich/oscal/). | open source | +| [Xacta 360](https://www.telos.com/offerings/xacta-360-continuous-compliance-assessment/) | Telos | Xacta 360 is a cyber risk management and compliance analytics platform that enables users to create and submit FedRAMP system security plans (SSPs) in OSCAL format. Future OSCAL capabilities are forthcoming as the standard evolves. | [license](https://cdn.telos.com/wp-content/uploads/2021/06/22150746/Xacta-360-EULA-US.pdf) | \ No newline at end of file From 83615b83e5fa7dfb7a3c06a01e78715ad14bd809 Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Tue, 28 Sep 2021 00:17:02 +1000 Subject: [PATCH 6/9] utils: fix SyntaxWarning on content validator (#1026) Resolves #1025 --- src/utils/util/oscal-content-validator.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/utils/util/oscal-content-validator.py b/src/utils/util/oscal-content-validator.py index ee1fdab896..dfa20b4f56 100755 --- a/src/utils/util/oscal-content-validator.py +++ b/src/utils/util/oscal-content-validator.py @@ -20,7 +20,7 @@ def _get_oscal_file_type(filename): def read_file(filename, ftype): with io.open(filename, 'r', encoding="utf-8") as f: - if ftype is "json": + if ftype == "json": filedata = json.load(f) else: filedata = f.read() @@ -42,9 +42,9 @@ def oscal_validator(oscal_schema, oscal_data): schema, stype = read_file(oscal_schema, _get_oscal_file_type(oscal_schema)) data, ftype = read_file(oscal_data, _get_oscal_file_type(oscal_data)) - if ftype is 'json': + if ftype == 'json': validate(data, schema) - if ftype is 'xml': + if ftype == 'xml': xmlschema.validate(data, schema) From 81abd8133134a25c9c7d2dab93243f0d919f716b Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 5 Oct 2021 11:11:13 -0400 Subject: [PATCH 7/9] Bump nokogiri from 1.11.5 to 1.12.5 in /docs (#1029) Bumps [nokogiri](https://github.com/sparklemotion/nokogiri) from 1.11.5 to 1.12.5. - [Release notes](https://github.com/sparklemotion/nokogiri/releases) - [Changelog](https://github.com/sparklemotion/nokogiri/blob/main/CHANGELOG.md) - [Commits](https://github.com/sparklemotion/nokogiri/compare/v1.11.5...v1.12.5) --- updated-dependencies: - dependency-name: nokogiri dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- docs/Gemfile.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 2023d62873..9f5f602ff2 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -15,9 +15,9 @@ GEM typhoeus (~> 1.3) yell (~> 2.0) mercenary (0.4.0) - mini_portile2 (2.5.1) - nokogiri (1.11.5) - mini_portile2 (~> 2.5.0) + mini_portile2 (2.6.1) + nokogiri (1.12.5) + mini_portile2 (~> 2.6.1) racc (~> 1.4) nokogumbo (2.0.4) nokogiri (~> 1.8, >= 1.8.4) From 3cbb38efcd80da1b5e8b84e34831604253c89420 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Thu, 7 Oct 2021 14:18:00 -0400 Subject: [PATCH 8/9] Improvements to converter readme docs (#1027) * Improvements to readme docs for both XML-to-JSON and JSON-to-XML XSLT conversion pathways --- json/README.md | 21 ++++++++++++++++++++- xml/README.md | 23 +++++++++++++++++++++-- 2 files changed, 41 insertions(+), 3 deletions(-) diff --git a/json/README.md b/json/README.md index 71860a88ae..bd4a3a8181 100644 --- a/json/README.md +++ b/json/README.md @@ -72,6 +72,25 @@ The following example uses **Saxon HE** to convert an OSCAL catalog XML file to java -jar "saxon9he.jar" -xsl:"oscal_catalog_xml-to-json-converter.xsl" -s:"oscal-catalog.xml" -o:"oscal-catalog.json" json-indent=yes ``` -The Saxon JAR file is named ```saxon9he.jar```. The catalog converter is specified as ```-xsl:"oscal_catalog_xml-to-json-converter.xsl"```, the source catalog XML file is specified as ```-s:"oscal-catalog.xml"```, and the destination catalog JSON file is specified as ```-o:"oscal-catalog.json"```. Paths\names of these files need to be provided based on the location of the files on your computer. +> *Note*: at time of writing, Saxon 9 users are being encouraged to upgrade systems to Saxon use 10, and the stylesheets provided should function equally well or better with the later software. However until we have experience testing it and assuring it runs without error, Saxon 9 is designated here. +> +> Operators of XSLT-based platforms should by all means test these processes with any XSLT 3.0 conformant processor, and report problems to us via Github Issues. + +Paths\names of these files need to be provided based on the location of the files on your computer: + +* The Saxon JAR file is named ```saxon9he.jar```. +* The catalog converter is specified as ```-xsl:"oscal_catalog_xml-to-json-converter.xsl"``` +* The source catalog XML file is specified as ```-s:"oscal-catalog.xml"``` +* The destination catalog JSON file is specified as ```-o:"oscal-catalog.json"```. The [online documentation](http://www.saxonica.com/documentation/#!using-xsl/commandline) for *Saxon* provides more information on the command line arguments. + +### Alternate invocations + +The configuration just provided will convert a JSON file given as a file reference, into OSCAL XML. There are also different configurations available for debugging: + +* `-it:from-xml` (indicating initial template) - provides the default XSLT entry point explicitly. +* `-file:mycatalog.xml` used with explicit `-it:from-xml` will look for the XML at the location given by the parameter, instead of on the source port (given by `-s`). This configuration parallels the JSON-to-XML converter. +* `produce=supermodel` as a runtime parameter will emit not OSCAL XML, but the intermediate format produced by the converter (a so-called 'OSCAL supermodel' derived from its metaschema): useful for debugging or as a pivot to other serializations. +* `produce=xpath-json` will produce the results in an XML format defined by the XPath function `json-to-xml()`, which when consumed by the complementary function `xml-to-json()` can deterministically provide syntactically correct JSON. This XML format is used internally to provide the JSON data description, to be cast into JSON as a (terminal) serialization step. Expressing the transformation results in this format directly can provide insight for debugging, especially in failure conditions (when the syntax cannot be written). See https://www.w3.org/TR/xpath-functions-31/#func-json-to-xml for more details on this format. + diff --git a/xml/README.md b/xml/README.md index 9167227fdc..70cc9ff66e 100644 --- a/xml/README.md +++ b/xml/README.md @@ -68,9 +68,28 @@ The OSCAL project uses *Saxon-HE* with Java version 8 or greater. The following example uses **Saxon HE** to convert an OSCAL catalog JSON file to XML using one of the NIST-provided [JSON to XML XSLT converters](convert). This example assumes that has been installed and the Saxon-HE jar files have already unzipped. ``` -java -jar "saxon9he.jar" -xsl:"oscal_catalog_json-to-xml-converter.xsl" -o:"oscal-catalog.xml" -it json-file="oscal-catalog.json" +java -jar "saxon9he.jar" -xsl:"oscal_catalog_json-to-xml-converter.xsl" -o:"oscal-catalog.xml" -it:make-xml json-file="oscal-catalog.json" ``` -The Saxon JAR file is named ```saxon9he.jar```. The catalog converter is specified as ```-xsl:"oscal_catalog_json-to-xml-converter.xsl"```, the source catalog JSON file is specified as ```json-file="oscal-catalog.json"```, and the destination catalog XML file is specified as ```-o:"oscal-catalog.xml"```. Paths\names of these files need to be provided based on the location of the files on your computer. +> *Note*: at time of writing, Saxon 9 users are being encouraged to upgrade systems to use Saxon 10, and the stylesheets provided should function equally well or better with the later software. However until we have experience testing it and assuring it runs without error, Saxon 9 is designated here. +> +> Operators of XSLT-based platforms should by all means test these processes with any XSLT 3.0 conformant processor, and report problems to us via Github Issues. + +`-it` indicates the initial template (XSLT entry point) should be `make-xml`. + +Paths\names given to other settings are offered as relative or absolute system paths or URIs: + +* The Saxon JAR file is named ```saxon9he.jar``` (system path). +* The catalog converter is specified as ```-xsl:"oscal_catalog_json-to-xml-converter.xsl"``` (relative or absolute URI) +* The source catalog JSON file is specified as ```json-file="oscal-catalog.json"``` (URI) +* The destination catalog XML file is specified as ```-o:"oscal-catalog.xml"``` (URI) The [online documentation](http://www.saxonica.com/documentation/#!using-xsl/commandline) for *Saxon* provides more information on the command line arguments. + +### Alternate invocations + +The configuration just provided will convert a JSON file given as a file reference, into OSCAL XML. There are also different configurations available for debugging: + +* `-it` (initial template) `from-xdm-json-xml` - assume the source is not given as a URI reference to a file, but as XML conformant to the model returned by the XPath function 'json-to-xml()'. In this case, the `file` parameter must point to this XML file not a JSON file. +* Alternatively, `-s:file.xml` (with or instead of `-it`) will operate the same way, except finding the XML at `file.xml`. +* `produce=supermodel` as a runtime parameter will emit not OSCAL XML, but the intermediate format produced by the converter (a so-called 'OSCAL supermodel' derived from its metaschema): useful for debugging or as a pivot to other serializations. From fc8b3eb4fde39e5b24ef00ae05afe0740c535b3d Mon Sep 17 00:00:00 2001 From: Alexander Stein Date: Thu, 14 Oct 2021 12:29:47 -0400 Subject: [PATCH 9/9] Add approval assembly to encode a role, party, and approval date. --- src/metaschema/oscal_metadata_metaschema.xml | 40 ++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/metaschema/oscal_metadata_metaschema.xml b/src/metaschema/oscal_metadata_metaschema.xml index 7ae1c7acbd..d4e3759bfa 100644 --- a/src/metaschema/oscal_metadata_metaschema.xml +++ b/src/metaschema/oscal_metadata_metaschema.xml @@ -52,6 +52,9 @@ + + + @@ -737,6 +740,43 @@ + + + Approval + An approval for content from a role within a given party. + + Approval Universally Unique Identifier + A unique identifier that can be used to reference this defined approval elsewhere in an OSCAL document. A UUID should be consistently used for a given location across revisions of the document. + + + Responsible Role + The approving role in the responsible party. + + + The party responsible for the approval. + + + The date and time when the approval occurred. + + + + + + + + + + + + + + + + + + + + Responsible Role A reference to one or more roles with responsibility for performing a function relative to the containing object.