diff --git a/documents/adr/0010-fedramp-extensions-registry.md b/documents/adr/0010-fedramp-extensions-registry.md new file mode 100644 index 000000000..38afa4aeb --- /dev/null +++ b/documents/adr/0010-fedramp-extensions-registry.md @@ -0,0 +1,142 @@ +# NN. Implement a Metaschema-based approach for the FedRAMP Extensions Registry + +## Status + +Proposed + +## Context + +OSCAL content authors need clear and consistent guidance on when to uses specialized FedRAMP OSCAL extensions versus when to use generalized core OSCAL props and values, and a clear understanding of the constraints around all extensions (issue [#564](https://github.com/GSA/fedramp-automation/issues/564)). + +As FedRAMP information needs change (e.g., during recent transition from rev 4 to rev 5 baselines), there are cases where the FedRAMP automation team will either need to create new extensions, update existing extensions, or deprecate extensions to align with the new requirements. In these cases, the FedRAMP automation team needs the ability to track all FedRAMP extensions and signal any changes to the community. + +Currently, FedRAMP extension guidance is spread across the following resources: + +- Legacy experimental [FedRMP extensions](https://github.com/GSA/fedramp-automation/blob/b9513d2be64180b0ea96c74b42836af2b368a156/dist/content/rev5/resources/xml/FedRAMP_extensions.xml) registry, however this resource: + 1. is not consistent with FedRAMP's use of external [Metaschema-based validation constraints](https://github.com/GSA/fedramp-automation/blob/develop/src/validations/constraints/README.md#what-are-they) going forward + 2. is deprecated, per [ADR 007](/documents/adr/0007-signal-unsupportent-content-in-github.md) +- The [FedRAMP Developer Hub](https://automate.fedramp.gov/documentation) site, however it can be difficult or time-consuming for OSCAL practitioners to find information about a specific FedRAMP extension. + +This ADR explores a couple of options for effectively maintaining a registry of FedRAMP extensions. +--- + + +## Evaluation of Options + +### Option 1 - FedRAMP Implements a Separate Metaschema model for its Registry + +This option proposes replacing the legacy experimental registry with a new [Metaschema](https://pages.nist.gov/metaschema/)-based FedRAMP Extensions Registry. The FedRAMP OSCAL Extensions Registry will provide a comprehensive machine-readable reference, documenting all of the FedRAMP extensions. FedRAMP will implement XML, JSON, and YAML versions of the registry. For each extension, the registry will document: +- **id** - the extension's unique identifier. +- **formal-name** - the extension's formal name. +- **description** - a brief description of the extension. +- **external-constraint-id** - reference to the identifier of the FedRAMP external constraint(s) (e.g., allowed-values) for this FedRAMP extension. +> Note: FedRAMP is currently implementing validation constraints. The registry will be updated with `external-constraint-id` information as constraint IDs become available. +- **remarks (OPTIONAL)** - additional information regarding the use of this FedRAMP extension. + +The registry will include all FedRAMP extensions, past and present. Any extensions that are no longer supported have a `deprecated` flag in the registry, specifying the the version number where support ceased. The following is an example of the proposed structure for the new FedRAMP Extensions Registry. + +```xml + + + + + + + + FedRAMP Extensions Registry + 2024-10-04T00:00:00Z + 2024-10-04T00:00:00Z + fedramp2.1.0-oscal1.0.4 + + + + + + + + + + + + + Authorization Type +

Identifies the FedRAMP authorization type.

 + + authorization-type + +

The "authorization-type" is used to specify the authorization path of a CSO in the SSP. The extension is also used to specify the authorization path of any leveraged CSOs.

+ + + + + + eAuth Level (OVERALL) +

The overall electronic authentication (eAuth) level applied to the system.

 + +

Deprecated.

+ + + + + +``` + +#### Option 1 Consequences + +The proposed option 1 will: + +- Consolidate the extensions into one machine-readable registry, making it easier for OSCAL practitioners to find guidance on FedRAMP extensions +- Consolidate the extensions into one machine-readable registry, making it easier for OSCAL practitioners to detect any changes (e.g., deprecations, addition of new extensions) +- Consolidate the extensions into one machine-readable registry, providing a central, authoritative source of FedRAMP extension information for the [FedRAMP Developer Hub](https://automate.fedramp.gov/documentation) site to reference (e.g., with deep links) +- Model the FedRAMP registry with Metaschema, making it easier to generate XML and JSON schemas for the registry, and allow the registry to be validated (e.g., using the OSCAL CLI) +- Model the FedRAMP registry with Metaschema, making it easier to automate documentation generation (e.g., using the OSCAL CLI, XSLT, or other methods) +- This approach could lead to drift between the extensions registry and the external constraints (e.g., which item is the source of truth if they have conflicting descriptions, remarks, etc.?) +- This approach adds some complexity (yet another model that may needs to be processed by practitioners) + + +### Option 2 - FedRAMP Leverages its existing External Constraints as Source of Extensions + +This option leverages the existing FedRAMP external constraints ([fedramp-external-allowed-values.xml](../../src/validations/constraints/fedramp-external-allowed-values.xml) and [fedramp-external-constraints](../../src/validations/constraints/fedramp-external-constraints.xml)). + +For example, all FedRAMP extensions have some corresponding constraint(s) (e.g., allowed values, cardinality, etc.). These constraints specify the `context` or `target` (e.g., `"system-implementation//prop[@name='scan-type'][@ns='https://fedramp.gov/ns/oscal']/@value"`) of the constraint. In this case, we can see the FedRAMP "scan-type" `prop` is a FedRAMP extension and can automatically extract that information (**namespace**, **name**) from the FedRAMP allowed values constraints file using XSLT or any scripting approach than can easily process XML source file. We can also easily extract the corresponding **constraint-id**, **description**, **level** and other useful information. The same approach would be used to extract FedRAMP extension information from the FeRAMP external constraints file. + +Ideally, this option would consist of a single parser that would process both files FedRAMP external constraints ([fedramp-external-allowed-values.xml](src/validations/constraints/fedramp-external-allowed-values.xml) and [fedramp-external-constraints](src/validations/constraints/fedramp-external-constraints.xml)), and output a de-duplicated listing of the FedRAMP external constraints with all the pertinent information (**namespace**, **name**, **constraint-id**, **description**, **level**, etc.). + +While the `context` and `target` could be used to identify the FedRAMP constraints, adding a `prop` to the FedRAMP external constraints could further simplify the ability to extract extension information from the external constraints files. + +```xml + + + + + + + + + Duplicate response point at '{ path(.) }'. + + + + +``` + +#### Option 2 Consequences + +The proposed option 2 will: + +- Rely on the existing FedRAMP external constraints as the source of truth for identifying FedRAMP extensions and understanding how they are constrained. +- Use post-processing of the FedRAMP external constraints to generate a machine-readable FedRAMP extensions registry on-demand, providing a central, current and authoritative source of FedRAMP extension information for the [FedRAMP Developer Hub](https://automate.fedramp.gov/documentation) site to reference (e.g., with deep links) + - Alternatively, the extensions registry could enable automatic generation of documentation (e.g., human-readable extensions registry on the [FedRAMP Developer Hub](https://automate.fedramp.gov/documentation) site ) +- Will support generating and converting the registry in XML, JSON, and YAML +- This approach reduces complexity and maintenance by using the existing external constraints as the source for all the FedRAMP extensions. It mitigates the risk for drift between the extensions registry and the external constraints + +--- + +## Decision + +TBD. The FedRAMP automation team will consider these (and other submitted options) for consideration before finalizing a decision. Factors considered in the decision will include: +- Ease of use by OSCAL practitioners - approaches that are most usable by the community are preferred +- Complexity of proposed approach - least amount of necessary complexity is preferred +- Effort / time required to implement - approaches that can be implemented with less effort / provide value to the community sooner are preferred +- Maintainability - approaches that can be maintained more easily are preferred \ No newline at end of file diff --git a/src/content/rev5/resources/xml/README.md b/src/content/rev5/resources/xml/README.md new file mode 100644 index 000000000..709051fe1 --- /dev/null +++ b/src/content/rev5/resources/xml/README.md @@ -0,0 +1,13 @@ +# FedRAMP OSCAL Extensions + +A FedRAMP digital authorization package requires certain information that is not included in the default NIST OSCAL Models. However, organizations can extend OSCAL by defining their own namespaced `prop` fields and `part` assemblies as described in the [NIST Extending OSCAL Models tutorial](https://pages.nist.gov/OSCAL/learn/tutorials/general/extension/). FedRAMP has established its own FedRAMP-specific extensions consisting of `prop` or `part` names, with the unique FedRAMP namespace (ns="https://fedramp.gov/ns/oscal"), that are required in OSCAL documents (SSP, SAP, SAR or POA&M) submitted to FedRAMP. + +The ([FedRAMP OSCAL Extensions Registry](fedramp_extensions_registry.xml)) provides a comprehensive machine-readable reference, documenting all of the FedRAMP extensions. Currently, the registry is provided in XML format, but future releases will also include JSON, and YAML versions of the registry. For each extension, the registry documents: +- **id** - the extension's unique identifier. +- **formal-name** - the extension's formal name. +- **description** - a brief description of the extension. +- **external-constraint-id** - reference to the identifier of the FedRAMP external constraint(s) (e.g., allowed-values) for this FedRAMP extension. +> Note: FedRAMP is currently implementing validation constraints. The registry will be updated with `external-constraint-id` information as constraint IDs become available. +- **remarks (OPTIONAL)** - additional information regarding the use of this FedRAMP extension. + +The registry includes all FedRAMP extensions, past and present. Any extensions that are no longer supported have a `deprecated` flag in the registry, specifying the the version number where support ceased (e.g., `deprecated="fedramp-2.0.0-oscal-1.0.4"`). \ No newline at end of file diff --git a/src/content/rev5/resources/xml/fedramp_extensions_registry.xml b/src/content/rev5/resources/xml/fedramp_extensions_registry.xml new file mode 100644 index 000000000..441101a23 --- /dev/null +++ b/src/content/rev5/resources/xml/fedramp_extensions_registry.xml @@ -0,0 +1,766 @@ + + + + + + + + FedRAMP Extensions Registry + 2024-10-04T00:00:00Z + 2024-10-04T00:00:00Z + fedramp2.1.0-oscal1.0.4 + + + Prepared By + +

The organization that prepared this content.

+ + + + + Federal Risk and Authorization Management Program: Program Management Office + FedRAMP PMO + + info@fedramp.gov +
+ 1800 F St. NW + + Washington + DC + + US +
+ + + + 77e0e2c8-2560-4fe9-ac78-c3ff4ffc9f6d + + + +

This machine-readable file documents how FedRAMP extends OSCAL to meet its information + requirements.

+

It provides the extensions, defined identifiers, and references constraints necessary to + meet FedRAMP Authorization Package requirements.

+ + + + + + + + + Assessment Type +

The type of assessment (e.g., initial authorization, annual assessment, + assessment for a significant change, or another type of assessment).

 + +

Added for rev 5 templates.

+ + + + + Asset Type +

Identifies the type of asset.

 + + + + Authentication Method +

The authentication method(s) for users of a leveraged service or external + interconnection. Refer to for authentication methods NIST 800-63B + (https://pages.nist.gov/800-63-3/sp800-63b.html) for authentication methods

 + +

Added for rev 5 templates.

+ + + + + Authorization Date +

The date the system was authorized. Omit or leave blank for an initial + authorization.

 + + + + Authorization Recommendation +

Indicates whether the assessor recommends the system be authorized by the + authorizing official.

 + +

Deprecated.

+

Use "recommend-authorization" prop instead.

+ + + + + Authorization Type +

Identifies the FedRAMP authorization type.

 + + + + Authorized Users +

The users or roles that can access the leveraged service or external + interconnection.

+ +

Added for rev 5 templates.

+ + + + + Service Processor +

A circuit used for the communication.

 + + + + Control Implementation Status +

Indicates the implementation status of the control.

 + +

Updated bindings and constraint.

+ + + + + Objective Implementation Status +

Indicates the implementation status of the control objective.

 + +

Deprecated.

+

Use "implementation-status" prop instead.

+ + + + + Control Origination +

The point(s) from which the control satisfaction originates.

 + + + + Core Control +

Identifies a control that must be included in every FedRAMP + assessment.

 + +

Core controls must be assessed every year, and are often subject to additional + scrutiny + by assessors and adjudication reviewers.

+ + + + + Cryptographic Module Usage +

The cryptographic module is used for data at rest (DAT) or data in transit + (DIT).

 + +

Added for rev 5 templates.

+ + + + + CSP Validated +

The CSP ensured the independent assessor team roles are appropriately + filled.

 + +

Added for rev 5 templates.

+ + + + + Description +

A brief description of the system.

 + +

Deprecated.

+ + + + + Discrepancies +

Any discrepancies between inventory that was in scope for the planned + assessment + and the assets in the assessment results.

 + +

Added for rev 5 templates.

+ + + + + Discrepancies Reason +

The justification or reason for any discrepancies between inventory that was + in + scope for the planned assessment and the assets in the assessment results.

 + +

Added for rev 5 templates.

+ + + + + False Positive +

The risk was found to be a false positive report.

 + + + + Fully Operational Date +

The date when security control implementations for the appropriate control + baseline was completed.

 + +

Added for rev 5 templates.

+

“Fully operational” means there are no “gaps” in the security control baseline + implementations for the system. The CSP attests that the security controls are + implemented correctly, operating as intended, and producing the desired outcome with + respect to meeting established security requirements.

+ + + + + IA Manual Review +

Confirmation that the independent assessor performed a manual review of (scan) + configuration files to analyze for existing vulnerabilities.

+ +

Added for rev 5 templates.

+ + + + + IA Validated +

The independent assessor ensured the assessment team roles are appropriately + filled.

 + +

Added for rev 5 templates.

+ + + + + Impact Level +

The impact level of a leveraged authorization.

 + +

Added for rev 5 templates.

+ + + + + Profile +

The baseline/profile for this system based on its FIPS-199 + categorization.

 + + + + Transmitted Information +

Describes the information transmitted over the interconnection.

 + + + + Interconnection Compliance +

Any (security) compliance certifications the third party external service has + (e.g., PCI SOC 2, CSA STAR Level 2, etc.).

 + +

Added for rev 5 templates.

+ + + + + Interconnection Data Categorization +

The security impact level of the data (Low, Moderate, High), processed by or + stored in the external service, in accordance with FIPS 199 & NIST 800-60 Vol. + 2.

 + +

Added for rev 5 templates.

+ + + + + Interconnection Data Type +

The type of data / information processed by or stored in the external service, + in + accordance with NIST 800-60 Vol. 2.

 + +

Added for rev 5 templates.

+ + + + + Interconnection Direction +

Identifies the direction of information flow for the + interconnection.

 + +

Deprecated.

+

Use core OSCAL "direction" prop instead.

+ + + + + Interconnection Hosting Environment +

A description of the hosting environment (e.g., corporate network, IaaS, or + self-hosted) for the external service.

 + +

Added for rev 5 templates.

+ + + + + Interconnection Risk +

A description of the potential risks introduced by the external system/service + and impact to the CSO or federal data if the confidentiality, integrity, and + availability + (CIA) of the system/service is compromised.

 + +

Added for rev 5 templates.

+ + + + + Interconnection Security +

Identifies the type of security applied to the interconnection.

 + + + + Interconnection Security +

Identifies the mechanisms/protocol(s) used to secure the + communication.

 + +

Renamed from "connection-security" to "interconnection-security".

+ + + + + Interconnection Type +

Numeric indicator of the type of interconnection, where 1 = Non-FedRAMP + Authorized Cloud Services, 2 = Corporate Shared Services, and 3 = Update Services for + In-Boundary Software/Services.

+ +

Added for rev 5 templates.

+ + + + + Different states of inventory items: public, private, et cetera. +

Indicates if the asset is virtual.

 + +

Deprecated.

+

Use core OSCAL "public" and "virtual" prop instead.

+ + + + + IPv4 Address +

The IP address of a component, inventory item, or other asset.

 + +

Added for rev 5 templates.

+

Core OSCAL has an "ipv4-address" prop which can be used for certain + component types and for inventory items. This extension can be used instead, and is also + applicable for other assemblies such as assessment-platform.

+ + + + + IPv4 Subnet +

The subnet for a component of inventory item.

 + +

Added for rev 5 templates.

+ + + + + ISO/IEC 17020 Identifier +

The ISO/IEC-17020 identifier assigned to the assessor related to their status + as + an A2LA Accredited Third Party Assessment Organization.

 + + + + KEV Catalog +

Indicates if this vulnerability is on the CISA Known Exploited Vulnerabilities + (KEV) Catalog.

 + +

Added for rev 5 templates.

+

In accordance with Binding Operational Directive (BOD) 22-01, CSPs must track their + vulnerabilities against the KEV catalog.

+ + + + + Due Date +

The KEV catalog specified due date by which the vulnerability must be + remediated.

 + +

Added for rev 5 templates.

+

In accordance with Binding Operational Directive (BOD) 22-01, CSPs must track their + vulnerabilities against the KEV catalog.

+ + + + + Test ID +

The test ID for the manual test method.

 + +

Added for rev 5 templates.

+ + + + + Leveraged Authorization +

Indicates a leveraged authorization used for this control.

 + +

This is for legacy SSP conversion to OSCAL. The preferred approach is to specify the + leveraged system as a component and reference it in the control using + by-component.

+ + + + + leveraged-system-identifier +

The identifier corresponding to the FedRAMP package ID.

 + +

Added for rev 5 templates.

+ + + + + Likelihood +

The likelihood of a risk.

 + + + + Tool Name +

The product or tool name for a component or inventory item.

 + +

Added for rev 5 templates.

+ + + + + Nature of Agreement +

Any type of agreement between a CSP and the leveraged CSP vendors who support + products (e.g., End User Licensing Agreement (EULA), Service-Level Agreement (SLA), App + License Agreement, Contract, etc.).

 + +

Added for rev 5 templates.

+ + + + + Authorization Date +

The date of the system's initial FedRAMP authorization.

 + + + + Relevant Baseline +

Identifies the relevant OSCAL baseline.

 + +

As with all URIs in OSCAL, this may contain a URI fragment, which identifies the + local + resource containing the relevant profile.

+ + + + + Short System Name +

The FedRAMP-assigned system identifier.

 + + + + Short System Name +

The FedRAMP-assigned system identifier.

 + + + + Short System Name +

The abbreviated name for the system, such as an acronym.

 + + + + Operational Requirement +

The risk cannot be remediated without impact to the system and must be + accepted.

 + + + + Planned Completion Date +

Provides the date the control expects to be implemented. Must be present when + Implementation Status is "Planned"

 + + + + Plugin Identifier +

A tool assigned Plugin ID.

 + + + + POA&M ID +

A CSP-assigned POA&M identifier.

 + + + + Impacted Control +

A control impacted by this POA&M item.

 + +

Impacted control is required in the POA&M and optional in the SAR.

+

It is allowed in the SAR in anticipation of duplicating open risks from the SAR to + the + POA&M.

+ + + + + Privacy Designation +

Indicates whether this system is privacy sensitive.

 + +

Deprecated.

+ + + + + Privacy Threshold Analysis Q1 +

Does the ISA collect, maintain, or share PII in any identifiable + form?

 + +

Deprecated.

+ + + + + Privacy Threshold Analysis Q2 +

Does the ISA collect, maintain, or share PII from or about the + public?

 + +

Deprecated.

+ + + + + Privacy Threshold Analysis Q3 +

Has a Privacy Impact Assessment (PIA) ever been performed for the + ISA?

 + +

Deprecated.

+ + + + + Privacy Threshold Analysis Q4 +

Is there a Privacy Act System of Records Notice (SORN) for this ISA + system?

 + +

Deprecated.

+ + + + + Purpose +

Explains the system's purpose.

 + + + + Resolution Resource +

The back-matter resource reference used to determine which FedRAMP validation + rule sets apply.

 + +

Added for rev 5 templates.

+ + + + + response-point +

A property whose presence indicates its parent part is a required point of + response for FedRAMP stakeholders.

 + TBD + +

This appears in FedRAMP profiles and resolved profile catalogs.

+

For control statements, it signals to the CSP which statements require a response in + the + SSP.

+

For control objectives, it signals to the assessor which control objectives must + appear + in the assessment results, which aligns with the FedRAMP test case workbook.

+ + + + + Party Identifier +

Identifies the party who authored this revision.

 + + + + Risk Adjustment +

Mitigating factors were identified or implemented, reducing the likelihood or + impact of the risk.

 + + + + Sampling +

Indicates whether a sampling methodology was used instead of assessing the + entire + system.

 + + + + Assessor's Authorization Recommendation +

Indicates the assessor's recommendation for initial or continued + authorization.

 + + + + Risk Priority +

Assessor's recommended risk priority. Lower numbers are higher priority. One + (1) + is highest priority.

 + + + + Scan Percentage +

The scan coverage

 + +

Added for rev 5 templates.

+ + + + + Scan Type +

Identifies the type(s) of scans to be performed on this inventory-item or + component.

 + + + + eAuth Level (OVERALL) +

The overall electronic authentication (eAuth) level applied to the + system.

 + +

Deprecated.

+ + + + + Service Processor +

Name of the interconnection service processor.

 + + + + Service Used By +

Identifies what uses the service.

 + + + + Significant Changes Scope +

The general quantity of significant change(s) in scope.

 + +

Added for rev 5 templates.

+ + + + + SORN ID +

An assigned System of Records Notice (SORN) identifier for this + system.

 + +

Deprecated.

+ + + + + Sort ID +

Identifier for sort ordering content.

 + +

Core OSCAL has a "sort-id" prop, however this "sort-id" extension can be + applied to any assembly that provided information which may need to be rendered in a + specific order. The step assembly is an example of this.

+ + + + + Still Supported +

Specify if the product / component is still supported by the vendor / + manufacturer.

 + +

Added for rev 5 templates.

+ + + + + System Identifier +

The FedRAMP-assigned identifier for this system.

 + + + + Login ID +

The login ID used to assess the web application.

 + +

Extension renamed from "login-id" to "login-id".

+ + + + + Login URL +

The login URL for a web application.

 + +

Extension renamed from "login-url" to "login-url".

+ + + + + Test Type +

Indicates the type of test represented by the task.

 + + + + User Identifier +

Cites the SSP defined user role to use for testing.

 + + + + Short Title +

The short name for the system represented in the resource.

 + + + + Type +

The "type" of back-matter resource.

 + +

Added for rev 5 templates.

+

Locally defined resource types.

+ + + + + User Sensitivity Level +

Defines the sensitivity level of the identified user type.

 + +

Values are as required by FedRAMP for packages based on NIST 800-53, Revision 4.

+

Authoritative source: OPM Position + Designation (Page 18).

+ + + + + External Users +

The current number of users external to the organization.

 + + + + Future External Users +

The anticipated number of users external to the organization in one + year.

 + + + + Internal Users +

The current number of users internal to the organization.

 + + + + Future Internal Users +

The anticipated number of users internal to the organization in one + year.

 + + + + Vendor Dependency +

A vendor resolution is pending, but not yet available.

 + + + + Vendor Name +

The vendor or manufacturer of a component or inventory item.

 + +

Added for rev 5 templates.

+ + + + + Vulnerability Identifier +

A tool assigned vulnerability ID.

 + + + \ No newline at end of file diff --git a/src/metaschema/fedramp_extensions_metaschema.xml b/src/metaschema/fedramp_extensions_metaschema.xml new file mode 100644 index 000000000..a7c737e8a --- /dev/null +++ b/src/metaschema/fedramp_extensions_metaschema.xml @@ -0,0 +1,73 @@ + + + OSCAL Extensions Registry + 0.0.1 + extensions + http://fedramp.gov/ns/oscal + http://fedramp.gov/ns/oscal + +

The OSCAL Extension Model is used to describe the comprehensive set of extenstions.

+

This provides OSCAL practitioners a machine-readable documentation of the extensions used + in an organization's authorization package. Specific requirements, in the form of external + constraints, are referenced in this model.

+ + + + + + + + OSCAL Extensions + Defines the collection of OSCAL extensions. + extensions-registry + + Extensions Registry Universally Unique Identifier + A globally unique identifier used to reference this Extensions Registry. + + + + + + + + + + + + + OSCAL Extension + Defines a OSCAL extension. This can include custom properties, links, + and parts with an organization's namespace. + + Extension Identifier + An unique identifier for the extension. + + + Deprecated + This optional attribute communicates the version after which use of the given 'extension' is discontinued and no longer supported. + + + + Extension Name + Formal name for the extension. + + + Description + Description of the extension. + + + External Constraint ID + The unique identifier of the referenced external constraint. + + + + Remarks + Additional commentary about the containing object. + + + + + + \ No newline at end of file