From cd47418f41cdb0125d0dc042823338036b10d57e Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 22 Oct 2024 21:45:52 -0400 Subject: [PATCH] Create style guide for FedRAMP OSCAL Constraints (#760) * Remove FedRAMP namespace from 'data-center' props (#795) * Hotfix/info (#780) * fix informational constraint handling and make ssp-all valid correct * revert external constraint changes * Update fedramp-external-constraints.xml * Update fedramp_extensions_steps.ts * update info handling * Update fedramp-external-constraints.xml Co-authored-by: Gabeblis * Update fedramp-external-constraints.xml Co-authored-by: Gabeblis * Update fedramp-external-constraints.xml Co-authored-by: Gabeblis * Update fedramp-external-constraints.xml Co-authored-by: Gabeblis * Update src/validations/constraints/fedramp-external-constraints.xml Co-authored-by: Gabeblis * Update src/validations/constraints/fedramp-external-constraints.xml Co-authored-by: Gabeblis * Update dev-constraint.js --------- Co-authored-by: Gabeblis * [skip ci] Create style guide doc for #675 * [skip ci] FSCR-1 re external constraints for #675 * [skip ci] FCSR-1, woops, need formal name for #675 * [skip ci] Tweak FCSR-1 anchor ID in #675 * [skip ci] Stop header hacks for IDs in #675 I read more about these techniques than I would like, but none of them appear to work effectively for making anchors like `#fcsr-1` without adding other content to the anchor which I would like to avoid. https://gist.github.com/asabaylus/3071099?permalink_comment_id=3895584 Either it never worked or something changed. Oh well! * [skip ci] Add FCSR-2 on context sorting for #675 * [skip ci] Add FCSR-3 about alpha sorting for #675 * [skip ci] Add FCSR-4 to require help-url for #675 * [skip ci] Adjust title from style guide to dev style guide per Rene's review * [skip ci] Adjust grammar and style per Rene's review Co-authored-by: Rene Tshiteya * [skip ci] @Rene2mt's feedback: add ID req for #675 * [skip ci] @Rene2mt's feedback: level req for #675 * [skip ci] @Rene2mt's review: why CRITICAL for #675 * [skip ci] Woops, missed IDs for reqs for #675 * [skip ci] Feedback: add message req for #675 * [skip ci] Fix constraint path in examples for #675 * [skip ci] Add remarks rec guidance for #675 * [skip ci] Add @wandmagic's rec for FCSR-1 for #675 * [skip ci] Add FCSR-10 re active voice for #675 * [skip ci] Remove FCSR-10's incorrect only for #675 * [skip ci] Add FCSR-11 about BCP14 words for #675 * [skip ci] Add no-jargon req FCSR-12 for #675 * [skip ci] Item, not sequence style req for #675 * [skip ci] Add req for sequence ctx hints for #675 * [skip ci] Add FCSR-15 re formal-names for #675 * [skip ci] Remove anchor hack from FCSR-1 for #675 * [skip ci] Wrap up kebab case IDs, reorder for #675 * [skip ci] Fixes from @Rene2mt'2 review for #675 * [skip ci] Add labels for rules in #675 * [skip ci] Simplify rule titles for #675 Follow feedback from @brian-ruf in his review. * [skip ci] Finalize table index with reqs for #645 * [skip ci] Limit informational constraints for #675 * [skip ci] Feedback: FRR1 about OSCAL constraints, not Metaschema constraints Co-authored-by: David Waltermire * [skip ci] Update FRR1 in table listing too Co-authored-by: David Waltermire * [skip ci] Add space in status row of table for FRR2 Co-authored-by: David Waltermire * [skip ci] Add missing word to FRR3 title Co-authored-by: David Waltermire * [skip ci] Improve the prose in FRR2 guidance Co-authored-by: David Waltermire * [skip ci] Reorder statements in sentence of FRR2 guidance Co-authored-by: David Waltermire * [skip ci] Clarify ambiguous wording in FRR5 Co-authored-by: David Waltermire * [skip ci] Correct typos in FRR6 formal name Co-authored-by: David Waltermire * [skip ci] Make FRR7 formal name more explicit Co-authored-by: David Waltermire * [skip ci] Improve FRR8 formal name Co-authored-by: David Waltermire * [skip ci] Fix FRR8 formal name in table index Co-authored-by: David Waltermire * [skip ci] Fix FRR9 formal name in table index Co-authored-by: David Waltermire * [skip ci] Fix FRR9 formal name in table index Co-authored-by: David Waltermire * [skip ci] Adjust FRR9 guidance to specify expect constraints Co-authored-by: David Waltermire * [skip ci] Adjust FRR9 constraint examples for correct type Co-authored-by: David Waltermire * [skip ci] Adjust FRR10 formal name to be more clear Co-authored-by: David Waltermire * [skip ci] Fix FRR10 formal name in table index Co-authored-by: David Waltermire * [skip ci] Make FRR11 formal name better sentence fragment Co-authored-by: David Waltermire * [skip ci] Fix FRR11 above requirement text Co-authored-by: David Waltermire * [skip ci] Adjust FedRAMP reqs prefix FCSR->FRR Given related work in the program, I want to generalize the prefix to be more general and global for all form of FedRAMP requirements down the road. * [skip ci] Add missing examples to FRR17 for #675 * [skip ci] Align formal names, spacing for #675 I had to fix up some of the formal names where Dave covered some of them in many places, but not all. Also other suggestions add some space. * [skip ci] Add level to many examples, finish #675 * [skip ci] Fold longer bg info for reqs in #675 * [skip ci] Clarify FRR1 bad example is bad in #645 * [skip ci] Clarify context order examples for #675 * [skip ci] Clarify case sorting for FRR3 in #675 * [skip ci] Clean up explanation of FRR10 for #675 * [skip ci] Fix typos in FRR13 and FRR15 for #675 * [skip ci] FRR2 feedback from Kylie for #675 * [skip ci] Reword FRR9 with Kylie's feedback in #675 * [skip ci] Woops, FRR16 twice, no FRR17 for #675 * [skip ci] Last call and let reqs in FRR18 for #675 * [skip ci] Correct ID for FRR18 to anchor in table Co-authored-by: Gabeblis * [skip ci] Offset req ID sequence Per discussion with others on a call with leads and staff from both FR branches, begin with an offset sequences and reserve the first 100 for other uses for the time being. /cc @kscarf1 * [skip ci] BCP14 keywords in #675 summary text * [skip ci] Tighten up summary text more for #675 * [skip ci] Add back to top anchors for #675 * [skip ci] Better grammar and flow for #675 summary * [skip ci] Improve FRR102 guidance text for #675 * [skip ci] Capitalize and fix FRR110 title for #675 * [skip ci] Fix poor grammar in FRR117 text for #675 * [skip ci] Explicit docs URL in FRR104 for #675 Address missing feedback to @kyhu65867 from review that had not been previously addressed by yours truly. * [skip ci] Fix FRR105 with feedback for #675 Address some feedback about wording and style of the unique ID req. * [skip ci] Fix FRR103 spacing for #675 Completely address feedback from @david-waltermire after checking for final review of style guide left in the comment below. https://github.com/GSA/fedramp-automation/pull/760#discussion_r1803898145 * [skip ci] Fix FRR108 conformant example for #675 --------- Co-authored-by: Rene Tshiteya Co-authored-by: wandmagic <156969148+wandmagic@users.noreply.github.com> Co-authored-by: Gabeblis Co-authored-by: David Waltermire --- src/validations/constraints/STYLE.md | 1218 +++++++++++++++++ .../ssp-data-center-country-code-INVALID.xml | 2 +- .../fedramp-external-allowed-values.xml | 6 +- 3 files changed, 1221 insertions(+), 5 deletions(-) create mode 100644 src/validations/constraints/STYLE.md diff --git a/src/validations/constraints/STYLE.md b/src/validations/constraints/STYLE.md new file mode 100644 index 000000000..44921b10a --- /dev/null +++ b/src/validations/constraints/STYLE.md @@ -0,0 +1,1218 @@ +# Developer Style Guide for FedRAMP OSCAL Constraints + +## Summary + +This document is to instruct FedRAMP developers and community members on mandatory or recommended style for the structure, format, and organization of constraints. Each requirement MUST have an identifier, guidance text, and examples that either do or do not conform to the best practices. The FedRAMP Automation Team maintains this guidance in this format to improve external constraints for code readability, consistency, and quality with minimal effort and less manual review. + +## Requirements + +| ID | Formal Name | Required or Recommended | Category | +|-----------------|-------------------------|-------------------------|-------------| +| [FRR101](#frr101) | Separate OSCAL External Constraints | Required | ID | +| [FRR102](#frr102) | Constraints Sorted from Broadest to Narrowest Metapath Target | Required | Metapath; Sorting | +| [FRR103](#frr103) | Constraints in the Context Sorted Alphabetically by ID | Required | ID; Sorting | +| [FRR104](#frr104) | Constraints Have a Help URL Property | Required | Structure; Metadata | +| [FRR105](#frr105) | Constraints Have a Unique ID | Required | ID; Metadata | +| [FRR106](#frr106) | Constraints Have IDs with Lower Case Letters, Numbers, and Dashes | Required | ID | +| [FRR107](#frr107) | Constraints Have an Explicit Severity Level | Required | Structure; Metadata | +| [FRR108](#frr108) | Constraints with Critical Severity Level Used only for Runtime Failures | Required | Structure; Metadata | +| [FRR109](#frr109) | Expect Constraint Message Field Required | Required | Structure; Metadata | +| [FR110](#frr110) | Constraint Has a Remark When Overly Complex | Recommended | Structure; Metadata | +| [FRR111](#frr111) | Constraint Message is Sentence in Active Voice | Recommended | Style | +| [FRR112](#frr112) | IETF BCP14 Keywords in Constraint Messages | Required | Style | +| [FRR113](#frr113) | Constraints Use Messages without Metaschema and OSCAL Jargon | Required | Style | +| [FRR114](#frr114) | Constraints Tests and Messages Have Single Item Focus | Recommended | Sequences; Style | +| [FRR115](#frr115) | Constraint Messages Have Single Item Hints | Recommended | Sequences; Style | +| [FRR116](#frr116) | Constraints Formal Names Required | Required | Structure; Metadata | +| [FRR117](#frr117) | Limit Informational Constraint Usage | Recommended| Structure; Metadata | +| [FRR118](#frr118) | Keep Let Bindings Adjacent to Their Constraints | Recommended| Structure; Sorting | + +### FRR101 + +ID: `frr101` + +Formal Name: Separate OSCAL External Constraints + +State: Required + +Categories: ID + +Guidance: FedRAMP OSCAL constraints MUST be in an external file or URL. OSCAL model in-line constraints should be avoided and only implemented by NIST for generalized, non-FedRAMP specific constraints. + +
+Click for important background: + +**NOTE:** At this time, the FedRAMP Automation Team maintains a set of constraints for the core NIST-maintained OSCAL models, not specific to FedRAMP, in the the [`oscal-external-constraints.xml`](./oscal-external-constraints.xml) file. The team intends intends to upstream these changes to the NIST-maintained models and their supporting code base, as proposed in [usnistgov/OSCAL#2050)](https://github.com/usnistgov/OSCAL/issues/2050). Currently, FedRAMP developers implement externalized constraints in this separate file, as this guidance requires and is the only feasible interim solution. However, the test infrastructure purposely ignores this file and does not process its constraints for explicit continuous integration testing. This approach MAY change given the result of the proposal to NIST maintainers or other decisions by FedRAMP's technical leadership, but they are not explicitly within the scope of FedRAMP developer's constraint roadmap and they follow this guidance _only_ when reasonable. FedRAMP developers did not design or implement these constraints as a permanent collection in the constraints inventory. +
+
+ +[back to top](#summary) + +#### FRR101 Conformant Example + +Below is a conformant example for FRR1. + +```xml + + + + + + + + + Every supporting artifact found in a citation should have a title. + + + + +``` + +```xml + + + + OSCAL Document Metadata Description + 1.1.2 + oscal-metadata + http://csrc.nist.gov/ns/oscal/1.0 + http://csrc.nist.gov/ns/oscal + + + Back matter + A collection of resources that may be referenced from within the OSCAL document instance. + + + Resource + + + + Resource Title + An optional name given to the resource, which may be used by a tool for display and navigation. + + +``` + +[back to top](#summary) + +#### FRR101 Non-conformant Example + +Below is a non-conformant example for FRR1. + +```xml + + + OSCAL System Security Plan (SSP) Model + 1.1.2 + oscal-ssp + http://csrc.nist.gov/ns/oscal/1.0 + http://csrc.nist.gov/ns/oscal + + + + + System Security Plan (SSP) + A system security plan, such as those described in NIST SP 800-18. + system-security-plan + + System Security Plan Universally Unique Identifier + + + + + + + + + + +``` + +[back to top](#summary) + +### FRR102 + +ID: `frr102` + +Formal Name: Constraints Sorted from Broadest to Narrowest Metapath Target + +State: Required + +Categories: Metapath; Sorting + +Guidance: Developers MUST sort OSCAL constraint definitions in the file from broadest to narrowest `metapath/@target`. In a `context`, the broadest `metapath/@target` is one where the target path is as close as possible to the root of the respective model (`target="/system-security-plan"`) or models (`target="//*/metadata"`) of a given OSCAL document. Targets that address specific nested fields, flags, or assemblies are more narrowly focused. + +This approach provides a predictable ordering for readers and maintainers of the constraint set. It is intended to allow a reader to quickly find the constraints for a given context and to know where to place new constraints based on the constraint's context. + +[back to top](#summary) + +#### FRR102 Conformant Example + +Below is a conformant example. + +```xml + + + + + + Duplicate response point at '{ path(.) }'. + + + + + + + + Each data center address must contain a country code. + + + Each data center must have an address that is within the United States. + + + + +``` + +[back to top](#summary) + +#### FRR102 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + Each data center address must contain a country code. + + + Each data center must have an address that is within the United States. + + + + + + + + + Duplicate response point at '{ path(.) }'. + + +

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.

+ + + + +``` + +[back to top](#summary) + +### FRR103 + +ID: `frr103` + +Formal Name: Constraints in the Context Sorted Alphabetically by ID + +State: Required + +Categories: ID; Sorting + +Guidance: Within a given constraint file, developers MUST sort constraint definitions within a given context so that each constraint is ordered alphabetically by the constraint's `@id`, where upper case letters are sorted before lower case letters. + +[back to top](#summary) + +#### FRR103 Conformant Example + +Below is a conformant example: + +```xml + + + + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + + +``` + +[back to top](#summary) + +#### FRR103 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + + +``` + +[back to top](#summary) + +### FRR104 + +ID: `frr104` + +Formal Name: Constraints Have a Help URL Property + +State: Required + +Categories: Structure; Metadata + +Guidance: Developers MUST define only one Metaschema constraint property with a namespace of `https://docs.oasis-open.org/sarif/sarif/v2.1.0`, name `help-url`, and `value` with a URL to an official, meaningful, and specific explanation to the OSCAL syntax and semantics (from [automate.fedramp.gov/documentation](https://automate.fedramp.gov/documentation/)) that motivate that OSCAL constraint definition in a file. + +
+ +Click for important background: + +**NOTE:** Although Metaschema can support multiple properties for different URLs, the explicit goal of this FedRAMP design and approach is to emit the relevant URL in SARIF output for constraint violations. The SARIF 2.1.0 specification and schema support one and only one URL in the relevant SARIF structure. +
+
+ +[back to top](#summary) + +#### FRR104 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + Each data center address must contain a country code. + + + + +``` + +[back to top](#summary) + +#### FRR104 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + Each data center address must contain a country code. + + + + +``` + +[back to top](#summary) + +### FRR105 + +ID: `frr105` + +Formal Name: Constraints Have a Unique ID + +State: Required + +Categories: ID; Metadata + +Guidance: Developers MUST define a Metaschema constraint with an `id` flag, and the value of that `id` flag must be unique from all other constraint IDs across all constraint documents FedRAMP and NIST define in core OSCAL. + +[back to top](#summary) + +#### FRR105 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + Duplicate response point at '{ path(.) }'. + + + + +``` + +[back to top](#summary) + +#### FRR105 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + + Duplicate response point at '{ path(.) }'. + + + + +``` + +[back to top](#summary) + +### FRR106 + +ID: `frr106` + +Formal Name: Constraints Have IDs with Lower Case Letters, Numbers, and Dashes + +State: Required + +Categories: ID + +Guidance: Developers MUST define a Metaschema constraint with an `id` flag with the following structure. + +1. all lowercase letters (`a-z`) and numbers (`0-9`) +1. dashes (`-`) separating words and phrases of letters and numbers above + +[back to top](#summary) + +#### FRR106 Conformant Example + +Below is a conformant example. + +```xml + + + + + + Data Center Locations in the United States + A FedRAMP SSP must define locations for data centers that are explicitly in the United States. + + + + +``` + +[back to top](#summary) + +#### FRR106 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + Data Center Locations in the United States + A FedRAMP SSP must define locations for data centers that are explicitly in the United States. + + + + +``` + +[back to top](#summary) + +### FRR107 + +ID: `frr107` + +Formal Name: Constraints Have an Explicit Severity Level + +State: Required + +Categories: Structure; Metadata + +Guidance: Developers MUST define a Metaschema constraint with a `level` flag with [a valid value](https://pages.nist.gov/metaschema/specification/syntax/constraints/#level) to indicate to downstream developers and/or users the potential impact of the data instance not meeting its requirements. + +[back to top](#summary) + +#### FRR107 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + Duplicate response point at '{ path(.) }'. + + + + +``` + +[back to top](#summary) + +#### FRR107 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + + Duplicate response point at '{ path(.) }'. + + + + +``` + +[back to top](#summary) + +### FRR108 + +ID: `frr108` + +Formal Name: Constraints with Critical Severity Level Used only for Runtime Failures + +State: Required + +Categories: Structure; Metadata + +Guidance: Developers MUST only define a Metaschema constraint with a `level` flag with a value of `CRITICAL` if and only if the violation of the constraint will lead to an irrecoverable runtime failure (e.g. a SSP's `import-profile` references a catalog or profile with no valid controls) or undefined behavior in a conformant processor in a consistent way for the majority of use cases. + +[back to top](#summary) + +#### FRR108 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + A FedRAMP SSP MUST define a valid URL to the catalog that identifies the controls' requirements it implements. This error indicates the referenced catalog or profile is invalid, so many constraints are unable to process. The resulting validations from constraint check are inaccurate, incomplete, or both. + + + + +``` + +[back to top](#summary) + +#### FRR108 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + + Duplicate response point at '{ path(.) }'. + + + + +``` + +[back to top](#summary) + +### FRR109 + +ID: `frr109` + +Formal Name: Expect Constraint Message Field Required + +State: Required + +Categories: Structure; Metadata + +Guidance: A developer MUST define a `message` field with a description of the positive requirement (i.e. what an OSCAL document must define and encode for FedRAMP's use case; why it matters; and other relevant details technical leads and developer team, if applicable) only in an `expect` Metaschema constraint. + +[back to top](#summary) + +#### FRR109 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + A FedRAMP SSP MUST define a valid URL to the catalog that identifies the controls' requirements it implements. This error indicates the referenced catalog or profile is invalid, so many constraints are unable to process. The resulting validations from constraint check are inaccurate, incomplete, or both. + + + + +``` + +[back to top](#summary) + +#### FRR109 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + + + + + +``` + +[back to top](#summary) + +### FR110 + +ID: `frr110` + +Formal Name: Constraint Has a Remark When Overly Complex + +State: Recommended + +Categories: Structure; Metadata + +Guidance: Developers SHOULD only define a Metaschema constraint with a `remarks` field when an explanation of the positive requirement is too long to fix in the `message` field. It is too long for the `message` when it is more than sentence or the sentence(s) are so complex they do not meet other style guide requirements for a `message`. + +[back to top](#summary) + +#### FR110 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + A FedRAMP SSP MUST define a valid URL to the catalog that identifies the controls' requirements it implements. + +

The control requirements a SSP must implement and support are defined in the profile or catalog referenced in b a URL to a file on a computer's filesystem or remote URL.

+

More than other constraints, a valid profile URL is integral for processing of other constraints in this document.

+

Users and intervening software developers should clearly mark that validation failed if this constraint is violated regardless of all others.

+ + + + + +``` + +[back to top](#summary) + +#### FR110 Non-conformant Example + +```xml + + + + + + + + A FedRAMP SSP MUST define a valid URL to the catalog that identifies the controls' requirements it implements. The control requirements a SSP must implement and support are defined in the profile or catalog referenced in b a URL to a file on a computer's filesystem or remote URL. More than other constraints, a valid profile URL is integral for processing of other constraints in this document. Users and intervening software developers should clearly mark that validation failed if this constraint is violated regardless of all others. + + + + +``` + +[back to top](#summary) + +### FRR111 + +ID: `frr111` + +Formal Name: Constraint Message is Sentence in Active Voice + +State: Recommended + +Categories: Style + +Guidance: Developers SHOULD define a Metaschema constraint with a `message` field with one sentence with active voice, not passive voice. The subject SHOULD be the document name or abbreviation for the OSCAL model in question. For general constraints (e.g. `metadata`; `back-matter/resources`), the sentence should begin with the subject as "A FedRAMP document requires." + +[back to top](#summary) + +#### FRR111 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + + A FedRAMP document MUST define a data center location with an explicit country code. + + + + +``` + +[back to top](#summary) + +#### FRR111 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + + An explicit country code must be defined here. + + + + +``` + +[back to top](#summary) + +### FRR112 + +ID: `frr112` + +Formal Name: IETF BCP14 Keywords in Constraint Messages + +State: Required + +Categories: Style + +Guidance: Developers MUST define a Metaschema constraint with a `message` sentence that conforms with IETF standards regarding capitalized requirement keywords per [BCP14](https://datatracker.ietf.org/doc/bcp14/). The sentence will use MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT,", "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" according to BCP14 requirements. + +[back to top](#summary) + +#### FRR112 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + A FedRAMP document MUST define a data center location with an explicit country code. + + + + +``` + +[back to top](#summary) + +#### FRR112 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + What's wrong with you, no country code for data center!? + + + + +``` + +[back to top](#summary) + +### FRR113 + +ID: `frr113` + +Formal Name: Constraints Use Messages without Metaschema and OSCAL Jargon + +State: Required + +Categories: Style + +Guidance: Developers MUST define a Metaschema constraint with a `message` field with one sentence that describes the positive requirements for the artifact of the security process without using jargon or terminology from the [Metaschema](https://pages.nist.gov/metaschema) and [OSCAL](https://pages.nist.gov/OSCAL) projects. Messages MUST NOT use this jargon. + +[back to top](#summary) + +#### FRR113 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + A FedRAMP document MUST define a data center location with an explicit country code. + + + + +``` + +[back to top](#summary) + +#### FRR113 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + + The value of this field in the address assembly within the abstract metadata module, with a cardinality of 0 to 1, must result with a value of 1 when evaluated by the Metapath function count. + + + + +``` + +[back to top](#summary) + +### FRR114 + +ID: `frr114` + +Formal Name: Constraints Tests and Messages Have Single Item Focus + +Categories: Sequences; Style + +State: Recommended + +Guidance: Developers SHOULD define a Metaschema constraint with `target`, `test`, and `message` fields that test and explain a positive requirement in the singular for an individual item of a sequence (i.e. occurrences of a flag, field, or assembly have a `max-occurs` greater than 1) that conforms to an OSCAL model. Violation paths and messages should discuss an individual item in the singular. The only exception is for quantitative or qualitative analysis of the whole sequence. The development team and community contributors can make a determination, meaning if the constraint is within that exceptional category, on a case-by-case basis, as this is a recommendation and not a requirement. + +[back to top](#summary) + +#### FRR114 Conformant Example + +Below is a conformant example. + +```xml + + + + + + A FedRAMP SSP must define a location for a data center with an explicit country code. + + + + +``` + +[back to top](#summary) + +#### FRR114 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + A FedRAMP SSP needs data centers to indicate a country code. + + + + +``` + +[back to top](#summary) + +### FRR115 + +ID: `frr115` + +Formal Name: Constraint Messages Have Single Item Hints + +Categories: Sequences; Style + +State: Recommended + +Guidance: Developers SHOULD define a Metaschema constraint with a `message` field that provides contextual hints when it is for an individual item of a sequence (i.e. occurrences of a flag, field, or assembly have a `max-occurs` greater than 1) that conforms to an OSCAL model. If there is an identifier, name, or brief label (of five words or less) as applicable. Messages SHOULD NOT provide hints with machine-oriented data (i.e. fields or flags of [type UUID](https://pages.nist.gov/metaschema/specification/datatypes/#uuid)). Instead, message hints should dereference machine-oriented data to provide human-oriented clues as recommended above. + +[back to top](#summary) + +#### FRR115 Conformant Example + +Below is a conformant example. + +```xml + + + + + + A FedRAMP SSP must define a location for a data center with the country code US for the United States, not {if empty(.) then 'not an empty value' else string(.)}. + + + + +``` + +[back to top](#summary) + +#### FRR115 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + Bad country code, pick the right one next time, fool! + + + + +``` + +[back to top](#summary) + +### FRR116 + +ID: `frr116` + +Formal Name: Constraints Formal Names Required + +State: Required + +Categories: Structure; Metadata + +Guidance: Developers MUST define a Metaschema constraint with a `formal-name` field that provides a name for the constraint to use in documentation and tool output. + +[back to top](#summary) + +#### FRR116 Conformant Example + +Below is a conformant example. + +```xml + + + + + + Data Center Locations in the United States + A FedRAMP SSP must define locations for data centers that are explicitly in the United States. + + + + +``` + +[back to top](#summary) + +#### FRR116 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + Bad country code, pick the right one next time, fool! + + + + +``` + +[back to top](#summary) + +### FRR117 + +ID: `frr117` + +Formal Name: Limit Informational Constraint Usage + +State: Recommended + +Categories: Structure; Metadata + +Guidance: Developers SHOULD only define Metaschema constraints with a severity `level="INFORMATIONAL"` (a.k.a. informational constraints) if and only if the FedRAMP developers clearly document a specific use case where a FedRAMP package reviewer SHOULD review the analysis reported in its `message` field. The constraint SHOULD report an analytical result of processing one or more OSCAL data elements and emitting novel information for that use case. The constraint's `message`, `target`, `test` fields SHOULD NOT only be the inverse of the opposite condition of a `CRITICAL`, `ERROR`, or `WARNING` constraint. + +Developers MAY use informational constraints for development and ad-hoc debugging, but such a constraint MUST NOT be merged into a branch for release to downstream stakeholders without project technical leads' approval during code review. That review SHOULD include a review of a documented use case for how FedRAMP package review or alternative stakeholder will act upon this information. + +[back to top](#summary) + +#### FRR117 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + + This FedRAMP SSP has {$data-centers-us-count} {if $data-centers-us-count = 1 then 'data center' else 'data centers' }. This notional example assumes is important for a reviewer to know for XYZ reason. + + + + +``` + +[back to top](#summary) + +#### FRR117 Non-conformant Example + +Below is a non-conformant example. + +```xml + + + + + + + This informational constraint is in the report because it is in the United States. + + + + +``` + +[back to top](#summary) + +### FRR118 + +ID: `frr118` + +Formal Name: Sort Let Bindings in Logical Order Before Constraints + +State: Recommended + +Categories: Sorting; Structure + +Guidance: Developers MUST define `let` bindings before any given constraint in a `context`. Developers SHOULD define the `let` binding(s) adjacent to its dependencies in a logical order. A logical order is when developers sort the bindings in order of their dependency, where an `expression` of a later binding evaluates a `var` reference to a previous expression's value. If there are multiple `let` bindings with no dependency relationship between them, developers MAY sort the `let` bindings alphabetically by `var` value (where upper case letters are sorted before lower case letters). + +[back to top](#summary) + +#### FRR118 Conformant Example + +Below is a conformant example. + +```xml + + + + + + + + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + + +``` + +[back to top](#summary) + +#### FRR118 Non-conformant Example + +Below are non-conformant examples. + +```xml + + + + + + + + + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + + +``` + +```xml + + + + + + + + + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + Example of sorting. + + + + +``` + +[back to top](#summary) diff --git a/src/validations/constraints/content/ssp-data-center-country-code-INVALID.xml b/src/validations/constraints/content/ssp-data-center-country-code-INVALID.xml index 217db047c..717365051 100644 --- a/src/validations/constraints/content/ssp-data-center-country-code-INVALID.xml +++ b/src/validations/constraints/content/ssp-data-center-country-code-INVALID.xml @@ -7,7 +7,7 @@
- +
diff --git a/src/validations/constraints/fedramp-external-allowed-values.xml b/src/validations/constraints/fedramp-external-allowed-values.xml index b79d8aa7d..a05d4c1db 100644 --- a/src/validations/constraints/fedramp-external-allowed-values.xml +++ b/src/validations/constraints/fedramp-external-allowed-values.xml @@ -404,11 +404,9 @@ - - - + - + Security Impact Level The security objective level as defined by NIST SP 800-60. Low