From 1f6154f0b02e67355629f8fd81f1acf97001f22c Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Tue, 8 Jun 2021 13:42:37 -0400 Subject: [PATCH] Addressing typos for issue #947. (#955) --- docs/content/about/_index.md | 4 +- docs/content/about/use-cases/_index.md | 6 +- docs/content/concepts/layer/_index.md | 2 +- .../concepts/layer/control/catalog/_index.md | 2 +- docs/content/concepts/layer/overview.md | 12 +- docs/content/concepts/relations-to-other.md | 2 +- docs/content/concepts/terminology/_index.md | 2 +- .../content/contribute/model-review/_index.md | 2 +- .../model-review/oscal-model-review.ics | 2 +- docs/content/learn/presentations/_index.md | 2 +- docs/content/learn/tutorials/_index.md | 1 + .../content/learn/tutorials/catalog/_index.md | 8 +- .../tutorials}/validation-modeling.md | 113 ++++++++++-------- .../assessment-plan/json-definitions.md | 2 +- .../assessment-plan/json-reference.md | 4 +- .../assessment-plan/xml-definitions.md | 2 +- .../assessment-plan/xml-reference.md | 4 +- .../assessment-results/json-definitions.md | 2 +- .../assessment-results/xml-definitions.md | 2 +- .../json-definitions.md | 2 +- .../json-reference.md | 4 +- .../xml-definitions.md | 2 +- .../xml-reference.md | 4 +- docs/content/reference/datatypes.md | 4 +- docs/content/reference/release-notes.md | 4 +- .../profile-resolution-specml.xml | 2 +- 26 files changed, 107 insertions(+), 89 deletions(-) rename docs/content/{concepts/layer/implementation => learn/tutorials}/validation-modeling.md (57%) diff --git a/docs/content/about/_index.md b/docs/content/about/_index.md index 5c069dddfc..01fd11fab3 100644 --- a/docs/content/about/_index.md +++ b/docs/content/about/_index.md @@ -27,7 +27,7 @@ There are a number of complicating factors contributing to the challenges faced * Regulatory standards and frameworks overlap in scope and can often conflict or be difficult to manage together; and * Information systems are increasing in size and complexity. -To address information security and privacy risks, the implementation of selected controls need to be verified and shown to be effective. To provide assurance of a system's security and privacy posture, the control implementation of a system must be both correctly described, assessed, and authorized. These tasks are resource-intensive, and often challenging to perform within budget constraints given the complexity of the problem. +To address information security and privacy risks, the implementation of selected controls needs to be verified and shown to be effective. To provide assurance of a system's security and privacy posture, the control implementation of a system must be both correctly described, assessed, and authorized. These tasks are resource-intensive, and often challenging to perform within budget constraints given the complexity of the problem. The standardized formats provided by the OSCAL project help to streamline and standardize the processes of documenting, implementing and assessing security controls. The automation enabled by the OSCAL formats will reduce complexity, decrease implementation costs, and enable the simultaneous, continuous assessment of a system's security against multiple sets of requirements. Additionally, paperwork will be significantly reduced. @@ -59,7 +59,7 @@ The OSCAL project is working to address the following goals. Drive a large decrease in the paperwork burden for both information security professionals and vendors. -- Normalize the representation of security control catalogs, regulatory frameworks, and system information using precise, machine readable formats. +- Normalize the representation of security control catalogs, regulatory frameworks, and system information using precise, machine-readable formats. - Allow the sharing of control implementation information across communities. ### Improve System Security Assessments diff --git a/docs/content/about/use-cases/_index.md b/docs/content/about/use-cases/_index.md index 24f7f2dd55..257d678253 100644 --- a/docs/content/about/use-cases/_index.md +++ b/docs/content/about/use-cases/_index.md @@ -29,9 +29,9 @@ To meet the requirements of different regulatory frameworks and to perform good OSCAL is designed to provide a standardized format that reduces or eliminates this paper-based process, by transitioning documentation to a highly normalized, machine-readable format. This approach has multiple benefits: -1. data between plans is consistent in both format and mapping to requirements and controls from multiple regulatory frameworks, when applicable, -1. data is machine readable and can be exposed to other security tools to provide additional automation, and -1. data consistency and standardization allows for innovation in the commercial tooling to provide further automation of assessment and accreditation processes. +1. Data between plans is consistent in both format and mapping to requirements and controls from multiple regulatory frameworks, when applicable, +1. Data is machine-readable and can be exposed to other security tools to provide additional automation, and +1. Data consistency and standardization support innovation in commercial and open-source tooling to provide further automation of assessment and accreditation processes. By representing system information using the OSCAL [system security plan model](/concepts/layer/implementation/ssp/), this data can be analyzed using automated processes, streamlining the review and assessment process. The management systems that are used to manage the security and privacy controls implemented in the system can be integrated to provide up-to-date system information using this model. Human-oriented documentation can be easily generated from the OSCAL data. This results in a more usable information set over what is provided using Word and Excel files alone. diff --git a/docs/content/concepts/layer/_index.md b/docs/content/concepts/layer/_index.md index 59f963bd68..96bb5fd752 100644 --- a/docs/content/concepts/layer/_index.md +++ b/docs/content/concepts/layer/_index.md @@ -37,7 +37,7 @@ The following image depicts each layer and the corresponding model(s) for each l {{Control Layer}} {{}} -Each OSCAL model is represented in multiple, machine readable *formats* (e.g., XML, JSON, YAML), which provide a serialization and encoding mechanism for representing and exchanging OSCAL data, also referred to as *OSCAL content*. +Each OSCAL model is represented in multiple, machine-readable *formats* (e.g., XML, JSON, YAML), which provide a serialization and encoding mechanism for representing and exchanging OSCAL data, also referred to as *OSCAL content*. Individual layers are summarized below, with links to additional layer and model information. There is also an [introduction to the OSCAL models](overview/), as well as information related to the [terminology](../terminology/) used in describing each model. diff --git a/docs/content/concepts/layer/control/catalog/_index.md b/docs/content/concepts/layer/control/catalog/_index.md index e6fb33894d..8604f12132 100644 --- a/docs/content/concepts/layer/control/catalog/_index.md +++ b/docs/content/concepts/layer/control/catalog/_index.md @@ -22,7 +22,7 @@ aliases: The OSCAL catalog model represents a collection of [controls](/concepts/terminology/#control), represented as a control [catalog](/concepts/terminology/#catalog). -The OSCAL catalog model was designed to represent security and privacy controls in standardized, machine readable formats. The OSCAL catalog model standardizes the representation of control definitions from different sources (e.g., SP 800-53, ISO/IEC 27002, COBIT 5) allowing control information to be easily searched, imported, and exported by applications using a common format. +The OSCAL catalog model was designed to represent security and privacy controls in standardized, machine-readable formats. The OSCAL catalog model standardizes the representation of control definitions from different sources (e.g., SP 800-53, ISO/IEC 27002, COBIT 5) allowing control information to be easily searched, imported, and exported by applications using a common format. The OSCAL catalog model was designed to represent security and privacy controls; however, it may be possible to apply OSCAL to other applications related to safety, health, or other purposes. These other applications have not been explored so far. diff --git a/docs/content/concepts/layer/overview.md b/docs/content/concepts/layer/overview.md index b45351af14..c0a1ddbd40 100644 --- a/docs/content/concepts/layer/overview.md +++ b/docs/content/concepts/layer/overview.md @@ -83,7 +83,7 @@ UUIDs in OSCAL are intended to uniquely identify information and link informatio Version 4 Universally Unique Identifier (UUID) as defined by [RFC 4122](https://tools.ietf.org/html/rfc4122) are a good fit for this use case and have been selected for use in OSCAL for this purpose. -Fields containing UUIDs tend to be named `uuid` in OSCAL. When an associated subject is created that has a `uuid` field, then a tool should automatically generate a UUId for this field. +Fields containing UUIDs tend to be named `uuid` or `xyz-uuid` (where `xyz` refers to the referenced subject with the assigned UUID) in OSCAL. When an associated subject is created that has a `uuid` field, then a tool should automatically generate a UUID for this field. UUIDs are intended to be consistently used to represent the same concept over multiple major and minor revisions of the same document; thus, they should only be changed if the underlying identified subject has changed in a significant way that no longer represents the same identified subject. @@ -101,7 +101,7 @@ Identifiers may be referenced from other locations within OSCAL content using on ## Metadata Overview -Every OSCAL document has a metadata section that shares the same structure. The required fields in metadata as as follows: +Every OSCAL document has a metadata section that shares the same structure. The required fields in metadata are as follows: 1. title: A human readable title for the document, represented in markdown. 2. last-modified: The date and time that the document was last modified. @@ -123,7 +123,7 @@ When used this way, document-id allows for consumers of OSCAL docum OSCAL recommends the use of link to establish resolvable version graphs of OSCAL documents. [RFC5829](https://tools.ietf.org/html/rfc5829) defines a set of values for the rel flag of link that allow for a document to provides resolvable links to the latest version, the next version, and the previous version. With this combination of links, a human or machine consumer of an OSCAL document can understand the version history of a document, and automatically update itself to the latest version. -Note that successful deployment of version control through link requires the document creator to maintain a well-structured static set of ersolvable resources that are reachable from where ever the document is to be consumed (usually on the public web). +Note that successful deployment of version control through link requires the document creator to maintain a well-structured static set of resolvable resources that are reachable from wherever the document is consumed (usually on the public web). As an example of such a system, let us assume that "Author" has just released OSCAL document "Example 1.0". They can now setup a redirect system based on the document-id: @@ -177,15 +177,15 @@ In addition to providing improved control over modeling and documentation, the f OSCAL models are designed to be broadly applicable to a variety of security compliance frameworks and organizational needs. Where an organization has unique modeling needs not supported by the core OSCAL syntax, it is possible to extend the syntax to address these requirements. -Models in OSCAL are organized hierarchically. At each level of this hierarchy, OSCAL syntax provides property (JSON: `property` / XML: `prop`) and annotation (`annotation`) objects. While these are sometimes used for core OSCAL syntax, they can also be assigned an organizational namespace (`ns`) value, which uniquely identifies the organization creating the extension. +Models in OSCAL are organized hierarchically. At each level of this hierarchy, OSCAL syntax provides property (JSON: `property` / XML: `prop`) objects. While these properties are sometimes used for core OSCAL syntax, they can also be assigned an organizational namespace (`ns`) value, which uniquely identifies the organization creating the extension. -For any property or annotation identified with the organization's namespace, the organization may use any [NCName](/reference/datatypes/#ncname) value in the property/annotation's `name`. This allows the organization to define the containing content as required. Organizations are strongly encouraged to publish these extensions to their community of OSCAL tool developers. +For any property identified with the organization's namespace, the organization may use any [token](/reference/datatypes/#token) value in the property's `name`. This allows the organization to define the containing content as required. Organizations are strongly encouraged to publish these extensions to their community of OSCAL tool developers. {{% callout %}} **IMPORTANT NOTE TO DEVELOPERS** Tools should always check for the `ns` assignment within properties and annotations. -When no `ns` is provided, the default is `http://csrc.nist.gov/ns/oscal`, which means the annotation or property is assumed to be part of the core OSCAL syntax. +When no `ns` is provided, the default is `http://csrc.nist.gov/ns/oscal`, which means the property is assumed to be part of the core OSCAL syntax. This is especially important as organizations extending OSCAL may use the same `name` value, but in a different namespace as compared to core OSCAL. diff --git a/docs/content/concepts/relations-to-other.md b/docs/content/concepts/relations-to-other.md index 006b744822..440fd14ea1 100644 --- a/docs/content/concepts/relations-to-other.md +++ b/docs/content/concepts/relations-to-other.md @@ -23,7 +23,7 @@ OSCAL seeks to complement HTML and other web technologies such as Markdown, by f ### MS Word/Excel formats .docx .xlsx (word processor and spreadsheet) -Microsoft's Office Open XML is the format underlying its Word and Excel applications; it is documented as ISO. Ubiquitous as an application format, these formats are tractable using tools built to the applications' APIs and data models, but they are not designed to support application-independepent data exchange. OSCAL enables greater data interoperability among disparate systems by capturing the semantics of controls, independent of how they may be displayed using various representations (such as word processors). However, we expect that word processors and spreadsheets will continue to be used in workflows supporting OSCAL, supported where necessary by data conversion utilities. +Microsoft's Office Open XML is the format underlying its Word and Excel applications; it is documented as ISO. Ubiquitous as an application format, these formats are tractable using tools built to the applications' APIs and data models, but they are not designed to support application-independent data exchange. OSCAL enables greater data interoperability among disparate systems by capturing the semantics of controls, independent of how they may be displayed using various representations (such as word processors). However, we expect that word processors and spreadsheets will continue to be used in workflows supporting OSCAL, supported where necessary by data conversion utilities. ### OpenOffice formats .odt .ods (word processor and spreadsheet formats) diff --git a/docs/content/concepts/terminology/_index.md b/docs/content/concepts/terminology/_index.md index 461d756233..51f47a1094 100644 --- a/docs/content/concepts/terminology/_index.md +++ b/docs/content/concepts/terminology/_index.md @@ -105,7 +105,7 @@ A baseline, or overlay in other terminology, defines a specific set of selected {{}}NIST Special Publication (SP) [800-37 Revision 2](https://csrc.nist.gov/publications/detail/sp/800-37/rev-2/final) defines a baseline as "the set of controls that are applicable to information or an information system to meet legal, regulatory, or policy requirements, as well as address protection needs for the purpose of managing risk."{{}} -Using the OSCAL profile model to express a baselines makes the mappings between the control catalog and the profile explicit and machine readable. A single OSCAL profile can reference controls in multiple catalogs. OSCAL permits profiles to use the same interoperable format irrespective of which catalogs are being used. +Using the OSCAL profile model to express a baseline makes the mappings between the control catalog and the profile explicit and machine-readable. A single OSCAL profile can reference controls in multiple catalogs. OSCAL permits profiles to use the same interoperable format irrespective of which catalogs are being used. The figure below uses the NIST SP 800-53 low baseline as an example to sketch how a baseline relates to a catalog. The low baseline indicates which controls from the NIST SP 800-53 catalog are required for compliance with this baseline. diff --git a/docs/content/contribute/model-review/_index.md b/docs/content/contribute/model-review/_index.md index ab9ae2cbdd..b97d4ed509 100644 --- a/docs/content/contribute/model-review/_index.md +++ b/docs/content/contribute/model-review/_index.md @@ -33,7 +33,7 @@ Each bi-weekly teleconference will cover some or all of the following topics: - Reviewing one or more of the OSCAL models - Answering questions on model usage -- Discussing property and annotation values +- Discussing property values and other controlled vocabularies - Collecting feedback on how to improve the models and related documentation We specifically want to hear from community members that are authoring OSCAL content and creating OSCAL tools. ***Your [feedback](/contact/) is important to us***, which is the primary reason we are hosting these teleconferences. diff --git a/docs/content/contribute/model-review/oscal-model-review.ics b/docs/content/contribute/model-review/oscal-model-review.ics index c336225129..e79d7a0f92 100644 --- a/docs/content/contribute/model-review/oscal-model-review.ics +++ b/docs/content/contribute/model-review/oscal-model-review.ics @@ -24,7 +24,7 @@ CREATED:20210421T162550Z DESCRIPTION:We will be hosting the first of a set of bi-weekly meetings to review the OSCAL models on Friday\, May 15th\, 2020.\n\n \n\nDuring these meetings we will be:\n\n* Reviewing the OSCAL models\n* Answering question - s on model usage\n* Discussing property and annotation values\n* Collectin + s on model usage\n* Discussing property values and other controlled vocabularies\n* Collectin g feedback on how to improve the models and related documentation\n\n \n\n If you are interested in developing OSCAL content or tools\, we would enco urage you to participate.\n\n \n\nMeeting Info:\n\n \n\nhttps://bluejeans. diff --git a/docs/content/learn/presentations/_index.md b/docs/content/learn/presentations/_index.md index 3b9f2beec9..b5214ac472 100644 --- a/docs/content/learn/presentations/_index.md +++ b/docs/content/learn/presentations/_index.md @@ -9,5 +9,5 @@ The following are presentations on OSCAL-related topics. Some of the older prese - [Using Leveraged Authorizations in OSCAL](/presentations/oscal-leveraged-authorizations-v6a.pdf) presented during the [OSCAL Model Review](/contribute/model-review/) - July 24, 2020 - [OSCAL Assessment Models Overview](/presentations/oscal-ap-ar-poam-v3.pdf) presented during the [Lunch with the OSCAL Developers](/contribute/dev-lunch/) - July 2, 2020 - [NIST OSCAL Workshop](OSCAL-workshop-20191105.pdf) - November 5, 2019 -- [Security Automation Simplified via NIST OSCAL: We're Not in Kansas Anymore](https://www.youtube.com/watch?v=eP8K7piU5UQ) presented at RSAConference 2018 - April 18, 2018 +- [Security Automation Simplified via NIST OSCAL: We're Not in Kansas Anymore](https://www.youtube.com/watch?v=eP8K7piU5UQ) presented at RSA Conference 2018 - April 18, 2018 - [Automating Security and Compliance via a New Standard of Standards](https://www.youtube.com/watch?v=mo3J0tFxixg) presented at Docker Government Summit 2018 - April 11, 2018 diff --git a/docs/content/learn/tutorials/_index.md b/docs/content/learn/tutorials/_index.md index a5a1b92af4..e38c4488b4 100644 --- a/docs/content/learn/tutorials/_index.md +++ b/docs/content/learn/tutorials/_index.md @@ -6,4 +6,5 @@ suppresstopiclist: true 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/). +- [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/_index.md b/docs/content/learn/tutorials/catalog/_index.md index bbaa2751b4..f8c3747d76 100644 --- a/docs/content/learn/tutorials/catalog/_index.md +++ b/docs/content/learn/tutorials/catalog/_index.md @@ -530,7 +530,7 @@ Another required piece of information for a control is the control's title provi While optional in the OSCAL model, the need often exists to provide a section or control label that is used to identify the control within its source document. Using the `` element, an OSCAL property with the name `label` is used to provide the section number label value. This is illustrated on line 3. -Finally, a control must have a set of control statements. Shown on lines 4 thru 6, a `` element with the name `statement` provides the required statement text using [HTML markup](/reference/datatypes/#markup-multiline). This uses the same part structure we reviewed earlier in this tutorial for defining text within a group. This part is also assigns the identifier `s1.1.1_stm` using the `@id` attribute. This identifier can be used to reference the specific statement in the OSCAL catalog. +Finally, a control must have a set of control statements. Shown on lines 4 thru 6, a `` element with the name `statement` provides the required statement text using [HTML markup](/reference/datatypes/#markup-multiline). This uses the same part structure we reviewed earlier in this tutorial for defining text within a group. This part is also assigning the identifier `s1.1.1_stm` using the `@id` attribute. This identifier can be used to reference the specific statement in the OSCAL catalog. {{% /tab %}} {{% tab %}} {{< highlight json "linenos=table" >}} @@ -557,7 +557,7 @@ Another required piece of information for a control is the control's title provi While optional in the OSCAL model, the need often exists to provide a section or control label that is used to identify the control within its source document. The `properties` JSON property provides an array of OSCAL property objects. An OSCAL property with the name `label` is used to provide the section number label value. This is illustrated on lines 5 thru 8. -Finally, a control must have a set of control statements. Shown on lines 9 thru 13, the `parts` property allows an array of part JSON objects to be provided. a part object with the name `statement` provides the required statement text using [Markdown text](/reference/datatypes/#markup-multiline). This uses the same part structure we reviewed earlier in this tutorial for defining text within a group. This part is also assigns the identifier `s1.1.1_stm` using the `id` property. This identifier can be used to reference the specific statement in the OSCAL catalog. +Finally, a control must have a set of control statements. Shown on lines 9 thru 13, the `parts` property allows an array of part JSON objects to be provided. a part object with the name `statement` provides the required statement text using [Markdown text](/reference/datatypes/#markup-multiline). This uses the same part structure we reviewed earlier in this tutorial for defining text within a group. This part is also assigning the identifier `s1.1.1_stm` using the `id` property. This identifier can be used to reference the specific statement in the OSCAL catalog. {{% /tab %}} {{% tab %}} {{< highlight yaml "linenos=table" >}} @@ -580,11 +580,11 @@ Another required piece of information for a control is the control's title provi While optional in the OSCAL model, the need often exists to provide a section or control label that is used to identify the control within its source document. The `properties` key provides an array of OSCAL property items. An OSCAL property is defined on lines 5 thru 6, with a name `label` and the value `1.1.1` to provide the section number label value. -Finally, a control must have a set of control statements. Shown on lines 8 thru 10, a list of parts identified using the `parts` key allows a list of part YAML items to be provided. a part object with the name `statement` provides the required statement text using [Markdown text](/reference/datatypes/#markup-multiline). This uses the same part structure we reviewed earlier in this tutorial for defining text within a group. This part is also assigns the identifier `s1.1.1_stm` using the `id` property. This identifier can be used to reference the specific statement in the OSCAL catalog. +Finally, a control must have a set of control statements. Shown on lines 8 thru 10, a list of parts identified using the `parts` key allows a list of part YAML items to be provided. a part object with the name `statement` provides the required statement text using [Markdown text](/reference/datatypes/#markup-multiline). This uses the same part structure we reviewed earlier in this tutorial for defining text within a group. This part is also assigning the identifier `s1.1.1_stm` using the `id` property. This identifier can be used to reference the specific statement in the OSCAL catalog. {{% /tab %}} {{< /tabs >}} -This represents the minimum information for defining a control. The next section discuss how to provide additional control-related information. +This represents the minimum information for defining a control. The next section discusses how to provide additional control-related information. ### Including Implementation Guidance and Other Supplemental Information diff --git a/docs/content/concepts/layer/implementation/validation-modeling.md b/docs/content/learn/tutorials/validation-modeling.md similarity index 57% rename from docs/content/concepts/layer/implementation/validation-modeling.md rename to docs/content/learn/tutorials/validation-modeling.md index 2f86b022d7..6583418f37 100644 --- a/docs/content/concepts/layer/implementation/validation-modeling.md +++ b/docs/content/learn/tutorials/validation-modeling.md @@ -1,6 +1,7 @@ --- title: Representing Test Validation Information heading: "Representing Test Validation Information for Components" +summary: "A mini-tutorial on providing test validation information (e.g., FIPS 140-2 validation) as an OSCAL component." weight: 60 toc: enabled: true @@ -11,7 +12,13 @@ aliases: - /documentation/schema/implementation-layer/validation-modeling/ --- -OSCAL's implementation layer models enable authors to capture testing validation information about components. The validation information is represented as a separate component, which is then linked to any component on which the validation was performed. +This tutorial covers describing test validation information (e.g., FIPS-140-2) using an OSCAL component. 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/) and [system security plan](/concepts/layer/implementation/ssp/) model overviews. + +OSCAL's implementation layer models enable authors to capture testing validation information related to components. The validation information is represented as a component, which is then linked to a separate component on which the validation was performed. For example, this approach can be used with a product containing a cryptographic module that has received a FIPS 140-2 validation by a NIST accredited laboratory. The product is represented as one `component`, and the validation information is represented in a different `component`. The two components are then linked as follows: @@ -41,65 +48,67 @@ For example, this approach can be used with a product containing a cryptographic {{% tab %}} {{< highlight json >}} { - "components": { - "11111111-0000-4000-a000-000000000001": { - "type": "hardware", - "title": "Product Name", - "description": "Describe the product's function.", - "links": [ - { - "rel": "validation", - "href": "#22222222-0000-4000-a000-000000000002" - } - ], - "status": { - "state": "operational" - } - }, - "22222222-0000-4000-a000-000000000002": { - "type": "validation", - "title": "Validation Name", - "description": "Describe the validation.", - "props": [ - { - "name": "validation-type", - "value": "fips-140-2" - }, - { - "name": "validation-reference", - "value": "xxxx" - } - ], - "links": [ - { - "rel": "validation-details", - "href": "https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/xxxx" - } - ], - "status": { - "state": "operational" - } - } - } + "components": [ + { + "uuid": "11111111-0000-4000-a000-000000000001", + "type": "hardware", + "title": "Product Name", + "description": "Describe the product's function.", + "links": [ + { + "rel": "validation", + "href": "#22222222-0000-4000-a000-000000000002" + } + ], + "status": { + "state": "operational" + } + }, + { + "uuid": "22222222-0000-4000-a000-000000000002", + "type": "validation", + "title": "Validation Name", + "description": "Describe the validation.", + "props": [ + { + "name": "validation-type", + "value": "fips-140-2" + }, + { + "name": "validation-reference", + "value": "xxxx" + } + ], + "links": [ + { + "rel": "validation-details", + "href": "https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/xxxx" + } + ], + "status": { + "state": "operational" + } + } + } } {{< /highlight >}} {{% /tab %}} {{% tab %}} {{< highlight yaml>}} components: - 11111111-0000-4000-a000-000000000001: + - uuid: 11111111-0000-4000-a000-000000000001: type: hardware title: Product Name description: Describe the product's function. links: - - rel: validation + - rel: validation href: #22222222-0000-4000-a000-000000000002 status: state: operational - 22222222-0000-4000-a000-000000000002: + - uuid: 22222222-0000-4000-a000-000000000002: component-type: validation - title: Validation Name - description: Describe the validation. + title: Validation Name + description: Describe the validation. props: - name: validation-type value: fips-140-2 @@ -115,12 +124,20 @@ For example, this approach can be used with a product containing a cryptographic {{< /tabs >}} The example above depicts two linked components: -- Component #1 (`11111111-0000-4000-a000-000000000001`) is a hardware component, which was has achieved a FIPS 140-2 validation from NIST Labs. +- Component #1 (`11111111-0000-4000-a000-000000000001`) is a hardware component, which has achieved a FIPS 140-2 validation from a NIST validated testing lab. - Component #2 (`22222222-0000-4000-a000-000000000002`) is a component representing the validation itself. -The only additional information necessary in component #1 is the link (XML:`link`, JSON/YAML: `links`) to component #2. The link's `rel` must be set to `validation`, and the `href` contains a URI fragment, wish is the UUID of the second component, prepended with a hashtag (`#`). +The only additional information necessary in component #1 is the link (XML:`link`, JSON/YAML: `links`) to component #2. The link's `rel` must be set to `validation`, and the `href` contains a URI fragment, which is the UUID of the second component, prepended with a hashtag (`#`). This link creates a `validation` association between the hardware component and the validation component. In component #2, details are provided about the validation. There must be at least two properties (XML:`prop`, JSON/YAML:`properties`) and a link. - `validation-type` property: a value depicting the type of validation, such as `fips-140-2` for a FIPS 140-2 validation. - `validation-reference` property: a value containing the identifier assigned by the validating body, such as the FIPS 140-2 certificate number. - `validation-details` link: A link to an online information provided by the authorizing body. This should be as specific as possible to the validation product. For example, for FIPS 140-2 validated products, the link should point to the specific certificate listing in the NIST Labs database. Additional links may be included, such as for the main page of the validating organization's web site. + +# Summary + +In this tutorial you learned: + +- How to create a validation component. +- How to provide validation details in a validation component. +- How to associate a validation component with another component using a link. diff --git a/docs/content/reference/1.0.0-rc2/assessment-plan/json-definitions.md b/docs/content/reference/1.0.0-rc2/assessment-plan/json-definitions.md index 1d661e6231..59fbc9f58f 100644 --- a/docs/content/reference/1.0.0-rc2/assessment-plan/json-definitions.md +++ b/docs/content/reference/1.0.0-rc2/assessment-plan/json-definitions.md @@ -3517,7 +3517,7 @@ The following is a reference for the JSON object definitions derived from this m

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/assessment-plan/json-reference.md b/docs/content/reference/1.0.0-rc2/assessment-plan/json-reference.md index abeeed0742..aec27cc43d 100644 --- a/docs/content/reference/1.0.0-rc2/assessment-plan/json-reference.md +++ b/docs/content/reference/1.0.0-rc2/assessment-plan/json-reference.md @@ -3261,7 +3261,7 @@ The following is the JSON format reference for this model, which is organized hi

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

@@ -3270,7 +3270,7 @@ The following is the JSON format reference for this model, which is organized hi

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/assessment-plan/xml-definitions.md b/docs/content/reference/1.0.0-rc2/assessment-plan/xml-definitions.md index d6fcee42d0..0a10526265 100644 --- a/docs/content/reference/1.0.0-rc2/assessment-plan/xml-definitions.md +++ b/docs/content/reference/1.0.0-rc2/assessment-plan/xml-definitions.md @@ -3493,7 +3493,7 @@ The following is a reference for the XML element and attribute types derived fro

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/assessment-plan/xml-reference.md b/docs/content/reference/1.0.0-rc2/assessment-plan/xml-reference.md index 14021991e8..59cea9bb35 100644 --- a/docs/content/reference/1.0.0-rc2/assessment-plan/xml-reference.md +++ b/docs/content/reference/1.0.0-rc2/assessment-plan/xml-reference.md @@ -3420,7 +3420,7 @@ The following is the XML format reference for this model, which is organized hie

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

@@ -3429,7 +3429,7 @@ The following is the XML format reference for this model, which is organized hie

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/assessment-results/json-definitions.md b/docs/content/reference/1.0.0-rc2/assessment-results/json-definitions.md index be8ef0e83c..92d3a996b5 100644 --- a/docs/content/reference/1.0.0-rc2/assessment-results/json-definitions.md +++ b/docs/content/reference/1.0.0-rc2/assessment-results/json-definitions.md @@ -3582,7 +3582,7 @@ The following is a reference for the JSON object definitions derived from this m

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/assessment-results/xml-definitions.md b/docs/content/reference/1.0.0-rc2/assessment-results/xml-definitions.md index 332fd13843..351e87b6cd 100644 --- a/docs/content/reference/1.0.0-rc2/assessment-results/xml-definitions.md +++ b/docs/content/reference/1.0.0-rc2/assessment-results/xml-definitions.md @@ -3570,7 +3570,7 @@ The following is a reference for the XML element and attribute types derived fro

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/json-definitions.md b/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/json-definitions.md index fd12596375..0206053c20 100644 --- a/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/json-definitions.md +++ b/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/json-definitions.md @@ -3133,7 +3133,7 @@ The following is a reference for the JSON object definitions derived from this m

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/json-reference.md b/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/json-reference.md index 8f0740aa3a..30502195a3 100644 --- a/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/json-reference.md +++ b/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/json-reference.md @@ -3276,7 +3276,7 @@ The following is the JSON format reference for this model, which is organized hi

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

@@ -3285,7 +3285,7 @@ The following is the JSON format reference for this model, which is organized hi

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/xml-definitions.md b/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/xml-definitions.md index 269a4d81c5..ac59121a14 100644 --- a/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/xml-definitions.md +++ b/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/xml-definitions.md @@ -3114,7 +3114,7 @@ The following is a reference for the XML element and attribute types derived fro

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/xml-reference.md b/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/xml-reference.md index 24f502ec93..3209a0701d 100644 --- a/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/xml-reference.md +++ b/docs/content/reference/1.0.0-rc2/plan-of-action-and-milestones/xml-reference.md @@ -3435,7 +3435,7 @@ The following is the XML format reference for this model, which is organized hie

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

@@ -3444,7 +3444,7 @@ The following is the XML format reference for this model, which is organized hie

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

If a local reference using a fragment is used, this will be indicated by a fragment - "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

+ "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

diff --git a/docs/content/reference/datatypes.md b/docs/content/reference/datatypes.md index 5749980ced..adef933283 100644 --- a/docs/content/reference/datatypes.md +++ b/docs/content/reference/datatypes.md @@ -337,11 +337,11 @@ Note that elements such as `div`, `blockquote`, `section` or `aside`, used in HT In addition, there are contexts in OSCAL where prose usage may be further constrained. For example, at a higher level (outside the base schema) an OSCAL application could forbid the use of prose headers `h1-h6` in favor of nested OSCAL `part` elements with their own titles. -The OSCAL Markdown syntax is loosely based on CommonMark. When in doubt about Markdown features and syntax, we look to CommonMark for guidance, largely because it is more rigorously tested than many others forms of Markdown. +The OSCAL Markdown syntax is loosely based on CommonMark. When in doubt about Markdown features and syntax, we look to CommonMark for guidance, largely because it is more rigorously tested than many other forms of Markdown. ### markup-line -The following table describes the equavalent constructs in HTML and Markdown used in OSCAL within the `markup-line` data type. +The following table describes the equivalent constructs in HTML and Markdown used in OSCAL within the `markup-line` data type. | Markup Type | HTML | Markdown | |:--- |:--- |:--- | diff --git a/docs/content/reference/release-notes.md b/docs/content/reference/release-notes.md index 5fda8971fc..2b696920cd 100644 --- a/docs/content/reference/release-notes.md +++ b/docs/content/reference/release-notes.md @@ -36,7 +36,7 @@ The following general changes were made in this release. - In prior OSCAL releases, the data types used in the OSCAL XML and JSON schemas did not require that provided strings are non-empty (see issue [usnistgov/OSCAL#805](https://github.com/usnistgov/OSCAL/issues/805)), and leading and trailing whitespace was also allowed (see issue [usnistgov/OSCAL#805](https://github.com/usnistgov/OSCAL/issues/805)). Some XML parsers that are schema aware are capable of removing this extra whitespace based on the `whiteSpace="collapse"` schema facet. This only works if the parser is schema aware. To normalize this behavior across all parsers, the OSCAL string data types will now not allow leading and trailing whitespace. - This lead to updates to the string data types in XML and JSON. The `ncname` data type was also replaced by `token` (see issue [usnistgov/OSCAL#911](https://github.com/usnistgov/OSCAL/issues/911)). + This led to updates to the string data types in XML and JSON. The `ncname` data type was also replaced by `token` (see issue [usnistgov/OSCAL#911](https://github.com/usnistgov/OSCAL/issues/911)). ### Changes to Profile Model @@ -82,7 +82,7 @@ The following changes were made in OSCAL 1.0.0 Release Candidate (RC) 2 since OS ### Changes common to all models -- "props" and "annotations" in JSON, and "prop" and "annotation in XML, have been merged into a single property that now allows an optional `remark` and `uuid`. Semantically, the optional `remark` and `uuid` were the only difference between a "prop" and an "annotation" in OSCAL. The resulting model is simpler with a single construct that will always allow a remark. Names and values that were allowed on annotations are now allowed on properties. +- "props" and "annotations" in JSON, and "prop" and "annotation" in XML, have been merged into a single property that now allows an optional `remark` and `uuid`. Semantically, the optional `remark` and `uuid` were the only difference between a "prop" and an "annotation" in OSCAL. The resulting model is simpler with a single construct that will always allow a remark. Names and values that were allowed on annotations are now allowed on properties. - `latest-version`, `predecessor-version`, and `successor-version` link relations were added to allow an OSCAL document to link to latest, previous, and next document revisions. - Markup content may now contain data insertion points for data other than parameters. The `insert` object, which may appear in markup content strings, now supports a `type` which can be used to indicate the type of data to insert, and an `id-ref` that identifies the specific data object to take data from. diff --git a/src/specifications/profile-resolution/profile-resolution-specml.xml b/src/specifications/profile-resolution/profile-resolution-specml.xml index c57ada9ba3..e66f0f0fca 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml.xml @@ -36,7 +36,7 @@ processor's result corresponds to the target as described here, given a particular source.

The term directive is used in these specifications to refer to an element or - combination of elements in source data, which is designed to effect a particular outcome in + combination of elements in source data, which is designed to affect a particular outcome in the target catalog. For the most part, directives are in the source profile document – for example, a set-parameter element in a profile is a directive to set a parameter value in the target catalog.