Added section on security review

Change-Id: I80576d9b3d13f9b2a4c203e735ef4b5f54ef3641

security-guide/source/index.rst

@@ -36,6 +36,7 @@ Contents
    instance-management.rst
    monitoring-logging.rst
    compliance.rst
+   security-review.rst
 
 Appendix
 ~~~~~~~~

security-guide/source/security-review.rst

@@ -0,0 +1,69 @@
+===============
+Security Review
+===============
+
+The goal of security review in the OpenStack community is to identify
+weaknesses in design or implementation of OpenStack projects. While rare,
+these weaknesses could potentially have catastrophic effects on the security of
+an OpenStack deployment, and therefore work should be undertaken to minimize
+the likelihood of these defects in released projects. The OpenStack Security
+Project asserts that once a security review of a project has been completed,
+the following are known and documented:
+
+- All entry points into a system
+- What assets are at risk
+- Where data is persisted
+- How data travels between components of the system
+- Data formats and transformations
+- External dependencies of the project
+- An agreed set of findings and/or defects
+- How the project interacts with external dependencies
+
+A common reason to perform a security review on an OpenStack project is to
+enable that project to achieve the *vulnerability:managed* governance tag. The
+OpenStack Vulnerability Management Team (VMT) applies the
+`vulnerability:managed tag
+<https://governance.openstack.org/reference/tags/vulnerability_managed.html>`__
+to projects where the report reception and disclosure of vulnerabilities is
+managed by the VMT. One of the requirements for gaining the tag is that
+some form of security review, audit or threat analysis has been performed on
+the project.
+
+The OpenStack Security Project (OSSP) has worked with the VMT to agree that an
+architectural review of the best practice deployment for a project is an
+appropriate form of security review, balancing the need for review with the
+resource requirements for a project of the scale of OpenStack. Security
+architecture review is also often referred to as *threat analysis*, *security
+analysis* or *threat modeling*, in the context of OpenStack security review
+these terms are synonymous for an architectural security review which may
+identify defects in the design of a project or reference architecture, and may
+lead to further investigative work to verify parts of the implementation.
+
+There are two routes that an OpenStack project may take to complete a security
+review:
+
+#. Review by OpenStack Security Project
+#. Review by a third party review body, with validation from the OpenStack
+   Security Project
+
+Security review by the OSSP is expected to be the normal route for new projects
+and for cases where third parties have not performed security reviews or are
+unable to share their results. Information for projects that require a security
+review by the OSSP will be available in the upcoming security review process.
+
+In cases where a security review has already been performed by a third party,
+or where a project prefers to use a third party to perform their review,
+information on how to take the output of that third party review and submit it
+to the OSSP for validation will be available in the upcoming third party
+security review process.
+
+In either case, the requirements for documentation artefacts are similar - the
+project must provide an architecture diagram for a best practise deployment.
+Vulnerability scans and static analysis scans are not sufficient evidence for
+a third party review, although they are strongly recommended as part of the
+development cycle for all teams.
+
+.. toctree::
+   :maxdepth: 2
+
+   security-review/architecture-page-guidance.rst

security-guide/source/security-review/architecture-page-guidance.rst

@@ -0,0 +1,209 @@
+==========================
+Architecture page guidance
+==========================
+
+The purpose of an architecture page is to document the architecture, purpose
+and security controls of a service or project. It should document the best
+practice deployment of that project.
+
+There are some key sections to the architecture page, which are explained in
+more detail below:
+
+- Title, version information, contact details
+- Project description and purpose
+- Primary users and use-cases
+- External dependencies and associated security assumptions
+- Components
+- Architecture diagram
+- Data assets
+- Data asset impact analysis
+- Interfaces
+
+
+Title, version information, contact details
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section titles the architecture page, gives the status of the review
+(draft, ready for review, reviewed) and captures the release and version of the
+project (where relevant). It also records the PTL for the project, the
+project's architect who is responsible for producing the architecture page,
+diagrams and working through the review (this may or may not be the PTL), and
+the security reviewer(s).
+
+
+Project description and purpose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section will contain a brief description of the project to introduce third
+parties to the service. This should be a paragraph or two and can be cut/paste
+from wiki or other documentation. Include links to relevant presentations and
+further documentation if available.
+
+For example:
+
+"Anchor is a public key infrastructure (PKI) service, which uses automated
+certificate request validation to automate issuing decisions. Certificates are
+issued for short time periods (typically 12-48 hours) to avoid the flawed
+revocation issues associated with CRLs and OCSP."
+
+
+Primary users and use-cases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A list of the expected primary users of the implemented architecture and their
+use-cases. 'Users' can either be actors or other services within OpenStack.
+
+For example:
+
+1. End users will use the system to store sensitive data, such as passphrases
+   encryption keys, etc.
+2. Cloud administrators will use the administrative APIs to manage resource
+   quotas.
+
+
+External dependencies and associated security assumptions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+External dependencies are items outside of the control of the service that are
+required for its operation, and may impact the service if they were compromised
+or became unavailable. These items are usually outside the control of the
+developer but within the control of the deployer, or they may be operated by a
+third party. Appliances should be regarded as external dependencies.
+
+For example:
+
+- Nova compute service depends on an external authentication and authorization
+  service. In a typical deployment this dependency will be fulfilled by the
+  keystone service.
+- Barbican depends on the use of Hardware Security Module (HSM) appliance.
+
+
+Components
+~~~~~~~~~~
+
+A list of the components of the deployed project excluding external entities.
+Each component should be named and have a brief description of its purpose, and
+be labeled with the primary technology used (e.g. Python, MySQL, RabbitMQ).
+
+For example:
+
+- keystone listener process (Python): Python process that consumes keystone
+  events published by the keystone service.
+- Database (MySQL): MySQL database to store barbican state data related to its
+  managed entities and their metadata.
+
+
+Service architecture diagram
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The architecture diagram shows the logical layout of the system so the security
+reviewers can step through the architecture with the project team. It is a
+logical diagram which shows how the components interact, how they connect to
+external entities, and where communications cross trust boundaries. Further
+information on architecture diagram, including a key of symbols, will be given
+in the upcoming architecture diagram guidance. Diagrams can be drawn in any
+tool that can produce a diagram which uses the symbols in the key, however
+`draw.io <https://draw.io>`__ is strongly recommended.
+
+This example shows the barbican architecture diagram:
+
+.. image:: ../figures/security_review_barbican_architecture.png
+
+
+Data assets
+~~~~~~~~~~~
+
+Data assets are user data, high-value data, configuration items, authorization
+tokens or other items that an attacker may target. The set of data items will
+vary between projects, but in general it should be considered as classes of
+data which are vital to the intended operation of the project. The level of
+detail required is somewhat dependent on the context. Data can usually be
+grouped, such as 'user data', 'secret data', or 'configuration files', but may
+be singular, like 'admin identity token' or 'user identity token', or 'database
+configuration file'.
+
+Data assets should include a statement of where that asset is persisted.
+
+For example:
+
+- *Secret data* - Passphrases, Encryption Keys, RSA Keys - persisted in
+  Database [PKCS#11] or HSM [KMIP] or [KMIP, Dogtag]
+- *RBAC rulesets* - persisted in policy.json
+- *RabbitMQ Credentials* - persisted in barbican.conf
+- *keystone Event Queue Credentials* - persisted in barbican.conf
+- *Middleware configuration* - persisted in paste.ini
+
+
+Data asset impact analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The data asset impact analysis breaks down the impact of the loss of
+confidentiality, integrity or availability for each data asset. Project
+architects should attempt to complete this, as they understand their project in
+the most detail, but the OpenStack Security Project (OSSP) will work through
+this with the project during the security review and are likely to add or
+update the impact details.
+
+For example:
+
+- *RabbitMQ credentials*:
+
+  - Integrity Failure Impact: barbican and Workers can no longer access the
+    queue. Denial of service.
+  - Confidentiality Failure Impact: An attacker could add new tasks to the
+    queue which would be executed by workers. User quotas could be exhausted by
+    an attacker. DoS. User would be unable to create genuine secrets.
+  - Availability Failure Impact: barbican could no longer create new secrets
+    without access to the queue.
+
+- *keystone credentials*:
+
+  - Integrity Failure Impact: barbican will not be able to validate user
+    credentials and fail. DoS.
+  - Confidentially Failure Impact: A malicious user might be able to abuse
+    other OpenStack services (depending on keystone role configurations) but
+    barbican is unaffected. If the service account for token validation also
+    has barbican admin privileges, then a malicious user could manipulate
+    barbican admin functions.
+  - Availability Failure Impact: barbican will not be able to validate user
+    credentials and fail. DoS.
+
+
+Interfaces
+~~~~~~~~~~
+
+The interfaces listing captures interfaces within the scope of the review. This
+includes  connections between blocks on the architecture diagram which cross a
+trust boundary or do not use an industry standard encryption protocol such as
+TLS or SSH. For each interface the following information is captured:
+
+  - The protocol used
+  - Any data assets in transit across that interface
+  - Information on authentication used to connect to that interface
+  - A brief description of the purpose of the interface.
+
+This is recorded in the following format:
+
+From->To *[Transport]*:
+
+- Assets in flight
+- Authentication?
+- Description
+
+For example:
+
+1. Client->API Process *[TLS]*:
+
+   - Assets in flight: User keystone credentials, plaintext secrets, HTTP verb,
+     secret ID, path
+   - Access to keystone credentials or plaintext secrets is considered a total
+     security failure of the system - this interface must have robust
+     confidentiality and integrity controls.
+
+
+Resources
+~~~~~~~~~
+
+List resources relevant to the project, such as wiki pages describing its
+deployment and usage, and links to code repositories and relevant
+presentations.

security-threat-analysis/source/index.rst

@@ -13,7 +13,6 @@ Contents
 .. toctree::
    :maxdepth: 1
 
-   objectives.rst
    threat-analysis-process.rst
    templates/architecture-page.rst
    templates/review-findings.rst

security-threat-analysis/source/objectives.rst

@@ -1,16 +0,0 @@
-=======================================
-Objectives for Security Threat Analysis
-=======================================
-
-
-We assert that after a Threat Analysis we:
-
-- Know all entry points into a system
-- Know what assets are at risk
-- Know where data is persisted
-- Understand how data travels between components of the system
-- Understand data formats and transformations
-- Document external dependencies
-- Identified who we are (and are not) protecting against
-- Understand the impact of degrading controls
-- Have a list of agreed defects

security-threat-analysis/source/todo.rst

@@ -6,11 +6,28 @@ Needed
 ~~~~~~
 
 
-#. TA Calendar
-#. Wiki page saying what TAs have been done, and havent.
+#. page saying what TAs have been done, and havent.
 #. Etherpad template for review tracking
 #. process
-
-
-Current Status
-~~~~~~~~~~~~~~
+#. Improve documentation around context for OpenStack deployments, namely that
+   they reflect best practice, and the documentation shoud explain what to do
+   when things can be changed.
+#. Add information on filling in interfaces table from diagram.
+#. Remove U-C, O-C, I-C guidance
+#. Add guidance that explains the importance of paying special attention to
+   interfaces that cross trust boundaries
+#. Reviewer to build sequence diagrams in real time during the review
+#. Document how we assess a third party review to be in line with our key
+   security assertions. I think perhaps we need a mapping table or something.
+#. Should we prioritise assets.
+#. Data assets should be listed in the architecture page before the review.
+#. Figure out how to protect etherpad contents while retaining ability to share
+   and collaboratively edit it.
+#. Add 'review CIA for data assets to process'
+#. change 'review CIA for each interface' to ' 'review CIA for each interface
+   that crosses a security domain or each interface that doesn't use TLS'
+#. Best practice for each type of asset connection
+#. Document what a trust boundary is
+#. Document what an asset is. Config file? elements within a config file?
+#. Documnet what level of detail we want for external dependencies and give
+   examples.