Adding documentation for security threat analysis

Change-Id: I77353def7997ab60164c97f44eaf6ada06231f52

.gitignore

@@ -12,6 +12,7 @@
 # Build directories
 publish-docs/
 security-guide/build
+security-threat-analysis/build
 
 # Transifex Client Setting
 .tx

security-threat-analysis/source/architecture-diagram-guidance.rst

@@ -0,0 +1,191 @@
+=============================
+Architecture diagram guidance
+=============================
+
+Types of diagrams required
+--------------------------
+
+This page provides guidance on architecture diagrams for threat
+analysis, a template for architecture documentation is available at <link>.
+
+Two types of diagrams are required for threat analysis:
+
+-  A service architecture diagram
+-  One or more information flow diagrams (either data flow diagrams,
+   sequence diagrams, or both)
+
+Examples of each of these are given below. There are no firm diagramming
+toolchain requirements, but the tool used must be able to draw the diagrams
+discussed. It is generally preferable to use a text-based diagram
+generator so diagrams can be managed with gerrit. Some options for tools
+include:
+
+- draw.io (proprietary XML files, but very easy to use)
+- Google drawing (no XML/text output, but can be used collaboratively)
+- blockdiag (non-WYSIWYG with a steeper learning curve, suitable for very
+  simple diagrams)
+
+When drawing architecture diagrams, it may be beneficial to draw the diagram on
+paper or a whiteboard before attempting to draw it with a diagramming tool.
+
+When you have completed the diagram, export both a text version (if available)
+and a Portable Network Graphic (.png) file to be committed to the repository
+with the architecture page.
+
+Service architecture diagram requirements
+-----------------------------------------
+
+Service Architecture diagrams contain these elements:
+
+-  Components
+
+   -  A rectangle containing a unique name is used to depict each
+      component
+   -  Components may be servers, clusters, or individual
+      processes
+
+   -  Standard component shapes should be used to illustrate component
+      types
+
+      -  A vertical cylinder indicates storage or a database
+      -  A horizontal cylinder (a “pipe” shape) indicates a message
+         queue (use an elongated rectangle if horizontal cylinders are
+         unavailable)
+
+   -  A dashed rectangle indicates a future component
+   -  Multi-instances of a component should be indicated by a quantity after
+      the component name, for example (100), and if possible layered component
+      boxes
+   -  Component shapes don’t need to be all the same size. Some component
+      shapes may be shrunk to allow application layers to be easily recognized,
+      without creating a maze of crossed interface lines
+   -  User access over the internet can be indicated by a cloud-shaped
+      component, but where multiple connections or external parties are
+      connected via the internet, a separate internet trust domain should be
+      shown
+
+-  Interfaces
+
+   -  An arrow connecting two components is used to depict an interface
+   -  Each interface has a unique number and name; listing the network
+      protocol (in parenthesis) is strongly recommended
+   -  Direction of interface arrow is from the component initiating the
+      connection; the arrowhead points to the listening/receiving component
+   -  A future interface is indicated as a dashed arrow
+
+-  Trust domains
+
+   -  Boundaries between trust domains must be shown
+   -  Trust boundaries based on networks are indicated as a dashed line
+      (preferably with rounded corners), with the Network name listed at the
+      upper or lower boundary
+   -  Trust boundaries based on groups of components (such as server pairs,
+      clusters, processes, or collections of related components) are indicated
+      by a dotted box
+   -  When a third party network boundary is used to illustrate a trust domain,
+      use that third party's name as the network boundary label
+
+
+Service architecture diagram template
+-------------------------------------
+
+This template illustrates the elements of a service architecture diagram.
+
+.. image:: figures/Template_Architecture-diagram.png
+
+
+Information flow diagram requirements
+-------------------------------------
+
+Information flow diagrams depict the flow of data between entities to
+illustrate the steps in a process or procedure. Often, multiple diagrams
+are created to illustrate individual use cases.
+
+Each information flow diagram must be in the form of either a data flow
+diagram (DFD) or a sequence diagram. The architect may select either
+type of diagram (or both) for illustrating information flows within the
+service.
+
+Information flow diagrams contain the following elements:
+
+-  Entities
+
+   -  An entity may be a single process, multiple processes within a trust
+      domain, a data store, or an external entity.
+   -  Each entity has a unique name which should match a name on the
+      architecture diagram
+   -  The number of entities on a flow diagram often matches the number of
+      components on a service architecture diagram.
+
+-  Data flows
+
+   -  Arrows indicate data flows between entities; the direction of the
+      arrow indicates the direction of data movement
+   -  Any pair of entities may have multiple sets of arrows to
+      illustrate a multi-step exchange of data between the entities
+   -  Typically every interface on a service architecture diagram has
+      one or more corresponding data flows on a flow diagram
+
+-  Trust boundaries
+
+   -  Groups of entities with the same level of privilege form a trust
+      domain, the boundaries of which are indicated by a dashed line in
+      DFDs and by a shallow rectangle on sequence diagrams
+
+-  Optional supplementary information
+
+   -  Textual notes on the diagram can provide clarification on data
+      types sent and received, changes in privilege, or steps forming a
+      use case
+
+
+Data flow diagram template
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This template illustrates the elements of a data flow diagram.
+
+.. image:: figures/Template_DFD.png
+
+
+Sequence diagram template
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following template illustrates the elements of a sequence diagram.
+
+.. image:: figures/Template_Sequence-diagram.png
+
+Sequence diagrams can be quickly and easily generated from text using
+http://WebSequenceDiagrams.com . Enter a specification using a simple scripting
+language, as follows. Be sure to include authentication steps in your diagram.
+
+title Issue Certificate
+
+Admin->GUI: 1. Login
+
+GUI->Controller: 2. List(pending)
+
+Controller->DB: 3. Fetch DB
+
+DB->Controller: 4. Cert DB
+
+Controller->Controller: 5. Filter(pending)
+
+Controller->GUI: 6. Show pending certs
+
+Admin->GUI: 7. Issue(ID)
+
+GUI->Controller: 8. Issue(ID)
+
+Controller->Controller: 9. Get CSR(ID)
+
+Controller->CA: 9. Sign(CSR)
+
+CA->Controller: 10. Cert
+
+Controller->DB: 11. Update DB (ID, Issued, Cert)
+
+Controller->User: 12. Email Notification
+
+The tool creates a sequence diagram as follows:
+
+.. image:: figures/Example_Generated-sequence-diagram.png

security-threat-analysis/source/conf.py

@@ -0,0 +1,258 @@
+# -*- coding: utf-8 -*-
+#
+# Anchor documentation build configuration file, created by
+# sphinx-quickstart on Wed Jul 29 15:52:08 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Anchor'
+copyright = u'2015'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'dev'
+# The full version, including alpha/beta/rc tags.
+release = 'dev'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Anchordoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'Anchor.tex', u'Anchor Documentation',
+   u'see git log', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'anchor', u'Anchor Documentation',
+     [u'see git log'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'Anchor', u'Anchor Documentation',
+   u'see git log', 'Anchor', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False

security-threat-analysis/source/figures/arch_diagram.diag

@@ -0,0 +1,73 @@
+blockdiag {
+
+  // Set labels and shapes for components
+  api_access [label = "Api Access", shape = cloud];
+  component_1 [label = "Component Name"];
+  component_2 [label = "Component Name"];
+  multi_component [label = "Component Name (>200)", stacked];
+  node_in_cluster [label = "A node in a cluster"];
+  future_component [label = "Future component", style = dashed]
+  db [label = "Database name", shape = flowchart.database]
+  mq [label = "Message queue", shape = roundedbox]
+  thirdparty [label = "Database name"]
+
+
+  // Define groups
+  group {
+    orientation = landscape;
+    label = "Nova VM Network";
+    shape = line;
+    style = dotted;
+
+    group {
+      orientation = portrait;
+      label = "Name of subsystem";
+      shape = line;
+      style = dotted;
+
+      //components
+      component_1;
+      component_2;
+    }
+
+    group {
+      orientation = portrait;
+      label = "Name of cluster";
+      shape = line;
+      style = dotted;
+
+      //components
+      node_in_cluster;
+    }
+  }
+
+  group {
+    orientation = landscape;
+    label = "Production Network";
+    shape = line;
+    style = dotted;
+
+    //components
+    multi_component;
+    future_component;
+  }
+
+  group {
+    label = "3rdparty.com";
+    shape = line;
+    style = dashed;
+
+    //components
+    thirdparty;
+  }
+
+  //Add the components and draw the lines
+  api_access -> component_1 [label = "1. Interface label (HTTPS)"];
+  component_1 -> component_2 [label = "2. Label (HTTP)"];
+
+  component_2 -> multi_component [label = "3. Label (HTTPs)"];
+  node_in_cluster -> future_component [label = "9. Future Interface", style = dashed];
+  node_in_cluster -> thirdparty
+  db;
+  mq;
+}

security-threat-analysis/source/figures/arch_diagram.xml

@@ -0,0 +1 @@
+<mxfile type="device" userAgent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.111 Safari/537.36" version="5.2.8.6" editor="www.draw.io"><diagram>7VpNc+I4E/41VM0eQmEcSOYYMp9Vkym2MrX77uktYQvQjm2xshxgfv10yy1b/oAlAVykdjiA3ZJbcj9Pt1otev59vPmo2Gr5IEMe9YaDcNPz3/WGw7eja/hGwZYEAz8XLJQIc5FXCh7FD07CAUkzEfK00lFLGWmxqgoDmSQ80BUZU0quq93mMqqOumILO2IpeAxY1JT+KUK9zKW3w3Ep/8TFYmlH9sZv85YZC74vlMwSGq839OfmkzfHzOoyL+q/BxsqKUENXsWbex6hHa2Ncmt82NFaTFLxhCay/wFowgeeWJTRe95NP4PgLgh4muaNqd5aI8DDYG+4maRLtkJhEMkMdE3WS6H544oFKFwDA0C21HEEdx5c0jBcaU6EaJmqEdE8P3IZc6220IUeGBERiD/eNd2vSzQ8S5alg8SYZIwIsCg0l3aBCzJNu5mIqo6ZvsonBpI/HuDrK9drqb43rPUvNpmLKLqXkVRwn8gErRqydMlxTGw3nCnuIjbj0VSmQguZoOHBbBwenaBRBfD0S62Dljgei8SitfsdNcyk1jI+DUSFrQmj2yZEhT+7EPm24zEYUXxxMWIxB4kETxuk2SzdpprHz0WpRGFQB2gHgFOmwdRoW7DW4Pq1YHc7qvoXRY6Kf1l8XfCGgxOA5zU9bNiHe2MY+H3z6du36W/NeBRCjKZbqfRSLmTCoveltAafgyvfCP0/FPdHdPeXbUlg8k4T3mIbKviba72lxYllWoKoHPeLRNiceIfT2w8HvI3MlKEehipa15hacOp12w6a4hHT4qmq/RgAaGjH/vcyXgGpYboQ4YwnHeM4Lb5yAtL6gxpp7SLhktYS+dSLgtXr2Mx3ODuOYKxJKJ7gcoGXhsOPQOK8BdQ7jeegtr025C25bKhdIbZpOy+1DY+r1PYM5zrgNo3t4GQxSFcssQg0+V7g5HZ7DW5Q5EpduAGlueeOyuelJyUPLj2N6Ah2mkfvlGL4lO2wkiLReV7tmrfQf9hi2Qw8lXDjYDH+J8OtxAS4pa8on7jDtzAcKJpLcrt+0aInEgm/sgxCRV4fx66pcROv+yiDtEvt9KaDguGvHK01R/NvDszRTpFfe+ToDuve4nL3IdOZKqKlg+JntMgcMftPrnierVK4S95NR0ueT/n0iaNyw7zdm/DouHww30mHWxvB1AAKW9gL4yNWAAIb3y4/LSi22V2kBV6ztNSkZBLCAinXpo7E0lQEu7KB2xs3HyizgylXAqaGkbf08B3u/jIO0qxdCu7IWx2r2vzLNaqVPS+BiDdTTBlKUO3iT5jWocqnTs+4hb+amlqlxmq1avLXbah5SbLSrMt4uGw4q8OJdkyY49ScjKfiB5uZDkgIyr6g92jSG71DJQes4LEIQxMfTYowKcq51mHLgu4er6WyNE2mqMtW2We4ttOdrwb94Y0toxNuV6T+paSyXeR8ngK9j4Sawo0D9VTJMAtMxvSrTlqWsm3eVpyFNONyWwgp8r2jAnOz1POQwTnKlUhSzZIyXXN8zd0bvwEhi9FmpgnKf4c66AUsiaNaBt3pTjnP/iqWt8nzwLHw5Vut00TCTnfXbre6kZzhTnPP1vIdgxjM4AirqSKpFn32Mbk4/drChjg08eISYLIQEEzXLTCda3fYcpL4ACeIeKjatPTvGYdOB5paK/m9OHKFt3etanGINws8dO7PI7kOlkzpfigULLf/DwHuHeB0gcjYHlISIiN7VuI6jpWd3HGaZyonLhO1+J9b3PFVOAUstv0AFs7n1X+6rwq9iryhyqZOyz8+6Thnnfc5J2wVPF+4tWup+u7a3J28vNByXv1tKchj8B8Y+D+My0sFaplrt5lAc39xWXVvAyA0Wgz3HiP9CnEHhLgi7HQR4l7pIXjNJYdtf4w6kUvCbfnftLxCUP7Zz3//Ew==</diagram></mxfile>

security-threat-analysis/source/index.rst

@@ -0,0 +1,27 @@
+==================================
+OpenStack Security Threat Analysis
+==================================
+
+Abstract
+~~~~~~~~
+
+This is the index
+
+Contents
+~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   objectives.rst
+   threat-analysis-process.rst
+   templates/architecture-page.rst
+   architecture-diagram-guidance.rst
+   todo.rst
+   
+
+
+Search in this guide
+~~~~~~~~~~~~~~~~~~~~
+
+* :ref:`search`

security-threat-analysis/source/objectives.rst

@@ -0,0 +1,16 @@
+=======================================
+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/templates/architecture-page.rst

@@ -0,0 +1,215 @@
+=============================
+Architecture page template
+=============================
+
+Project name architecture - version/release
+===========================================
+
+**Status**: Draft/Ready for Review/Reviewed
+
+**Release**: Juno/Kilo/Liberty if applicable
+
+**Version**: 0.01 if applicable
+
+**Contacts**:
+
+- PTL: name - irc handle
+
+- Architect: name - irc handle
+
+- Security Reviewer: name - irc handle
+
+Project description and purpose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A brief description of the purpose of the project. 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.
+
+
+Primary users and use-cases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A short statement about the expected primary users of the implemented
+architecture, 'users' can either be actors or other services within OpenStack.
+
+For example:
+
+#. Administrators will use this tool to manage storage quotas
+#. Nova will fetch TLS certificates for nova-migrate
+#. IaaS services e.g cinder, neutron-lbaas and nova for encryption key
+   generation and storage.
+
+
+Differences from previous architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If this is a revision of a prior architecture, briefly list the new components
+and interfaces. If this is a new architecture that replaces a prior service,
+briefly describe how this service differs from its ancestor. If this is an
+entirely new service with no precedent, then state only "This is a new service
+with no related prior solution".
+
+For example:
+
+- New OpenStack service added in Liberty.
+
+
+External dependencies & 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, but may be operated by a
+third party.
+
+For example:
+
+- Nova compute service is configured in accordance with security best practice.
+- AWS object storage.
+
+
+Components
+~~~~~~~~~~
+
+In the component descriptions that follow, IC means that in a typical
+deployment,they reside in hosted instances on the cloud, and UC means they are
+likely to be in the under cloud infrastructure.
+
+- component-1 (optional product/technology name)[IC or UC]: Describe component
+- component-2 [IC]: Describe component
+- component-3 [UC]: Describe component
+
+For Example:
+
+- Worker Queue (rabbitmq) [UC]: This queue is used to process new order
+  requests. Other systems involved submit and receive data via this queue.
+- Database (MySQL) [IC or UC]: Open-source sql database to store Barbican state
+  data related to its managed entities and their metadata.
+
+
+Interfaces
+~~~~~~~~~~
+.. csv-table::
+   :header: "Interface","Network name","Network protocol","Requestor","Request","Request credentials","Request authorization","Listener","Response","Response credentials","Description of operation"
+
+   "1"
+   "2"
+   "3"
+
+
+Guidance:
+
+- Enter a component name in the Requestor and Listener columns.
+- Enter a data asset name in the Request and Response columns.
+- Do not use an interface to show a function call within the same process.
+- It is appropriate to show calls or effects which a process or library
+  makes outside of the process. For example, if the project is responsible for
+  part of a process, such as a library, do not list intra-process calls to that
+  library as separate interfaces. On the service architecture diagram you can
+  show the process and the library and color-code them to show the part(s) for
+  which the project has responsibility.
+- If a request uses mutual TLS authentication (using both a client and server
+  certificate) then it may be appropriate to list 'TLS Certificate' in the
+  'Request credentials field' for that interface, but otherwise TLS should not
+  be regarded as a credential. The following examples attempt to clarify this
+  for common situations:
+
+  - Over an HTTPS session a service sends a Keystone token to authenticate
+    itself. In this case the Request credential is the Keystone token and the
+    Network protocol is HTTPS.
+  - A service connects to a database using SQL with a username and password.
+    Customers have the option at installation time to set up TLS for this
+    connection but are not required to do so.  In this case list the most
+    secure available option in the interfaces table: the Network protocol is
+    "SQL with TLS" and the Request credentials are "username/password".
+
+
+Service architecture diagram
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Insert Service Architecture diagram here. For diagram requirements see
+Architecture Diagram guidance.
+
+
+Data assets
+~~~~~~~~~~~
+
+The following is the description of data assets used by this service. See the
+TODO Information Classification Handling Policy for an explanation of
+requirements associated with the Confidentiality and Availability labels.
+
+.. csv-table::
+  :header: "Data name","Confidentiality","Integrity","Availability","Description"
+
+
+  "System request","Confidential","High","Medium","Requests between OpenStack services"
+  "System reply","Confidential","High","Medium","Replies to System requests"
+  "Data type X","Confidential","High","High","Data in motion, not stored"
+  "Data type Y","Confidential","High","Medium","Parameters in config file."
+  "MySQL database","Confidential","High","High","Contains user preferences. Backup to Swift daily."
+
+
+
+Data flow diagram(s)
+~~~~~~~~~~~~~~~~~~~~
+
+Insert DFDs here. If you prefer to use sequence diagrams, then delete this
+section. Architecture documentation should have at least one DFD or sequence
+diagram.
+
+An example of a data flow diagram is shown below:
+
+.. image:: ../figures/Template_DFD.png
+
+
+Sequence diagram(s)
+~~~~~~~~~~~~~~~~~~~
+
+Insert sequence diagrams here. If you prefer to use DFDs, then delete this
+section. Architecture documentation should have at least one DFD or sequence
+diagram.
+
+An example of a sequence diagram is shown below:
+
+.. image:: ../figures/Template_Sequence-diagram.png
+
+
+Summary of controls **Delete this section??**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Summary of controls spanning multiple components and interfaces:
+
+- **Audit**: for example: SERVICENAME performs logging.  Logs are
+  collected by the centralized logging service.
+- **Authentication**:  for example: authentication via Keystone tokens
+  at APIs. Password authentication to MQ and DB.
+- **Authorization**: for example: OpenStack provides admin and
+  non-admin roles that are indicated in session tokens.  Processes run
+  at minimum privilege.  Processes run as unique user/group definitions
+  (servicename/servicename).  Appropriate filesystem controls prevent
+  other processes from accessing service’s files.  Security Groups
+  (or IPtables) ensure that no unneeded ports are open.  Security Groups
+  provide authorization controls between in-cloud components.  IPtables
+  and ACLs at the network perimeter and VLAN boundaries ensure that no
+  unneeded ports are open.
+- **Availability**:  for example: redundant hosts, clustered DB,
+  fail-over –or—This is not an HA process.  Throttle to prevent API
+  flooding.  Monitoring via centralized monitoring service.
+- **Confidentiality**: for example: Network connections over TLS.
+  Network separation via VLANs.  Data and config files protected via
+  filesystem controls. Unencrypted local traffic is bound to localhost.
+- **Integrity**: for example: Network connections over TLS. Network
+  separation via VLANs.  DB API integrity protected by SQL Alchemy. Data
+  and config files are protected by filesystem controls.  Unencrypted
+  local traffic is bound to localhost.
+
+
+Resources
+~~~~~~~~~
+
+- URL related to this project
+- URL related to this project
+- URL related to this project
+- URL related to this project

security-threat-analysis/source/threat-analysis-process.rst

@@ -0,0 +1,122 @@
+=======================
+Threat Analysis Process
+=======================
+
+This page documents the process for a Threat Analysis review, which consists of
+the following phases:
+
+- Preparing artifacts for review
+- Verifying readiness for a threat analysis review
+- Scheduling the threat analysis review
+- Running the threat analysis review
+- Follow-up from the threat analysis review
+
+Preparing artifacts for review
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Complete the architecture page. The architecture page describes the purpose
+  of the service, and captures the information that is required for an
+  effective threat analysis review. A template for the architecture page is
+  provided at <link> and there is guidance on diagraming at <link>. If further
+  help or advice is needed, please reach out to the Security Project via the
+  openstack-dev@lists.openstack.org mailing list, tagging your email
+  [security].
+- The architecture page should describe a best practice deployment. If a
+  reference architecture is available this may be a good example to use,
+  otherwise the page should describe a best practice deployment, rather than
+  the simplest possible deployment. Where reference architectures do not exist,
+  it is possible that the architecture drawn for the threat analysis process
+  can be used as a reference architecture.
+- The following information is required in the architecture page for review:
+
+  #. A brief description of the service, its purpose and intended usage.
+  #. A list of components in the architecture, their purpose, any sensitive
+     data they persist and protocols they expose.
+  #. External dependancies and security assumptions made about them.
+  #. An architecture block diagram.
+  #. Either a sequence diagram or a data flow diagram, describing common
+     operations of the service
+
+
+Before the review
+~~~~~~~~~~~~~~~~~
+
+- Verify that the service’s architecture page contains all the sections listed
+  in the Architecture Page Template <link>.
+- The architecture page should include diagrams as specified in the
+  Architecture Diagram guidance <link>.
+- Send an email to the openstack-dev@lists.openstack.org mailing list with a
+  [security] tag to announce the up-coming threat analysis review.
+- Prepare a threat analysis review etherpad, using this template <link>.
+- Print the architecture page as a PDF, to be checked in along with the review
+  notes, as evidence of what was reviewed.
+
+Running the threat analysis review
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Identify the “scribe” role, who will record the discussion and any findings
+  in the etherpad.
+- Ask the project architect to briefly describe the purpose of the service,
+  typical uses cases, who will use it and how it will be deployed. Identify the data assets that might be at risk, eg peoples photos, cat videos, databases. Assets in flight and at rest.
+- Briefly consider potential abuse cases, what might an attacker want to use
+  this service for? Could an attacker use this service as a stepping stone to
+  attack other services? Do not spend too long on this section, as abuse cases
+  will come up as the architecture is discussed.
+- Ask the project architect to summarize the architecture by stepping through
+  the architecture block diagram. While reviewing the architecture, perform the
+  following steps:
+
+  #. For each interface between components, consider the confidentiality,
+     integrity and availability requirements for that interface. Is
+     sensitive data protected effectively to prevent information disclosure
+     (loss of confidentiality) or tampering (loss of integrity)? Is there a
+     requirement for availability which should be documented and added to
+     reference deployments? In addition to considering the authenticity of
+     the data in transit, consider how the authenticity of the sending and
+     receiving nodes is assured.
+  #. Consider the protocols used to pass data between interfaces. Is this an
+     appropriate protocol, is it a current protocol, does it have documented
+     vulnerabilities, is the implementation in use maintained? Is this protocol
+     used as a security control to provide confidentiality, integrity or
+     availability?
+  #. Can this interface be used as an entry point to the system, can an attacker
+     use it to attack a potentially vulnerable service? If so, consider what
+     additional controls should be applied to limit the exposure.
+  #. If an attacker was able to compromise a given component, what would that
+     enable them to do? Could they stepping-stone through the OpenStack cloud?
+  #. How is the service administered? Is this a secure path, with appropriate
+     authentication and authorization controls?
+
+- Once the reviewers are familiar with the service, re-consider abuse cases, are
+  there any other cases which should be considered and mitigated?
+- Step through typical use-case diagrams. Again consider if sensitive data is
+  appropriately protected. Where an entry point is identified, consider how
+  risks of malicious input data can be mitigated.
+- If any potential vulnerabilities are identified, they should be discussed
+  with the project team, if they agree that it is an issue then a note should
+  be made in the findings section of the etherpad, with a short title and
+  summary of the issue, including a note of who found it. If the project team
+  disagree, then the note should be made under the further investigation
+  section.
+
+
+Follow-up from the threat analysis review
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Create a Master Bug for the TA review. The summary and description should
+  both say "Threat Analysis Review for [ServiceName]. Include the PTL,
+  Service Architect, Security Architect, and Architecture page link in the
+  description.
+- Create a separate bug for each of the security findings listed in the TA
+  Review notes.
+- Update the Threat Analysis Review Etherpad each of the new launchpad bug
+  numbers.
+- Paste the contents of the Threat Analysis Review Etherpad into a text file in
+  security-docs/security-ta/notes and push it to the security-review repo using
+  gerit.
+- Distribute the Threat Analysis Review Notes via email to all who were present
+  at the threat analysis. If anyone discovers errors or omissions in the notes,
+  then make corrections.
+- On the threat analysis reviews wiki page create a new row in the reviews
+  table, include a link to the master bug, the date of the review, the PTL and
+  reviewers.

security-threat-analysis/source/todo.rst

@@ -0,0 +1,16 @@
+===================
+Threat Analyis Todo
+===================
+
+Needed
+~~~~~~
+
+
+#. TA Calendar
+#. Wiki page saying what TAs have been done, and havent.
+#. Etherpad template for review tracking
+#. process
+
+
+Current Status
+~~~~~~~~~~~~~~

security-threat-analysis/templates/architecture-page.rst

@@ -0,0 +1,115 @@
+<Project Name> Architecture
+===========================
+
+**Contacts**:
+
+- PTL: <name> - <irc handle>
+
+- Architect: <name> - <irc handle>
+
+- Security Reviewer: <name> - <irc handle>
+
+Project Description and Purpose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+<Brief description of the purpose of the project; about a paragraph, can be cut/paste from wiki or other documentation. Include links to relevant presentations if available. Remove this comment>.
+
+
+Primary Users
+~~~~~~~~~~~~~
+
+<Short statement about the expected primary users of the implemented
+architecture. Remove this comment>.
+
+
+Differences from Previous Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+<If this is a revision of a prior architecture, briefly list the new
+components and interfaces>
+<If this is a new architecture that replaces a prior service, briefly
+describe how this service differs from its ancestor>
+<If this is an entirely new service with no precedent, then state only
+"This is a new service with no related prior solution".>
+
+
+Components
+~~~~~~~~~~
+
+In the component descriptions that follow, I-C means they reside in
+hosted instances on the cloud, and U-C means they are in the under
+cloud infrastructure.
+
+- <component-1 (I-C or U-C): <Describe component>
+
+- <component-2 (I-C): <Describe component>
+
+- <component-3 (U-C): <Describe component>
+
+
+Data
+~~~~
+
+The following is the description of data types used by this service.
+<See the <TODO> Information Classification Handling Policy for an
+explanation of requirements associated with the Confidentiality and
+Availability labels. Remove this comment>
+
+.. csv-table::
+   :header: "Data name","Confidentiality","Integrity","Availability","Description"
+
+
+   "System request","Confidential","High","Medium","Requests between OpenStack services"
+   "System reply","Confidential","High","Medium","Replies to System requests"
+   "Data type X","Confidential","High","High","Data in motion, not stored"
+   "Data type Y","Confidential","High","Medium","Parameters in config file."
+   "MySQL database","Confidential","High","High","Contains user preferences. Backup to Swift daily."
+
+
+Service Architecture Diagram
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+<Insert Service Architecture diagram here. For diagram requirements see
+Architecture Diagram Requirements. Remove this comment>
+
+
+Interfaces
+~~~~~~~~~~
+.. csv-table::
+   :header: "Interface","Network name","Network protocol","Requestor","Request","Request credentials","Request authorization","Listener","Response","Response credentials","Description of operation"
+
+   "1"
+   "2"
+   "3"
+
+Guidance:
+
+- Enter a component name in the Requestor and Listener columns.
+
+- Enter a data name in the Request and Response columns.  If a request
+uses unidirectional TLS authentication (which means that the client
+authenticates the server but the server does NOT authenticate the
+client) then TLS should not be listed in the "Request credentials"
+cell for the interface.  If a request uses bidirectional TLS
+authentication (which means that the server authenticates the client
+and the client authenticates the server) then it may be appropriate to
+list "TLS Certificate" in the "Request  credentials" cell for the
+interface but normally this is not the case.  The following examples
+attempt to clarify this for common situations:
+
+Over an HTTPS session a service sends a Keystone token to authenticate
+itself.  In this case the Request credential is the Keystone token and
+the Network protocol is HTTPS.
+A service connects to a database using SQL with a username and password.
+Customers have the option at installation time to set up TLS for this
+connection but are not required to do so.  In this case list the most
+secure available option in the interfaces table: the Network protocol is
+"SQL with TLS" and the Request credentials are "username/password"
+Do not use an interface to show a function call within the same process.
+It is appropriate to show calls or effects which a process or library
+makes outside of the process.  For example, if the project is
+responsible for part of a process, such as a library, do not list
+intra-process calls to that library as separate interfaces.  On the
+service architecture diagram you can show the process and the library
+and color-code them to show the part(s) for which the project has
+responsibility, like this: