From 6381eeebe15d0138e27f7d4a079afd7e7256d716 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Fri, 27 Aug 2021 18:34:26 -0400 Subject: [PATCH] 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/).