Added comment template.

renamed file. Cleaning up scraps (and checking setup) Initial work modeling 'framework' for profiling functionality More improvements supporting framework (profile) example More adjustments to framework (profile) example Touchups to framework strawman Improvements to profiling (design and demo) Updated OSCAL namespace Fine adjustments for profiles especially regarding subcontrols First efforts at FedRAMP mapping More adjustments More adjustments to profiling including SP80-53 baselines as profiles (provisional) Slight improvement in logic just in case Much development on profiling More adjustments to profile examples and resolution including preventing infinite recursion in profile resolution Superseded by profile resolver XSLT FedRAMP misc CSF stuff mainly Touchups mostly Adjustments in integration and display (CSF example mainly) Rearranging schema docs Cleanup Misc improvements, touchups, reorg Linking README.md to OSCAL Overview.md Rename OSCAL Overview.md to OSCAL-Overview.md Update README.md Update README.md Transferred/integrated content from main README.md Moved content to docs/prose/OSCAL-Overview.md Added pointer to tag library, resequenced material Update README.md Create Profile-Catalog-Relationship.md Linked to the new Profile-Catalog-Relationship.md Create Schema-Decisions Rename Schema-Decisions to Schema-Decisions.md Update README.md Update README.md Update OSCAL-Overview.md More adjustments to schema docs (#25) A couple of more or less misleading points now corrected More updates Moved documentation inside working, eliminating working/doc branch also adjustments to readmes Amended and improved some high-level discussion FedRAMP demo adjustments incl temporary readme Fixed typo Added presentation Dave made on 10.17.2017. Correcting small bug in profile extraction Many files rearranged also more dev on framework analysis Touchups New XSLT now runs assessment of a nominal 'worksheet' framework document producing a copy with links and annotations Revs to high level docs and oscal-oscal.xml (issue #25) Create README.md Removed quotes Mainly demo files for profiling implementation Renaming in FedRAMP example to reduce confusion More improvements and clarifications in demo More adjustments incl filenames; new XSLT producing profile from linked worksheet Schematron supporting worksheet editing More adjustments to FedRAMP, schemas More readme adjustments More slight adjustments to schema setup Added rev5 draft controls and moved rev4 to a new directory for better organization. Added 800-53 schema version 2.0. Wrapup on Sprint 4 Now UTF-8 Added feed container schema. Tweaked to validate Created schema directories for OSCAL XML and JSON schema. Restructuring SP800-53 working dir Updates to SP800-53 stuff for rev5 More refinements Adjustments for SP800-53 rev5 OSCAL conversion More Fedramp analysis including restructuring Mini testing catalog JSON under XSLT3 tinkering Adjustments for capturing rev5 Fedramp mapping updates Removing process litter Schema and schema process updates Now presenting profile demos Rearranging schema files Updated readme Minor adjustments Many improvements and adjustments including an implementation of patching in profiles Improvements in resolution and rendering Edits to samples and readmes More unit tests Another example Schema adjustments; updated schema docs now describes profiling elements Preliminary FedRAMP analysis Standalone OSCAL SP800-53 rev4 and its baselines now in /examples Refinements SP800-53 updates Improvements to profiling Schematron w/ mini-testing Production pipeline adjustments Ran fresh for some catalog adjustments More detail on examples/mini-testing readme Mini testing refresh FEDRamp HIGHT baseline analysis with XSLTs Refinements and reorganization to FedRAMP (preliminary) profile extraction More refinements and polishing of FedRAMP examples Further adjustments to profile examples Further improvements to readme Refresh Adjustments in view of #64 Keeping profile schema in line w/ changes in core Starting on hand adjustments to FedRAMP Extending profiles Schematron to detect when profiles can/should use exclude instead of include More updates and name changes More minor adjustments (more of them and more minor) Cleanup mostly Improvements to tag library docs Updating docs Trying again (testing Github md alas) More FedRAMP readme More small edits Touches
usnistgov · Apr 5, 2018 · e81253b · e81253b
1 parent 0838450
commit e81253b
Show file tree

Hide file tree

Showing 234 changed files with 832,515 additions and 197,287 deletions.
diff --git a/OSCAL-dev.xpr b/OSCAL-dev.xpr
diff --git a/README.md b/README.md
@@ -1,36 +1,12 @@
 # Open Security Controls Assessment Language (OSCAL) 
 
-NIST is proposing the development of the Open Security Controls Assessment Language, or OSCAL, a hierarchical, formatted, XML-based (and JSON translation) schema that provides a standard for representing different categories of information pertaining to the publication, implementation, and assessment of security controls.
-
-OSCAL aims to:
-1. Standardize control, implementation, and assessment information using open, machine-readable formats. 
-1. Normalize the semantics of controls and profiles/baselines/overlays across multiple control catalogs (e.g., NIST SP 800-53, ISO/IEC 27001/2, COBIT 5).
-1. Provide interoperable formats to ensure that OSCAL information is used by tools in consistent ways.
-1. Promote adoption of OSCAL by tool developers by ensuring that OSCAL information is easy to create, use, and customize. 
-
-OSCAL consists of a number of layers:
-
-![OSCAL layers](docs/graphics/oscal-layers.png "OSCAL Layer Diagram")
-
-Starting from the bottom on the left, the OSCAL layers are:
-  * __Catalog__: Defines a set of security controls (e.g., NIST SP 800-53 Appendix F); may also define objectives and methods for assessing the controls (e.g., NIST SP 800-53A).
-  * __Profile__: Defines a set of security requirements, where meeting each requirement necessitates implementing one or more security controls; also called a _baseline_ or _overlay_.
-  * __Implementation__: Defines how each profile item is implemented for a given system component (System Security Plan).
-  * __Assessment__: Describes how the system assessment is to be performed.
-  * __Assessment Results__: Records the findings of the assessment.
-
-OSCAL will also integrate with: 
-  * __Metrics__: Defines metrics and measurements for understanding the effectiveness of the system’s security.
-  * __Mechanism__: Describes methods used to monitor the system’s current security state (e.g., Security Content Automation Protocol (SCAP)).
-
---------------
+NIST is proposing the development of the Open Security Controls Assessment Language, or OSCAL, a hierarchical, formatted, XML-based (and JSON translation) schema that provides a standard for representing different categories of information pertaining to the publication, implementation, and assessment of security controls. 
 
 This repository consists of the following directories pertaining to the OSCAL project:
   * [docs](docs): Documentation graphics, prose, and presentation slides
   * [working](working): Development artifacts (e.g., XML, XSLT, CSS, script, Markdown, and sample files, plus supporting files); additional documentation is posted under [working/doc](working/doc): 
   * [sources](sources): Resources used to produce OSCAL artifacts that are not maintained by the OSCAL project (e.g., a copy of the NIST SP 800-53 control data feed schema)
 
-## Update August 10th, 2017
-
-As the result of a new OSCAL initiative undertaken starting in mid-May, this repository has been updated. With this effort, we are stressing the agile development of a *minimal* format that is both generic enough to capture the breadth of data in scope (controls specifications), while also capable of ad-hoc tuning and extension to support peculiarities of both (industry or sector) standard and new control types.
+See [docs/prose/OSCAL-Overview.md](docs/prose/OSCAL-Overview.md) for an introduction to OSCAL and [docs/schema/oscal-tag-library.md](docs/schema/oscal-tag-library.md) for detailed information on the OSCAL data models and XML schema compositions.
 
+As the result of a new OSCAL initiative undertaken in May 2017, this repository was updated in August 2017. With this effort, we are stressing the agile development of a *minimal* format that is both generic enough to capture the breadth of data in scope (controls specifications), while also capable of ad-hoc tuning and extension to support peculiarities of both (industry or sector) standard and new control types.
diff --git a/docs/OSCAL-comment-template.xls b/docs/OSCAL-comment-template.xls
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,11 @@
+# OSCAL Documentation Materials
+
+This part of the repository contains OSCAL documentation and related supporting files.
+
+The 'docs' subdirectory contains the following:
+
+ * '[graphics](graphics)' - graphics files for reference by OSCAL documentation, and source files for generating particular graphics
+ * '[presentations](presentations)' - Microsoft Powerpoint slides for OSCAL presentations, some with notes
+ * '[prose](prose)' - Prose files (e.g., Markdown format) with narrative on OSCAL (OSCAL overview, how-to steps, etc.)
+ * '[schema](schema)' - OSCAL schema documentation, as further detailed in [schema/readme.md](schema/readme.md)
+
diff --git a/docs/presentations/OSCAL Overview 20170810 with draft notes.pptx b/docs/presentations/OSCAL Overview 20170810 with draft notes.pptx
diff --git a/docs/presentations/OSCAL Overview 20171017.pptx b/docs/presentations/OSCAL Overview 20171017.pptx
diff --git a/docs/prose/OSCAL Overview.md → docs/prose/OSCAL-Overview.md b/docs/prose/OSCAL Overview.md → docs/prose/OSCAL-Overview.md
@@ -5,9 +5,9 @@ This is an overview of the Open Security Controls Assessment Language (OSCAL). I
 
 Before discussing OSCAL, it is important to define three key OSCAL terms:
  * *Control*: A safeguard or countermeasure designed to satisfy a set of defined security and/or privacy requirements. While this is based on the NIST Special Publication (SP) 800-53 definition of "control", in the context of OSCAL it refers to a similar kind of requirement from a control catalog. 
- * *Catalog*: A set of security control definitions. Examples include the hundreds of controls in NIST SP 800-53, the 100+ controls in ISO 27002, and the practices in COBIT 5. 
- * *Profile*: A set of security requirements; also called a baseline or overlay. Examples include the control baselines in NIST SP 800-53, the FedRAMP baselines, and the PCI DSS requirements. A profile is basically selecting a set of security requirements from one or more control catalogs.
-
+ * *Catalog*: A set of security control definitions. Examples include the hundreds of controls in NIST SP 800-53 Revision 4 Appendix F, the 100+ controls in ISO 27002, and the practices in COBIT 5. 
+ * *Profile*: A set of security requirements, where meeting each requirement necessitates implementing one or more security controls. Also called a baseline or overlay. Examples include the control baselines in NIST SP 800-53, the FedRAMP baselines, and the PCI DSS requirements.
+ 
 ## Major challenges in security controls assessment
 
 OSCAL is attempting to address a number of challenges around security controls and security controls assessment. The core challenge, and one of the primary reasons for creating OSCAL, is that concepts like security controls and profiles are represented today largely in proprietary ways. In many cases they are written in prose documents that are imprecise, lead to differences in interpretation, and are not machine-readable, meaning that the prose instructions require someone to do data entry into a tool in order for the tool to use the information. 
@@ -29,9 +29,9 @@ The plans for OSCAL involve seven components, as depicted in the following diagr
 ![OSCAL layers](/docs/graphics/oscal-layers.png "OSCAL Layer Diagram")
 
 Here are the current definitions for each component. As the project progresses, these definitions may evolve. They are included here to indicate the overall body of work for OSCAL and not the finalized details of each component.  
- * *Catalog*: Defines a set of security controls (e.g., NIST SP 800-53 Appendix F); may also define objectives and methods for assessing the controls (e.g., NIST SP 800-53A). Combining assessment objectives and methods with security controls has been done because some control catalog formats, such as COBIT 5, address assessment information directly. Others have it separately, like 800-53A. Including assessment objectives within the OSCAL catalog model simplifies the entire OSCAL operational model.
- * *Profile*: Defines a set of security requirements, where meeting each requirement necessitates implementing one or more security controls. The profile format will allow for selecting security controls using a number of different mechanisms as well as tailoring those controls (e.g., assigning parameter values, modifying requirements). A profile can include controls from more than one catalog, so an organization could have a single profile that references controls from several catalogs.
- * *Implementation*: Defines how each profile item is implemented. This can represent a machine-readable system security plan in OSCAL format. It will also support transforms from the machine-readable form to a human-readable version.
+ * *Catalog*: In addition to defining a set of security controls, may also define objectives and methods for assessing the controls (e.g., NIST SP 800-53A). Combining assessment objectives and methods with security controls has been done because some control catalog formats, such as COBIT 5, address assessment information directly. Others have it separately, like 800-53A. Including assessment objectives within the OSCAL catalog model simplifies the entire OSCAL operational model.
+ * *Profile*: The profile format will allow for selecting security controls using a number of different mechanisms as well as tailoring those controls (e.g., assigning parameter values, modifying requirements). A profile can include controls from more than one catalog, so an organization could have a single profile that references controls from several catalogs. For more information on the relationship between profiles and catalogs, see [Profile-Catalog-Relationship.md](Profile-Catalog-Relationship.md).
+ * *Implementation*: Defines how each profile item is implemented for a given system component. This can represent a machine-readable system security plan in OSCAL format. It will also support transforms from the machine-readable form to a human-readable version.
  * *Assessment*: Describes how the system assessment is to be performed.
  * *Assessment Results*: Records the findings of the assessment.
  * *Metrics*: Defines metrics and measurements for understanding the effectiveness of the system’s security. 
@@ -52,14 +52,6 @@ Standardized OSCAL catalog and profile models should also be beneficial to sever
  * *Auditors/assessors*: perform audits/assessments on demand with minimal effort
  * *Policy personnel*: identify systemic problems that necessitate changes to organization security policy
 
-## The relationship between the OSCAL catalog and profile models
-
-To understand the relationship between the OSCAL catalog and profile models, consider the trivial conceptual example in the figure below. This example represents the NIST SP 800-53 low baseline. The catalog defines the possible security controls within the scope of NIST SP 800-53. The profile indicates which security controls from the catalog are required to be compliant with the low baseline. Using OSCAL formats for the catalog and profile makes the mappings between the catalog and the profile explicit and machine readable. 
-
-![trivial_example](/docs/graphics/profile-catalog-mapping-trivial-example.png "Trivial Example of Profile and Catalog Mapping")
-
-OSCAL provides a standarized, machine-readable profile with clear semantics. OSCAL allows profiles to be generated using the same interoperable format regardless of the underlying catalogs that are being used, like ISO 27001/2 and COBIT 5. 
-
 ## OSCAL deliverables
 
 The OSCAL project is producing several types of deliverables, including the following:

diff --git a/docs/prose/Profile-Catalog-Relationship.md b/docs/prose/Profile-Catalog-Relationship.md
@@ -0,0 +1,7 @@
+# The relationship between the OSCAL catalog and profile models
+
+To understand the relationship between the OSCAL catalog and profile models, consider the trivial conceptual example in the figure below. This example represents the NIST SP 800-53 low baseline. The catalog defines the possible security controls within the scope of NIST SP 800-53. The profile indicates which security controls from the catalog are required to be compliant with the low baseline. Using OSCAL formats for the catalog and profile makes the mappings between the catalog and the profile explicit and machine readable. 
+
+![trivial_example](/docs/graphics/profile-catalog-mapping-trivial-example.png "Trivial Example of Profile and Catalog Mapping")
+
+OSCAL provides a standarized, machine-readable profile with clear semantics. OSCAL allows profiles to be generated using the same interoperable format regardless of the underlying catalogs that are being used, like ISO 27001/2 and COBIT 5. 
diff --git a/working/doc/schema/oscal-docs-html.xsl → docs/schema/oscal-docs-html.xsl b/working/doc/schema/oscal-docs-html.xsl → docs/schema/oscal-docs-html.xsl
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   version="1.0"
-  xmlns:oscal="http://scap.nist.gov/schema/oscal"
+  xmlns:oscal="http://csrc.nist.gov/ns/oscal/1.0"
   xmlns="http://www.w3.org/1999/xhtml"
   exclude-result-prefixes="oscal">
 
@@ -18,6 +18,8 @@
         <title>
           <xsl:value-of select="descendant::oscal:title[1]"/>
         </title>
+        <!-- b/c XProc serialization doesn't do this -->
+        <meta charset="utf-8"/>
         <style type="text/css">
 
 section, div { margin-top:1em }
@@ -38,16 +40,17 @@ div div div h3 { font-size: 110% }
 .param { font-style: italic }
 .insert, .choice { border: thin solid black; padding: 0.1em }
 
-.subst  { color: midnightblue; font-family: sans-serif; font-sizea; 85% } 
+.subst  { color: midnightblue; font-family: sans-serif; font-size; 85% } 
 
 .param .em { font-style: roman }
 
 .tag:before { content: '\3C' }
 .tag:after  { content: '\3E' }
 .code { font-family: monospace }
 
-#toc-panel { margin-top: 0em; border: thin solid black; float: left; max-width: 25%; font-size: 80%; font-family: sans-serif;
-padding: 1em; position: fixed; max-height: 80ex; overflow: auto }
+#toc-panel { margin-top: 0em; border: thin solid black; float: left;
+  margin-left: 1rem; max-width: 25%; font-size: 80%; font-family: sans-serif;
+  padding: 1em; max-height: 80ex; overflow: auto; position: fixed }
 .toc { margin: 0em; padding: 0em; margin-left: 1em; border: none }
 .toc-line { margin: 0em; padding-left: 3em; text-indent: -3em }
 
@@ -72,23 +75,23 @@ a:visited { color: midnightblue }
   </xsl:template>
 
 
-  <xsl:template match="oscal:catalog" mode="toc">
+  <xsl:template match="oscal:catalog | oscal:framework | oscal:worksheet" mode="toc">
     <div id="toc-panel">
-      <xsl:apply-templates select="oscal:title | oscal:prop[@class='tag']" mode="toc"/>
-      <xsl:apply-templates select="oscal:section | oscal:group | oscal:control" mode="toc"/>
+      <xsl:apply-templates select="oscal:title" mode="toc"/>
+      <xsl:apply-templates select="oscal:section | oscal:group | oscal:control | oscal:component" mode="toc"/>
     </div>
   </xsl:template>
 
-  <xsl:template match="oscal:section | oscal:group | oscal:control" mode="toc">
+  <xsl:template match="oscal:section | oscal:group | oscal:control | oscal:component" mode="toc">
     <div class="toc">
       <xsl:apply-templates select="oscal:title | oscal:prop[@class='tag']" mode="toc"/>
-      <xsl:apply-templates select="oscal:section | oscal:group | oscal:control" mode="toc"/>
+      <xsl:apply-templates select="oscal:section | oscal:group | oscal:control | oscal:component" mode="toc"/>
     </div>
   </xsl:template>
 
   <xsl:template match="oscal:title" mode="toc">
     <p class="toc-line">
-      <a href="#{generate-id(parent::*[not(self::oscal:catalog)])}">
+      <a href="#{generate-id(parent::*[not(self::oscal:catalog|self::oscal:framework|self::oscal:worksheet)])}">
         <xsl:apply-templates/>
       </a>
     </p>
@@ -110,13 +113,17 @@ a:visited { color: midnightblue }
     </p>
   </xsl:template>
 
-  <xsl:template match="oscal:catalog">
-    <div id="main" class="catalog">
+  <xsl:template match="oscal:catalog | oscal:framework | oscal:worksheet">
+    <div id="main" class="{local-name()}">
       <xsl:apply-templates/>
     </div>
   </xsl:template>
 
-  <xsl:template match="oscal:catalog/oscal:title"/>
+  <xsl:template match="oscal:catalog/oscal:title | oscal:framework/oscal:title | oscal:worksheet/oscal:title">
+    <h1>
+      <xsl:apply-templates/>
+    </h1>
+  </xsl:template>
 
   <xsl:template match="oscal:title">
    <!-- <xsl:for-each select="..">
@@ -146,7 +153,7 @@ a:visited { color: midnightblue }
   <!--<xsl:key name="assignment"  match="oscal:param" use="@target"/>-->
 
 
-  <xsl:template match="oscal:control">
+  <xsl:template match="oscal:control | oscal:component">
     <div class="control {@class}" id="{generate-id(.)}">
       <xsl:call-template name="make-title">
         <xsl:with-param name="runins" select="oscal:prop[@class='tag'] | oscal:prop[@class='full_name']"/>
@@ -156,7 +163,7 @@ a:visited { color: midnightblue }
   </xsl:template>
 
   <!-- Picked up in parent, by default this element is suppressed -->
-  <xsl:template match="oscal:control/oscal:title"/>
+  <xsl:template match="oscal:control/oscal:title  | oscal:component/oscal:title"/>
 
   <xsl:template name="make-title">
     <xsl:param name="runins" select="/.."/>
@@ -229,7 +236,13 @@ a:visited { color: midnightblue }
       <xsl:apply-templates/>
     </p>
   </xsl:template>
-
+
+  <xsl:template match="oscal:pre">
+    <pre class="pre">
+      <xsl:apply-templates/>
+    </pre>
+  </xsl:template>
+
   <xsl:template match="oscal:inject">
     <xsl:variable name="param" select="@param-id"/>
     <xsl:variable name="closest-param" select="ancestor-or-self::*/oscal:param[@id=$param][last()]"/>
@@ -251,6 +264,11 @@ a:visited { color: midnightblue }
       <xsl:apply-templates/>
     </ol>
   </xsl:template>
+  <xsl:template match="oscal:ul">
+    <ul class="ul">
+      <xsl:apply-templates/>
+    </ul>
+  </xsl:template>
   <xsl:template match="oscal:li">
     <li class="li">
       <xsl:apply-templates/>