Updating Documentation section from DocBook to RST

+ Concatenated ch, section, and case study file into one
+ Stripped DocBook tags
+ Added RST tags
+ Added image tag for picture
+ Separated back into 3 files
+ Added documentation folder and files
+ Added figures and updated case-studies.rst filename
+ Updated case-studies filename and command to config

Change-Id: I0a8c4f8de7899b43db248accb1f0e4dde78b5b7f
Partial-Bug: #1463111

security-guide-rst/source/documentation.rst

@@ -1,3 +1,17 @@
 ====================
-System Documentation
+System documentation
 ====================
+
+The system documentation for an OpenStack cloud deployment should follow the
+templates and best practices for the Enterprise Information Technology System
+in your organization. Organizations often have compliance requirements which
+may require an overall System Security Plan to inventory and document the
+architecture of a given system. There are common challenges across the industry
+related to documenting the dynamic cloud infrastructure and keeping the
+information up-to-date.
+
+.. toctree::
+   :maxdepth: 2
+
+   documentation/system-documentation-requirements.rst
+   documentation/case-studies.rst

security-guide-rst/source/documentation/case-studies.rst

@@ -0,0 +1,41 @@
+============
+Case studies
+============
+
+Earlier in the :doc:`../introduction/introduction-to-case-studies`
+we introduced the Alice and Bob case studies where Alice is deploying a
+government cloud and Bob is deploying a public cloud each with different
+security requirements. Here we discuss how Alice and Bob would address their
+system documentation requirements. The documentation suggested above includes
+hardware and software records, network diagrams, and system configuration
+details.
+
+Alice's private cloud
+~~~~~~~~~~~~~~~~~~~~~
+
+As Alice needs detailed documentation to satisfy FISMA and FedRAMP
+requirements, she implements Microsoft's Systems Center due to its established
+auditing capabilities to support FedRAMP artifact creation, including capturing
+hardware, firmware, and software details. Architecture docs are created that
+clearly define the components, services, and data flows, with supporting
+materials listing the details of those services including processes, protocols,
+and ports used. These documents are then stored on a secured file share,
+allowing authenticated access for service and architecture teams to reference.
+
+Additionally, the security domains are clearly highlighted on each document,
+and asset groups are categorized per the NIST Risk Management Framework.
+Specifically, Alice will call out the fact that several services cross security
+domains, such as the API endpoints crossing the Public and Management domains,
+the Identity data being served from a Federated entity crossing from a system
+she does not manage to her Management domain, the Database service crossing
+both Data and Guest domains, and hypervisor crossing Management, Guest, and
+Public domains. She will then be able to dictate additional controls that
+ensure and reinforce the trust level of each domain. For example, the
+application will be exposed to the Internet, and therefore data coming through
+that will initially be untrusted before it is moved through to the data domain
+and into the database.
+
+Bob's public cloud
+~~~~~~~~~~~~~~~~~~
+
+In this case, Bob will approach these steps the same as Alice.

security-guide-rst/source/documentation/system-documentation-requirements.rst

@@ -0,0 +1,92 @@
+=================================
+System documentation requirements
+=================================
+
+System roles and types
+~~~~~~~~~~~~~~~~~~~~~~
+
+The two broadly defined types of nodes that generally make up an OpenStack
+installation are:
+
+Infrastructure nodes
+   The nodes that run the cloud related services such as the OpenStack
+   Identity service, the message queuing service, storage, networking, and
+   other services required to support the operation of the cloud.
+
+Compute, storage, or other resource nodes
+   Provide storage capacity or virtual machines for your cloud.
+
+System inventory
+~~~~~~~~~~~~~~~~
+
+Documentation should provide a general description of the OpenStack environment
+and cover all systems used (production, development, test, etc.). Documenting
+system components, networks, services, and software often provides the
+bird's-eye view needed to thoroughly cover and consider security concerns,
+attack vectors and possible security domain bridging points. A system inventory
+may need to capture ephemeral resources such as virtual machines or virtual
+disk volumes that would otherwise be persistent resources in a traditional IT
+system.
+
+Hardware inventory
+------------------
+
+Clouds without stringent compliance requirements for written documentation
+might benefit from having a Configuration Management Database
+(:term:`configuration management database (CMDB)<CMDB>`). CMDBs are
+normally used for hardware asset tracking and overall life-cycle
+management. By leveraging a CMDB, an organization can quickly identify
+cloud infrastructure hardware such as compute nodes, storage nodes, or
+network devices. A CMDB can assist in identifying assets that exist on
+the network which may have vulnerabilities due to inadequate
+maintenance, inadequate protection or being displaced and forgotten. An
+OpenStack provisioning system can provide some basic CMDB functions if
+the underlying hardware supports the necessary auto-discovery features.
+
+Software inventory
+------------------
+
+As with hardware, all software components within the OpenStack deployment
+should be documented. Examples include:
+
+* System databases, such as MySQL or mongoDB
+* OpenStack software components, such as Identity or Compute
+* Supporting components, such as load-balancers, reverse proxies, DNS or DHCP
+  services
+
+An authoritative list of software components may be critical when assessing the
+impact of a compromise or vulnerability in a library, application or class of
+software.
+
+Network topology
+~~~~~~~~~~~~~~~~
+
+A network topology should be provided with highlights specifically calling out
+the data flows and bridging points between the security domains. Network
+ingress and egress points should be identified along with any OpenStack logical
+system boundaries. Multiple diagrams may be needed to provide complete visual
+coverage of the system. A network topology document should include virtual
+networks created on behalf of tenants by the system along with virtual machine
+instances and gateways created by OpenStack.
+
+Services, protocols and ports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Knowing information about organizational assets is typically a best practice,
+therefore it is beneficial to create a table which contains information
+regarding the service, protocols and ports being utilized in the OpenStack
+deployment. The table can be created from information derived from a CMDB or
+can be constructed manually. The table can be customized to include an overview
+of all services running within the cloud infrastructure. The level of detail
+contained in this type of table can be beneficial as the information can
+immediately inform, guide, and assist with validating security requirements.
+Standard security components such as firewall configuration, service port
+conflicts, security remediation areas, and compliance become easier to maintain
+when concise information is available. An example of this type of table is
+provided below:
+
+.. image:: ../figures/services-protocols-ports.png
+
+Referencing a table of services, protocols and ports can help in understanding
+the relationship between OpenStack components. It is highly recommended that
+OpenStack deployments have information similar to this on record.