From 8a6b91ef2dc03ca7ba31d5982d5d412d1e87cee1 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Fri, 11 Oct 2024 16:46:49 -0400 Subject: [PATCH 1/9] Add ADR for system identifier-type and FedRAMP extension namespace values --- ...0-fedramp-identifier-type-and-namespace.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 documents/adr/0010-fedramp-identifier-type-and-namespace.md diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md new file mode 100644 index 000000000..2c86b2e05 --- /dev/null +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -0,0 +1,43 @@ +# 10. FedRAMP System Identifier Type and Namespace + +Date: 2024-10-11 + +## Status + +Proposed + +## Context + +The FedRAMP automation team needs to provide clear guidance on the acceptable values for an SSP system `identifier-type` and for its extension `prop` namespace values. + +The OSCAL models specify a set of allowed values for `identifier-type` (see [OSCAL Metaschema Model](https://github.com/usnistgov/OSCAL/blob/4f02dac6f698efda387cc5f55bc99581eaf494b6/src/metaschema/oscal_implementation-common_metaschema.xml#L676-L704)). For FedRAMP systems, the only allowed value is "http://fedramp.gov/ns/oscal" because "https://fedramp.gov" is deprecated. However, use of "http://fedramp.gov/ns/oscal" for `identifier-type` may cause some confusion as FedRAMP extensions currently have `@ns` values of "https://fedramp.gov/ns/oscal" (notice the difference - **http** vs **https**). + +## Possible Solutions + +The team considered multiple approaches listed below. + +1. **Option 1** - require "https://fedramp.gov" for both `identifier-type` and `prop` namespaces attribute value. + - Pros - both the `identifier-type` and FedRAMP extension `@ns` share the same value, reducing confusion. + - Cons - this value is marked as a deprecated `identifier-type` in the NIST model, thus creating a misalignment between core OSCAL and FedRAMP OSCAL requirements. + +2. **Option 2** - require "http://fedramp.gov/ns/oscal" for both `identifier-type` and `prop`. + - Pros - this approach aligns with NIST allowed values for `identifier-type` + - Cons - however, this approach is likely to impact the community since FedRAMP extensions will all need to be updated (e.g., change "https" to "http" in existing FedRAMP OSCAL documents). OSCAL content generating tools will also be impacted by the `@ns` change for FedRAMP extensions. + +3. **Option 3** - require "https://fedramp.gov/ns/oscal" for both `identifier-type` and `prop`. + - Pros - perceived lesser impact on existing FedRAMP OSCAL documents and tools, as only the `identifier-type` would require change. + - Cons - this approach does not align with NIST allowed-value for `identifier-type` which may cause confusion, thus creating a misalignment between core OSCAL and FedRAMP OSCAL requirements. + +4. **Option 4** - go with "http://fedramp.gov/ns/oscal" for `identifier-type`, and "https://fedramp.gov/ns/oscal" for FedRAMP extension `prop` namespaces. + - Pros - this approach aligns with NIST OSCAL allowed value for `identifier-type`, while preserving the current FedRAmP extention `prop` namespace value. This requires no change to existing FedRAMP OSCAL content or tools. + - Cons - FedRAMP OSCAL practitioners may be confused by the minor, subtle difference in allowed values for `identifier-type` and FedRAMP extention `prop` namespaces. + +## Decision + +TBD + +## Consequences + +Each of the proposed options will require some updates by the FedRAMP automation team to documentation at https://automate.fedramp.gov/documentation as well as updates to the codebase (including FedRAMP OSCAL profiles, FedRAMP OSCAL templates, and FedRAMP constraints). + +Community impact will depend on the which approach is ultimately selected. \ No newline at end of file From c4572b16c3d794b1da0bd20f59b784f14c27befa Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Wed, 23 Oct 2024 17:42:56 -0400 Subject: [PATCH 2/9] Update ADR --- documents/adr/0010-fedramp-identifier-type-and-namespace.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md index 2c86b2e05..eb18bdca8 100644 --- a/documents/adr/0010-fedramp-identifier-type-and-namespace.md +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -34,10 +34,8 @@ The team considered multiple approaches listed below. ## Decision -TBD +Proceed with option 4 to minimize impact to OSCAL SSP authors. There is only one instance of the use of `identifier-type` in an OSCAL SSP, the potential impact if SSP authors need to update it is minimal, and it is easy to identify / enforce with constraints. Option 4 eliminates any impact to SSP authors, an requires no or minimal updates to the [FedRAMP Developer Hub](https://automate.fedramp.gov/documentation) documentation site. ## Consequences -Each of the proposed options will require some updates by the FedRAMP automation team to documentation at https://automate.fedramp.gov/documentation as well as updates to the codebase (including FedRAMP OSCAL profiles, FedRAMP OSCAL templates, and FedRAMP constraints). - -Community impact will depend on the which approach is ultimately selected. \ No newline at end of file +Option 4 will provide clarity around the acceptable values for an SSP system `identifier-type` and for its extension `prop` namespace values, with minimal impact to the community. \ No newline at end of file From 3fb73b6c2b8034ec59d94e39ca92176fa58f3e8c Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Tue, 29 Oct 2024 16:13:51 -0400 Subject: [PATCH 3/9] Update documents/adr/0010-fedramp-identifier-type-and-namespace.md Co-authored-by: A.J. Stein --- documents/adr/0010-fedramp-identifier-type-and-namespace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md index eb18bdca8..429df79e6 100644 --- a/documents/adr/0010-fedramp-identifier-type-and-namespace.md +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -34,7 +34,7 @@ The team considered multiple approaches listed below. ## Decision -Proceed with option 4 to minimize impact to OSCAL SSP authors. There is only one instance of the use of `identifier-type` in an OSCAL SSP, the potential impact if SSP authors need to update it is minimal, and it is easy to identify / enforce with constraints. Option 4 eliminates any impact to SSP authors, an requires no or minimal updates to the [FedRAMP Developer Hub](https://automate.fedramp.gov/documentation) documentation site. +Proceed with Option 2. The inconsistency in documentation and tooling was the source of a bug that initiated an investigation and led to this ADR. This change will have an impact on updating documentation for FedRAMP, but there is little evidence or public feedback to indicate one or more community-maintained tools warrant this concern. Alignment sooner rather than later by FedRAMP, who will operationalize the FedRAMP constraints, is a key factor to prioritize this change the soonest major release, not defer it until later. ## Consequences From e5c18c486b68cf72e4b7af92659c945c4b718f81 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Tue, 29 Oct 2024 16:25:01 -0400 Subject: [PATCH 4/9] Update 0010-fedramp-identifier-type-and-namespace.md --- documents/adr/0010-fedramp-identifier-type-and-namespace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md index 429df79e6..c845d6c36 100644 --- a/documents/adr/0010-fedramp-identifier-type-and-namespace.md +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -38,4 +38,4 @@ Proceed with Option 2. The inconsistency in documentation and tooling was the s ## Consequences -Option 4 will provide clarity around the acceptable values for an SSP system `identifier-type` and for its extension `prop` namespace values, with minimal impact to the community. \ No newline at end of file +While not backwards compatible, option 2 will provide is more understandable and maintainable long-term, which should prevent misunderstandings in the future. From fe68350b7556ac81784e99217a34072a5ad458f9 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Tue, 29 Oct 2024 16:46:15 -0400 Subject: [PATCH 5/9] Update ADR 10 to include 'system' attribute --- ...0-fedramp-identifier-type-and-namespace.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md index c845d6c36..93e55a7ac 100644 --- a/documents/adr/0010-fedramp-identifier-type-and-namespace.md +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -8,29 +8,29 @@ Proposed ## Context -The FedRAMP automation team needs to provide clear guidance on the acceptable values for an SSP system `identifier-type` and for its extension `prop` namespace values. +The FedRAMP automation team needs to provide clear guidance on the acceptable values for an SSP system `identifier-type`, for its extension `prop` namespace values, and the naming system identifier `system` attribute (used in the assessent results and POA&M). -The OSCAL models specify a set of allowed values for `identifier-type` (see [OSCAL Metaschema Model](https://github.com/usnistgov/OSCAL/blob/4f02dac6f698efda387cc5f55bc99581eaf494b6/src/metaschema/oscal_implementation-common_metaschema.xml#L676-L704)). For FedRAMP systems, the only allowed value is "http://fedramp.gov/ns/oscal" because "https://fedramp.gov" is deprecated. However, use of "http://fedramp.gov/ns/oscal" for `identifier-type` may cause some confusion as FedRAMP extensions currently have `@ns` values of "https://fedramp.gov/ns/oscal" (notice the difference - **http** vs **https**). +The OSCAL models specify a set of allowed values for `identifier-type` (see [OSCAL Metaschema Model](https://github.com/usnistgov/OSCAL/blob/4f02dac6f698efda387cc5f55bc99581eaf494b6/src/metaschema/oscal_implementation-common_metaschema.xml#L676-L704)). For FedRAMP systems, the only allowed value is "http://fedramp.gov/ns/oscal" because "https://fedramp.gov" is deprecated. However, use of "http://fedramp.gov/ns/oscal" for `identifier-type` may cause some confusion as FedRAMP extensions currently have `@ns` values of "https://fedramp.gov/ns/oscal" (notice the difference - **http** vs **https**). Currently, the allowed value forr naming system identifier (in the assessment results and POA&M) is "https://fedramp.gov/ns/oscal". ## Possible Solutions The team considered multiple approaches listed below. -1. **Option 1** - require "https://fedramp.gov" for both `identifier-type` and `prop` namespaces attribute value. - - Pros - both the `identifier-type` and FedRAMP extension `@ns` share the same value, reducing confusion. +1. **Option 1** - require "https://fedramp.gov" for `identifier-type`, `system`, and `prop` namespaces attribute value. + - Pros - the `identifier-type`, `system`, and FedRAMP extension `@ns` share the same value, reducing confusion. - Cons - this value is marked as a deprecated `identifier-type` in the NIST model, thus creating a misalignment between core OSCAL and FedRAMP OSCAL requirements. -2. **Option 2** - require "http://fedramp.gov/ns/oscal" for both `identifier-type` and `prop`. - - Pros - this approach aligns with NIST allowed values for `identifier-type` +2. **Option 2** - require "http://fedramp.gov/ns/oscal" for `identifier-type`, `system`, and `prop`. + - Pros - this approach aligns with NIST allowed values for `identifier-type`, and has the added benefit of reducing confusion since all use the same FedRAMP URI value. - Cons - however, this approach is likely to impact the community since FedRAMP extensions will all need to be updated (e.g., change "https" to "http" in existing FedRAMP OSCAL documents). OSCAL content generating tools will also be impacted by the `@ns` change for FedRAMP extensions. -3. **Option 3** - require "https://fedramp.gov/ns/oscal" for both `identifier-type` and `prop`. +3. **Option 3** - require "https://fedramp.gov/ns/oscal" for `identifier-type`, `system`, and `prop` namespaces attribute value. - Pros - perceived lesser impact on existing FedRAMP OSCAL documents and tools, as only the `identifier-type` would require change. - Cons - this approach does not align with NIST allowed-value for `identifier-type` which may cause confusion, thus creating a misalignment between core OSCAL and FedRAMP OSCAL requirements. -4. **Option 4** - go with "http://fedramp.gov/ns/oscal" for `identifier-type`, and "https://fedramp.gov/ns/oscal" for FedRAMP extension `prop` namespaces. - - Pros - this approach aligns with NIST OSCAL allowed value for `identifier-type`, while preserving the current FedRAmP extention `prop` namespace value. This requires no change to existing FedRAMP OSCAL content or tools. - - Cons - FedRAMP OSCAL practitioners may be confused by the minor, subtle difference in allowed values for `identifier-type` and FedRAMP extention `prop` namespaces. +4. **Option 4** - go with "http://fedramp.gov/ns/oscal" for `identifier-type`, and "https://fedramp.gov/ns/oscal" for FedRAMP extension `prop` namespaces and `system`. + - Pros - this approach aligns with NIST OSCAL allowed value for `identifier-type`, while preserving the current FedRAMP extention `prop` namespace value. This requires no change to existing FedRAMP OSCAL content or tools. + - Cons - FedRAMP OSCAL practitioners may be confused by the minor, subtle difference in allowed values for `identifier-type`, `system` and FedRAMP extention `prop` namespaces. ## Decision From d2b79e519799333c391ed570846f72e654ebc4e6 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Thu, 31 Oct 2024 14:46:44 -0400 Subject: [PATCH 6/9] Update ADR 10 option 2 description Co-authored-by: Gabeblis --- documents/adr/0010-fedramp-identifier-type-and-namespace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md index 93e55a7ac..6d259910c 100644 --- a/documents/adr/0010-fedramp-identifier-type-and-namespace.md +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -38,4 +38,4 @@ Proceed with Option 2. The inconsistency in documentation and tooling was the s ## Consequences -While not backwards compatible, option 2 will provide is more understandable and maintainable long-term, which should prevent misunderstandings in the future. +Option 2 is not backwards compatible, as it requires updates to existing FedRAMP documentation. However, it establishes a consistent and maintainable standard that will reduce ambiguity in the long term. Implementing this now also minimizes the risk of future misalignment. From be8a576ca22a1cd67f57c3f845d32a337dbc2a81 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Thu, 31 Oct 2024 14:47:10 -0400 Subject: [PATCH 7/9] Fix ADR10 typo Co-authored-by: Gabeblis --- documents/adr/0010-fedramp-identifier-type-and-namespace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md index 6d259910c..7d3b570a7 100644 --- a/documents/adr/0010-fedramp-identifier-type-and-namespace.md +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -10,7 +10,7 @@ Proposed The FedRAMP automation team needs to provide clear guidance on the acceptable values for an SSP system `identifier-type`, for its extension `prop` namespace values, and the naming system identifier `system` attribute (used in the assessent results and POA&M). -The OSCAL models specify a set of allowed values for `identifier-type` (see [OSCAL Metaschema Model](https://github.com/usnistgov/OSCAL/blob/4f02dac6f698efda387cc5f55bc99581eaf494b6/src/metaschema/oscal_implementation-common_metaschema.xml#L676-L704)). For FedRAMP systems, the only allowed value is "http://fedramp.gov/ns/oscal" because "https://fedramp.gov" is deprecated. However, use of "http://fedramp.gov/ns/oscal" for `identifier-type` may cause some confusion as FedRAMP extensions currently have `@ns` values of "https://fedramp.gov/ns/oscal" (notice the difference - **http** vs **https**). Currently, the allowed value forr naming system identifier (in the assessment results and POA&M) is "https://fedramp.gov/ns/oscal". +The OSCAL models specify a set of allowed values for `identifier-type` (see [OSCAL Metaschema Model](https://github.com/usnistgov/OSCAL/blob/4f02dac6f698efda387cc5f55bc99581eaf494b6/src/metaschema/oscal_implementation-common_metaschema.xml#L676-L704)). For FedRAMP systems, the only allowed value is "http://fedramp.gov/ns/oscal" because "https://fedramp.gov" is deprecated. However, use of "http://fedramp.gov/ns/oscal" for `identifier-type` may cause some confusion as FedRAMP extensions currently have `@ns` values of "https://fedramp.gov/ns/oscal" (notice the difference - **http** vs **https**). Currently, the allowed value for naming system identifier (in the assessment results and POA&M) is "https://fedramp.gov/ns/oscal". ## Possible Solutions From 0c329fc9f7e0691ea48347c29a4bc01baf9be28e Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Thu, 31 Oct 2024 14:48:21 -0400 Subject: [PATCH 8/9] Fix ADR10 wording Co-authored-by: Gabeblis --- documents/adr/0010-fedramp-identifier-type-and-namespace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md index 7d3b570a7..01bd44b22 100644 --- a/documents/adr/0010-fedramp-identifier-type-and-namespace.md +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -22,7 +22,7 @@ The team considered multiple approaches listed below. 2. **Option 2** - require "http://fedramp.gov/ns/oscal" for `identifier-type`, `system`, and `prop`. - Pros - this approach aligns with NIST allowed values for `identifier-type`, and has the added benefit of reducing confusion since all use the same FedRAMP URI value. - - Cons - however, this approach is likely to impact the community since FedRAMP extensions will all need to be updated (e.g., change "https" to "http" in existing FedRAMP OSCAL documents). OSCAL content generating tools will also be impacted by the `@ns` change for FedRAMP extensions. + - Cons - this approach is likely to impact the community since FedRAMP extensions will all need to be updated (e.g., change "https" to "http" in existing FedRAMP OSCAL documents). OSCAL content generating tools will also be impacted by the `@ns` change for FedRAMP extensions. 3. **Option 3** - require "https://fedramp.gov/ns/oscal" for `identifier-type`, `system`, and `prop` namespaces attribute value. - Pros - perceived lesser impact on existing FedRAMP OSCAL documents and tools, as only the `identifier-type` would require change. From 82df5ef52010c7cf42fc2891e5eec1176622f9ea Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Thu, 31 Oct 2024 14:48:40 -0400 Subject: [PATCH 9/9] Fix ADR10 typo Co-authored-by: Gabeblis --- documents/adr/0010-fedramp-identifier-type-and-namespace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0010-fedramp-identifier-type-and-namespace.md b/documents/adr/0010-fedramp-identifier-type-and-namespace.md index 01bd44b22..13760cb14 100644 --- a/documents/adr/0010-fedramp-identifier-type-and-namespace.md +++ b/documents/adr/0010-fedramp-identifier-type-and-namespace.md @@ -29,7 +29,7 @@ The team considered multiple approaches listed below. - Cons - this approach does not align with NIST allowed-value for `identifier-type` which may cause confusion, thus creating a misalignment between core OSCAL and FedRAMP OSCAL requirements. 4. **Option 4** - go with "http://fedramp.gov/ns/oscal" for `identifier-type`, and "https://fedramp.gov/ns/oscal" for FedRAMP extension `prop` namespaces and `system`. - - Pros - this approach aligns with NIST OSCAL allowed value for `identifier-type`, while preserving the current FedRAMP extention `prop` namespace value. This requires no change to existing FedRAMP OSCAL content or tools. + - Pros - this approach aligns with NIST OSCAL allowed value for `identifier-type`, while preserving the current FedRAMP extension `prop` namespace value. This requires no change to existing FedRAMP OSCAL content or tools. - Cons - FedRAMP OSCAL practitioners may be confused by the minor, subtle difference in allowed values for `identifier-type`, `system` and FedRAMP extention `prop` namespaces. ## Decision