diff --git a/doc/source/templates/architecture-page.rst b/doc/source/templates/architecture-page.rst index 085d0d0..cc6b798 100644 --- a/doc/source/templates/architecture-page.rst +++ b/doc/source/templates/architecture-page.rst @@ -4,7 +4,6 @@ Architecture page template Project name architecture - version/release ------------------------------------------- - **Status**: Draft/Ready for Review/Reviewed **Release**: Juno/Kilo/Liberty if applicable @@ -17,11 +16,11 @@ Project name architecture - version/release - Architect: name - irc handle +- Security Reviewer: 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. @@ -29,7 +28,6 @@ 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. @@ -41,19 +39,8 @@ For example: 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 or one that has not been reviewed -previously, then remove this section. - - 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 @@ -68,66 +55,20 @@ For example: Components ~~~~~~~~~~ - -In the component descriptions that follow, I-C means that in a typical -deployment, they reside in hosted instances on the cloud, and U-C means they -are likely to be in the under cloud infrastructure. O-C means they are outside -of the cloud. - -- component-1 (optional product/technology name)[I-C or U-C]: Describe - component -- component-2 [I-C]: Describe component -- component-3 [U-C]: Describe component -- component-3 [O-C]: Describe component or service +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: -- Worker Queue (rabbitmq) [U-C]: This queue is used to process new order - requests. Other systems involved submit and receive data via this queue. -- Database (MySQL) [I-C or U-C]: 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". +- 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Insert Service Architecture diagram here. For diagram requirements see Architecture Diagram guidance in the OpenStack Security Guide. @@ -136,75 +77,56 @@ Architecture Diagram guidance in the OpenStack Security Guide. Data assets ~~~~~~~~~~~ +Data assets are user data, high-value data, configuration items, authorization +tokens or other items that an attacker may target. Data assets should include a +statement of where that asset is persisted. -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" +For example: +- *ACL rules* - persisted in database +- *DB Credentials* - persisted in barbican.conf +- *Middleware configuration* - persisted in paste.ini +- *[PKCS#11] HSM HMAC Key* - persisted in HSM - "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 asset impact analysis +~~~~~~~~~~~~~~~~~~~~~~~~~~ +List all data assets listed above, briefly describe the impact to the system +that an integrity failure, loss of confidentiality or loss of availability +would have to the system. Project architects should attempt to complete this +prior to the review to minimise the time required. + +For example: + +Data Assets: +- *RBAC/ACL rulesets*: + + - Integrity Failure Impact: Attacker with valid AuthN could be granted access + to any secret. + - Confidentiality Failure Impact: Mappings between users and secrets are + exposed. + - Availability Failure Impact: barbican will not start if the file is not + readable. +Interfaces +~~~~~~~~~~ +List interfaces within the scope of the review: connections that cross a trust +boundary, connections that do not use a industry standard encryption protocol +such as TLS or SSH. Capture the following information for each interface: -Data flow diagram(s) -~~~~~~~~~~~~~~~~~~~~ +Number. From -> To *[Transport Protocol]* -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. +- Assets in flight: List all data assets traveling across the interface. +- Brief description of the impact of a successful attack on this interface. -An example of a data flow diagram is shown below: +For example: -.. image:: figures/template_dfd.png +1. Administrator->API Process *[TLS]*: - -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. + - Assets in flight: barbican admin keystone Credentials + - An attacker with access to the admin credentials can modify quotas, + expanding or reducing them for any user. This has potential availability + impact. Denial of Service. Resources @@ -213,4 +135,3 @@ Resources - URL related to this project - URL related to this project - URL related to this project -- URL related to this project