Expressing FedRAMP Template Metadata in OSCAL
While each FedRAMP template has a unique purpose, they share common information elements, such as title and publication date. These common elements are expressed using the same OSCAL syntax for the SSP, SAP, SAR, and POA&M. This section provides OSCAL syntax for these common elements, including:
- Document Basics:
- Document Title
- Document Publication Date
- Document Version
- Document Sensitivity & Ownership Markings
- Prepared By
- Prepared For
- Document Revision History
- OSCAL-Additional Document Basics:
- Last Modified Date
- OSCAL Syntax Version
- FedRAMP Version
- Logos:
- FedRAMP Logo
- CSP Logo
- Assessor Logo
- Consulting 3PAO Logo
- Attachments:
- FedRAMP Acronyms
- FedRAMP Citations (Laws, Regulations, Standards, and Guidance)
Title Page
The FedRAMP Logo is a resource in the back-matter section of the OSCAL-based FedRAMP Templates, and can be referenced with the following XPath:
/*/metadata/party[@uuid=../responsible-party[@role-id='fedramp-pmo']/party-uuid]/link[@rel='logo']/@href
As with any href value, this can include a relative or absolute URI external to the OSCAL file, or it can contain a URI fragment, pointing to a resource inside the OSCAL file itself (or other OSCAL files in the stack).
If the above returns an href value beginning with a hashtag (#), the rest of the value is the UUID value for the resource containing the logo. Drop the hashtag and use the remaining value to locate the resource as follows:
/*/back-matter/resource[@uuid='[UUID-value-returned-above]']/rlink/@href
OR
/*/back-matter/resource[@uuid='[UUID-value-returned-above]']/base64
Representation
|
|
FedRAMP Allowed Value
Required Role ID:
fedramp-pmo
XPath Queries
- Document Title:
/*/metadata/title
- Document Published Version #:
/*/metadata/version
- Document Published Date (will need to convert data for presentation):
/*/metadata/published
- FedRAMP’s Logo:
/*/metadata/party[@uuid=../responsible-party[@role-id='fedramp-pmo']/party-uuid]/link[@rel='logo']/@href
- Document Sensitivity Label (If more than one, tools should present all):
/*/metadata/prop[@name="marking"]
NOTES:
-
There may be more than one Document Sensitivity Label (
marking
), if needed. The only required value iscui
(Controlled Unclassified Information). Tools should display and/or notify the user of all sensitivity markings. -
The logos on older FedRAMP Templates are not necessary. This includes the NIST Logo, as well as the three Joint Authorization Board (JAB) Agency Logos.
Prepared By (Third Party)
The FedRAMP SAP and SAR must always indicate the assessing organization using this Prepared By syntax.
Representation
|
|
OSCAL Allowed Value
Required Role ID:
prepared-by
XPath Queries
- Preparer Organization’s Name and Address:
/*/metadata/party[@id=[/*/metadata/responsible-party[@role-id='prepared-by']/party-id]]/org/org-name
NOTE: Replace “org-name” with “address/addr-line”, “address/city”, “address/state”, or “address/zip” as needed. There may be more than one addr-line.
NOTES:
-
The
responsible-party
assembly connects the role to the party and is required for compliance. -
If the content was prepared by an organization other than the CSP, their logo should also appear in back-matter.
Prepared By (CSP Self-Prepared)
This is applicable where the CSP creates or updates its own SSP or POA&M content. The FedRAMP SAP and SAR must never be CSP self-prepared.
Representation
|
|
OSCAL Allowed Value
Required Role ID:
prepared-by
XPath Queries
- Preparer Organization’s Name and Address:
/*/metadata/party[@id=[/*/metadata/responsible-party[@role-id='prepared-by']/party-id]]/org/org-name
NOTE: Replace “org-name” with “address/addr-line”, “address/city”, “address/state”, or “address/zip” as needed. There may be more than one addr-line.
NOTES:
- The
responsible-party
assembly connects the role to the party and is required for compliance.
Prepared For (CSP)
For FedRAMP SSP, SAP, SAR, and POA&M, the Prepared For
is typically
the CSP; however, it may be different if an unforeseen circumstance
requires another party to be named. For this reason, Prepared For
and CSP have separately defined roles.
Representation
|
|
XPath Queries
- Prepared For (CSP) Details:
/*/metadata/party[@id=[/*/metadata/responsible-party[@role-id='prepared-for']/party-id]]/org/org-name
- Prepared For Details:
/*/metadata/party[@id=[/*/metadata/responsible-party[@role-id='prepared-for']/party-id]]/org/org-name
NOTE: Replace “org-name” with “address/addr-line”, “address/city”, “address/state”, or “address/zip” as needed. There may be more than one addr-line.
Document Revision History
remarks
field is Markup multiline, which enables the text to be formatted. This requires special handling. See the section on markup-line and markup-multiline Fields in OSCAL, or visit: https://pages.nist.gov/metaschema/specification/datatypes/#markup-multilineThe OSCAL revision history requires one FedRAMP extension to fully meet FedRAMP’s revision history requirements.
Representation
|
|
FedRAMP Extension (Author)
prop (ns="http://fedramp.gov/ns/oscal"
):
name="party-uuid"
XPath Queries
- Number of Revision Entries:
count(/*/metadata/revision-history/revision)
- Revision Date for Individual Entry:
/*/metadata/revision-history/revision[1]/published
- Description for Individual Entry:
/*/metadata/revision-history/revision[1]/remarks/string()
- Version for Individual Entry:
/*/metadata/revision-history/revision[1]/version
- Author for Individual Entry:
/*/metadata/party[@uuid=/*/metadata/revision-history/revision[1]/prop [@name='party-uuid'][@ns='http://fedramp.gov/ns/oscal']]/org/short-name
NOTES:
- The Revision History’s Author field is addressed using a FedRAMP
extension, which points to a metadata
party
. - The published field requires the OSCAL data type, date-time-with-timezone.
- FedRAMP only requires the publication date, not the time.
- The time portion may be replaced with all zeros.
- FedRAMP tools should present only the date, and use a more user-friendly format.
FedRAMP Version
All documents in a digital authorization package for FedRAMP must specify the version that identifies which FedRAMP policies, guidance, and technical specifications its authors used during the creation and maintenance of the package.
FedRAMP maintains an official list of the versions on the fedramp-automation releases page. Unless noted otherwise, a valid version is a published tag name.
Representation
|
|
XPath Query
/*/metadata/prop[@name='fedramp-version'][@ns='http://fedramp.gov/ns/oscal']/@value
How to Contact Us
The FedRAMP email and web site addresses are part of the organizational content for the FedRAMP PMO party. This information already exists in OSCAL-based FedRAMP Templates.
There must be a role
defined in the file with the ID value set to
fedramp-pmo
. There must be a party
defined with FedRAMP’s details,
and there must be a responsible-party
defined, linking the
fedramp-pmo
role-id
to the FedRAMP party
uuid.
Representation
|
|
FedRAMP-Role Identifiers:
fedramp-pmo
XPath Queries
- FedRAMP Email Address:
/*/metadata/party[@uuid=/*/metadata/responsible-party[@role-id='fedramp-pmo'] /party-uuid]/email
- FedRAMP Web Site Address:
/*/metadata/party[@uuid=/*/metadata/responsible-party[@role-id='fedramp-pmo'] /party-uuid]/link/@href
Document Approvals
The OSCAL syntax is the same for document approvers in the SSP, SAP, and SAR. For the SSP, approvers are typically executives within the CSP. For the SAP and SAR, approvers are typically executives within the assessor’s organization.
Representation
|
|
Defined Identifiers
Required Role IDs:
content-approver
cloud-service-provider
FedRAMP Extension (Person’s Title)
prop (ns="http://fedramp.gov/ns/oscal"
):
name="title"
XPath Queries
-
Approver’s Name:
(/*/metadata/party[@uuid=[/*/metadata/responsible-party[@role-id='content-approver']/party-uuid]]/party-name)[1]
-
Approver’s Title:
(/*/metadata/party[@uuid=[/*/metadata/responsible-party[@role-id='content-approver'] /party-uuid]]/prop[@name='title'][@ns='http://fedramp.gov/ns/oscal'])[1]
NOTE: For each additional approver, replace the “[1]” with “[2]”, “[3]”, and so on.
-
CSP Name:
/*/metadata/party[@uuid=[/*/metadata/responsible-party[@role-id='cloud-service-provider']/party-uuid]]/party-name
NOTES:
The code above is an SSP example. For SAP and SAR, a similar approach is
used for the assessor, using the "assessor"
role ID instead of the
"cloud-service-provider"
role ID.
FedRAMP Standard Attachments (Acronyms, Laws/Regulations)
The FedRAMP MS Word-based SSP, SAP and SAR templates included links to the FedRAMP Laws and Regulations file, as well as the FedRAMP Acronyms file posted on https://fedramp.gov.
These are already included in the OSCAL-based FedRAMP templates as
resources. The resource
linking to the FedRAMP citations file is
identified with links from the property type, fedramp-citations
. The
resource
linking to the FedRAMP acronyms file is identified with the
property type, fedramp-acronyms
.
Representation
|
|
XPath Queries
|
|
Additional Laws, Regulations, Standards or Guidance
Additional citations must be represented as
additional resource
assemblies with one resource
assembly per citation. This
applies to applicable laws, regulations, standards, or guidance beyond
FedRAMP’s predefined set.
Each must have a type defined. The value of the type filed must be set
to law
, regulation
, standard
, or guidance
as
appropriate. There may be more than one type defined. FedRAMP tools use
the type
property to differentiate these resource assemblies from
others.
Representation
|
|
XPath Queries
- Number of Laws and Regulations (integer):
count(/*/back-matter/resource/prop[@name="type"][(string(.) = "law") or (string(.)="regulation")])
- Laws and Regulations: Identification Number:
(/*/back-matter/resource/prop[@name="type"][(string(.) = "law") or (string(.)="regulation")])[1]/../doc-id
- Laws and Regulations: Title:
(/*/back-matter/resource/prop[@name="type"][(string(.) = "law") or (string(.)="regulation")])[1]/../title
- Laws and Regulations: Date:
(/*/back-matter/resource/prop[@name="type"][(string(.) = "law") or (string(.)="regulation")])[1]/../prop[@name="publication"]
- Laws and Regulations: Link:
(/*/back-matter/resource/prop[@name="type"][(string(.) = "law") or (string(.)="regulation")])[1]/../rlink/@href
NOTE: For Standards and Guidance replace “law” with “standard” and “regulation” with “guidance” in the above queries to generate the Standards and Guidance tables.
Attachments and Embedded Content
There are several attachments in a classic FedRAMP MS Word based SSP, SAP, SAR document or Deviation Request (DR) form. Some lend well to machine-readable format, while others do not. Those that are readily modeled in machine-readable format are typically addressed within the OSCAL syntax, while attachments such as policies, procedures, plans, guides, and rules of behavior documents are all treated as attachments in OSCAL as well.
Further, any diagrams or images that normally appear in context, such as the authorization boundary diagram, are attached in the back-matter and referenced from the body of the OSCAL file, as described in Citations and Attachments in OSCAL Files. The following table represents attachments and embedded content.
Representation
|
|
XPath Queries
- PIA Attachment (Embedded Base64 encoded):
/*/back-matter/resource/prop[@name='type'][string(.)='privacy-impact-assessment']/../base64
- PIA Attachment (Relative Link):
/*/back-matter/resource/prop[@name=type][string(.)='privacy-impact-assessment']/../rlink/@href
- Publication Date of PIA:
/*/back-matter/resource/prop[@name=type][string(.)='privacy-impact-assessment']/../prop[@name="publication"]
Tools creating OSCAL content should include a media-type
for all rlink
and base64
fields, as well as a filename
for all base64
fields.
Tools should process rlink
and base64
content with or without these
fields. Where present they should be used when validating or rendering
the linked or embedded content.