diff --git a/security-guide/source/figures/security_review_barbican_architecture.png b/security-guide/source/figures/security_review_barbican_architecture.png new file mode 100644 index 00000000..fc3d5dd9 Binary files /dev/null and b/security-guide/source/figures/security_review_barbican_architecture.png differ diff --git a/security-guide/source/index.rst b/security-guide/source/index.rst index 3678e41d..8b16f123 100644 --- a/security-guide/source/index.rst +++ b/security-guide/source/index.rst @@ -36,6 +36,7 @@ Contents instance-management.rst monitoring-logging.rst compliance.rst + security-review.rst Appendix ~~~~~~~~ diff --git a/security-guide/source/security-review.rst b/security-guide/source/security-review.rst new file mode 100644 index 00000000..17102945 --- /dev/null +++ b/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 +`__ +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 diff --git a/security-guide/source/security-review/architecture-page-guidance.rst b/security-guide/source/security-review/architecture-page-guidance.rst new file mode 100644 index 00000000..473f3bf2 --- /dev/null +++ b/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 `__ 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. diff --git a/security-threat-analysis/source/index.rst b/security-threat-analysis/source/index.rst index 493243c9..dd84ca4f 100644 --- a/security-threat-analysis/source/index.rst +++ b/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 diff --git a/security-threat-analysis/source/objectives.rst b/security-threat-analysis/source/objectives.rst deleted file mode 100644 index 5a78e2f7..00000000 --- a/security-threat-analysis/source/objectives.rst +++ /dev/null @@ -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 diff --git a/security-threat-analysis/source/todo.rst b/security-threat-analysis/source/todo.rst index 75fbf714..e23b909e 100644 --- a/security-threat-analysis/source/todo.rst +++ b/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.