From a27fa472d264e7522c04fa1f021db68d524151cf Mon Sep 17 00:00:00 2001 From: James Robinson Date: Wed, 5 Jul 2023 17:23:18 +0100 Subject: [PATCH 1/9] :memo: Run aspell over codebase --- docs/source/contributing/index.md | 10 +++++----- docs/source/contributing/walkthrough.md | 8 ++++---- docs/source/pillars/data_management.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index cefd0aa0..3f42bf05 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -55,7 +55,7 @@ This can be without discussion, however, it is best for substantial or significa We have opted to not use GitHub Discussions at this point. The community can suggest governance changes at any point. -This includes the SATRE team, and any decision must be openly documented in the repo. +This includes the SATRE team, and any decision must be openly documented in the repository. ::: ### Specification Format @@ -116,8 +116,8 @@ However, it makes the source and [diffs produced during the pull request](https: ### Linting and auto-formatting -We take advantage of pre-commit and related tools to help maintain consistent formatting within a repo, which improves review efficiency, and readability. -`pre-commit can be installed using pip: +We take advantage of `pre-commit` and related tools to help maintain consistent formatting within a repository, which improves review efficiency, and readability. +`pre-commit` can be installed using pip: ```sh pip install pre-commit @@ -134,7 +134,7 @@ See the [pre-commit](https://pre-commit.com/) documentation for more advanced us ## SATRE Team Contributions -SATRE team members are free to contribute to the repo in the same way as any contributor, following the process above. +SATRE team members are free to contribute to the repository in the same way as any contributor, following the process above. The SATRE team is also doing ongoing work to identify the key features of this specification. Some contributions by SATRE team members may represent the output of this work. Any contribution that represents this work will be explicitly mentioned in the contribution. @@ -143,7 +143,7 @@ This work is taking on two main forms: 1. Identifying what features the community feels are important for a TRE via the [features survey](https://dundee.onlinesurveys.ac.uk/satre-tre-operatorsbuilders-survey). We will synthesise responses from this survey to suggest features here. -1. Evaluating the TREs used in production as part of [the Alan Turing Institute DSH](https://github.com/alan-turing-institute/data-safe-haven), [Microsoft's Azure TRE](https://github.com/microsoft/AzureTRE), and the [TREEHOOSE TRE](https://github.com/HicResearch/TREEHOOSE/tree/v1.0.0-beta1). +1. Evaluating the TREs used in production as part of [the Alan Turing Institute Data Safe Haven](https://github.com/alan-turing-institute/data-safe-haven), [Microsoft's Azure TRE](https://github.com/microsoft/AzureTRE), and the [TREEHOOSE TRE](https://github.com/HicResearch/TREEHOOSE/tree/v1.0.0-beta1). The SATRE team will make recommendations for features of the specification based on similarities/differences across these three TRE provisions. (contributing-get-in-touch)= diff --git a/docs/source/contributing/walkthrough.md b/docs/source/contributing/walkthrough.md index 53f04007..1f6cbd9f 100644 --- a/docs/source/contributing/walkthrough.md +++ b/docs/source/contributing/walkthrough.md @@ -62,7 +62,7 @@ So you are still able to contribute via this method, though all direct changes w Below is a walkthrough of all the steps required to contribute via GitHub, from the very beginning. -This walkthrough is designed to give you the critical path steps to contributing directly to the Specification repo. +This walkthrough is designed to give you the critical path steps to contributing directly to the Specification repository. For a more broad, deeper introduction to GitHub, check out the Turing Way's [Introduction to GitHub Workshop](https://www.youtube.com/watch?v=Vcckl-2dASM), run at CarpentryCon22. 1. Go to the [GitHub homepage](https://github.com/) @@ -105,7 +105,7 @@ SATRE specification website #### Code -This is the default landing page of the repo, and contains all the code associated with the specification. +This is the default landing page of the repository, and contains all the code associated with the specification. The most important one for you to know about is where the actual specification is being written. ```{figure} ../../images/satre_specification_docs_directory.png @@ -251,7 +251,7 @@ Link to the main SATRE repository Update your fork of the SATRE repository ``` -1. **Edit the section you want to change.** Click on the `specification.md` file in the repo where you will be able to edit it: +1. **Edit the section you want to change.** Click on the `specification.md` file in the repository where you will be able to edit it: ```{figure} ../../images/github_edit_file.png :alt: Edit a file @@ -312,7 +312,7 @@ You will know you have the right setting when a tick appears next to your chosen ##### Notification streams You can also decide how you receive notifications - whether just on GitHub, or also via email. -We recommend receiving `Participating and @mentions` notifications by email too, to ensure you don't miss any conversation you're invovled in! +We recommend receiving `Participating and @mentions` notifications by email too, to ensure you don't miss any conversation you're involved in! 1. Click your profile in the top right corner of GitHub and select `Settings`. diff --git a/docs/source/pillars/data_management.md b/docs/source/pillars/data_management.md index f9b130f8..50f60d3c 100644 --- a/docs/source/pillars/data_management.md +++ b/docs/source/pillars/data_management.md @@ -153,7 +153,7 @@ _The ability to query and browse the data within an environment at various level ## Information security -This capability relates to the ability of the TRE organisation to protect against the unauthorized use of information, especially electronic data. +This capability relates to the ability of the TRE organisation to protect against the unauthorised use of information, especially electronic data. Measures taken to ensure information security can be further categorised into: From c1b8036fd196a3810578a748dfb3eb1a4f4f206d Mon Sep 17 00:00:00 2001 From: James Robinson Date: Wed, 5 Jul 2023 18:18:00 +0100 Subject: [PATCH 2/9] :recycle: Separate roles --- docs/source/index.md | 1 + docs/source/roles.md | 72 +++++++++++++++++++++++++++++++++++ docs/source/specification.md | 73 ------------------------------------ 3 files changed, 73 insertions(+), 73 deletions(-) create mode 100644 docs/source/roles.md diff --git a/docs/source/index.md b/docs/source/index.md index 10f15734..5b611d7c 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,6 +5,7 @@ :caption: Overview specification.md +roles.md ``` ```{toctree} diff --git a/docs/source/roles.md b/docs/source/roles.md new file mode 100644 index 00000000..69e1a0e1 --- /dev/null +++ b/docs/source/roles.md @@ -0,0 +1,72 @@ +(satre_roles)= + +# Roles + +A TRE conforming to the SATRE specification should provide a broadly similar experience for stakeholders operating in each of these defined roles. +There is not necessarily a one-to-one mapping between roles and people. +One person can have multiple roles. + +## TRE users + +The researchers working on projects that involve logging into a TRE to access data. + + + +```{list-table} +:header-rows: 1 +:name: tab-tre-role-user + +* - Role name + - Role description +* - + - +``` + +## TRE administration roles + +The IT and related professionals who will be responsible for deploying and managing instances of a TRE conforming to the SATRE specification. +These roles cover managing TRE computing infrastructure, but also administering the TRE itself (_e.g._ managing users and projects). + + + +```{list-table} +:header-rows: 1 +:name: tab-tre-role-administrator + +* - Role name + - Role description +* - + - +``` + +## TRE developer roles + +The software engineers responsible for developing and maintaining TRE software, including adding functionality, bug fixes and general maintenance. + + + +```{list-table} +:header-rows: 1 +:name: tab-tre-role-developer + +* - Role name + - Role description +* - + - +``` + +## TRE governance roles + +Roles that uphold the governance of TREs. +Such governance responsibilities typically involve establishing policies and procedures to ensure the responsible use of data, protecting the privacy and confidentiality of research participants, and promoting transparency and accountability in research activities. +Typical roles might include data custodians, ethicists, an independent board or a lay panel. + +```{list-table} +:header-rows: 1 +:name: tab-tre-role-governance + +* - Role name + - Role description +* - + - +``` diff --git a/docs/source/specification.md b/docs/source/specification.md index 4ea4c9e0..1463d576 100644 --- a/docs/source/specification.md +++ b/docs/source/specification.md @@ -95,76 +95,3 @@ SATRE Pillars Capability Map In addition to these capabilities, any organisation running a TRE (TRE organisation) will need to possess various {ref}`supporting capabilities `. Examples of supporting capabilities include complying with legal requirements and managing relationships with stakeholders. - -(satre_roles)= - -## Roles - -A TRE conforming to the SATRE specification should provide a broadly similar experience for stakeholders operating in each of these defined roles. -There is not necessarily a one-to-one mapping between roles and people. -One person can have multiple roles. - -### TRE users - -The researchers working on projects that involve logging into a TRE to access data. - - - -```{list-table} -:header-rows: 1 -:name: tab-tre-role-user - -* - Role name - - Role description -* - - - -``` - -### TRE administration roles - -The IT and related professionals who will be responsible for deploying and managing instances of a TRE conforming to the SATRE specification. -These roles cover managing TRE computing infrastructure, but also administering the TRE itself (_e.g._ managing users and projects). - - - -```{list-table} -:header-rows: 1 -:name: tab-tre-role-administrator - -* - Role name - - Role description -* - - - -``` - -### TRE developer roles - -The software engineers responsible for developing and maintaining TRE software, including adding functionality, bug fixes and general maintenance. - - - -```{list-table} -:header-rows: 1 -:name: tab-tre-role-developer - -* - Role name - - Role description -* - - - -``` - -### TRE governance roles - -Roles that uphold the governance of TREs. -Such governance responsibilities typically involve establishing policies and procedures to ensure the responsible use of data, protecting the privacy and confidentiality of research participants, and promoting transparency and accountability in research activities. -Typical roles might include data custodians, ethicists, an independent board or a lay panel. - -```{list-table} -:header-rows: 1 -:name: tab-tre-role-governance - -* - Role name - - Role description -* - - - -``` From ef99309b25c91366b40371119d24bde89c99db4c Mon Sep 17 00:00:00 2001 From: James Robinson Date: Wed, 5 Jul 2023 18:19:39 +0100 Subject: [PATCH 3/9] :memo: Standardise wording across all sections --- docs/source/index.md | 2 +- docs/source/pillars/computing_technology.md | 83 ++++++------ docs/source/pillars/data_management.md | 123 ++++++++++-------- docs/source/pillars/information_governance.md | 94 +++++++------ docs/source/pillars/supporting.md | 87 +++++++------ docs/source/specification.md | 33 ++--- 6 files changed, 224 insertions(+), 198 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index 5b611d7c..18f6a6ca 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -53,7 +53,7 @@ Personal or sensitive data which have been collected for operational, commercial TREs are designed to enable access to sensitive data only for authorised projects and researchers, whilst minimising risk of data release or exposure. Influential reports from DARE UK and Health Data Research UK, together with the UK Government Goldacre review and ‘Data Saves Lives’ policy paper, have all highlighted the need for change in how sensitive data are handled. -The SATRE team contains representatives from several existing UK TREs which are hosting a wide variety of data. +The SATRE team contains representatives from several existing UK TREs, which between them host many different types of sensitive data. We will use the reference architecture specified here to bring these into closer alignment and make it easy for others to do the same. This supports DARE UK's aim of developing a coordinated national data research infrastructure. diff --git a/docs/source/pillars/computing_technology.md b/docs/source/pillars/computing_technology.md index 0768ec8f..77ae6d51 100644 --- a/docs/source/pillars/computing_technology.md +++ b/docs/source/pillars/computing_technology.md @@ -2,7 +2,7 @@ # Computing technology -This capability concerns what the TRE organisation does to manage systems for storing, retrieving, analysing and sending information. +This capability concerns what the TRE operator does to manage systems for storing, retrieving, analysing and sending information. ```{figure} ../../images/Capability_Map/full.drawio.svg :alt: SATRE Pillars Capability Map @@ -15,7 +15,7 @@ SATRE Pillars Capability Map ## End user computing -_The ability of the TRE organisation to provide and manage devices, workspaces, interfaces and applications used by researchers to interact with underlying systems and data._ +_The ability of the TRE operator to provide and manage devices, workspaces, interfaces and applications used by researchers to interact with underlying systems and data._ ### User interface @@ -28,23 +28,23 @@ _The interfaces used for interacting with the TRE management system and the TRE * - Statement - Guidance - Importance -* - A TRE should be accessed via a user interface accessible using commonly available applications. +* - Your TRE should be accessed via a user interface accessible using commonly available applications. - TREs which allow users to connect from their own devices should not require the installation of any bespoke TRE application on the user's device. In practice a web browser is the most common way to achieve this. - Recommended -* - A TRE workspace should provide an environment familiar to the users of the TRE. +* - Your TRE workspace should provide an environment familiar to your users. - This may take the form of a virtual Windows or Linux desktops, non-desktop interfaces such as JupyterLab and other web applications, or a terminal. Bespoke TRE-specific software should be avoided when widely used alternatives already exist. - Recommended -* - A TRE should take accessibility for users with disabilities into account. +* - Your TRE should take accessibility for users with disabilities into account. - The restricted nature of TREs means many assistive tools such as screenreaders in a virtual desktop may not be allowed, but other options such as colour schemes, font sizes, and resizing user interface elements, should be supported. - Recommended -* - Copying out data via the system clipboard must be disabled. +* - You should disable the ability to copy data out of your TRE via the system clipboard. - A TRE user must not be able to copy sensitive data out of a workspace using the system clipboard. A TRE may allow user to paste text into a workspace. - - Mandatory + - Recommended * - A TRE could restrict data access from researchers entirely and provide an interface for submitting code. - - For example, the OpenSAFELY TRE platform for electronic health records provides an interface for researchers who have developed their analysis code with dummy data, to submit their code to be run with the real data, and results returned via a disclosure process, without the researcher ever seeing the data. + - For example, you might use a system where users submit jobs which run over the data and return results without allowing direct data acces. - Optional ``` @@ -59,34 +59,33 @@ _The tools used by researchers inside a TRE, such as programming languages, IDEs * - Statement - Guidance - Importance -* - A TRE must provide software applications that are relevant to working with the data in the TRE. +* - Your TRE must provide software applications that are relevant to working with the data in the TRE. - The tools provided will depend on the types of data in the TRE, and the expectations of users of the TRE. For users working in a TRE via a virtual desktop, this may include programming languages such as Python and R, integrated development environments, Jupyter notebooks, office type applications such as word processors and spreadsheets, command line tools, etc. TREs with non-desktop interfaces should similarly consider carefully which applications are best suited for the researchers needs when interacting with the data, for example "point and click" GUI tools for querying a database and generating plots of data. The set of tools should be reviewed regularly to ensure they are up to date. - Mandatory -* - A TRE should provide clear guidance on how to use software tools and work with data in the TRE. +* - Your TRE must provide clear guidance on how to use software tools and work with data in the TRE. - TREs that provide a virtual desktop environment for researchers to work in should provide documentation detailing the available tools. TREs where the analysis code is developed on the access machine (as opppose to within the TRE) should provide documentation detailing the mechanism by which code is submitted to the TRE. - Mandatory -* - A TRE should provide tools to encourage best-practice in reproducibly analysing data. +* - Your TRE should provide tools to encourage best-practice in reproducibly analysing data. - Reproducibility of analyses improves auditability and accountability of how data has been used, as well as being best-practice in research. This may include version control software, and tools for developing and running data analysis pipelines. - Recommended -* - Where possible, the TRE should automatically apply security related updates for user software. - - TRE users will benefit from the latest versions of software being installed on the TRE, to maximise the functionality at their disposal, and the security of the TRE will also be maintained by reducing the risk of expoitable vulnerabilities in installed software. +* - Your TRE should, where possible, automatically apply security related updates for user software. + - Reducing the risk of expoitable vulnerabilities in installed software will increase the security of your TRE. - Recommended -* - A TRE may provide shared services that are accessible to users in the same project. +* - Your TRE could provide shared services that are accessible to users in the same project. - This may include shared file storage, databases, collaborative writing, and other web applications. This must only be shared amongst users within the same project. - Optional -* - A TRE may provide limited access to some public software repositories or container registries. +* - Your TRE could provide limited access to some public software repositories or container registries. - For example, a TRE may allow installation of packages from Python or R repositories, or provide an internal mirror with approved packages. Similarly a subset of public containers could be made available, or individual container images via an internal container registry. - Optional - -* - A TRE may include licenced commercial software if required by researchers, but additional risks must be recorded and mitigated where neccesary - - For example, if an application must connect to an external licensing server TREs must be confident that only licensing information is sent to this server, and that any network proxies to allow this are secured. +* - Your TRE could include licenced commercial software if required by researchers, but additional risks must be recorded and mitigated where neccesary. + - For example, if an application must connect to an external licensing server TREs must be confident that only licensing information is sent to this server, and that any network proxies to allow this are secured. - Optional ``` @@ -101,29 +100,29 @@ _The ability to run analyses requiring more compute resources, or more specialis * - Statement - Guidance - Importance -* - A TRE should be able to provide access to high performance computing or other scaleable compute resource if required by users. +* - Your TRE should be able to provide access to high performance computing or other scaleable compute resource if required by users. - If a TRE supports users conducting computationally intensive research it should provide access to dynamically scaleable compute or the equivalent. For example this may be in the form of a batch scheduler on a HPC cluster, or a dynamically created compute nodes on a cloud platform. - Recommended -* - A TRE should be able to provide access to accelerators such as GPUs if required by users. +* - Your TRE should be able to provide access to accelerators such as GPUs if required by users. - GPUs and other accelerators are commonly used in machine learning and other computationally intensive research. TREs should make it clear to users whether GPUs and other resources are available whilst projects are being assessed. - Recommended -* - Segregation of users and data must be maintained when using non-standard compute. +* - Your TRE must maintain segregation of users and data from different projects when using non-standard compute. - High performance or specialist compute is often shared amongst multiple users. Users and data must remain segregated at all times. - For example, when using physical compute resources all sensitive data must be securely wiped before another user is given access to that same node. - In a cloud hosted TRE virtual machines should be destroyed and recreated. + For example, when using physical compute resources, all sensitive data could be securely wiped before another user is given access to that same node. + In a cloud hosted TRE virtual machines could be destroyed and recreated. - Mandatory -* - A TRE may make data available to researchers using common databases such as PostgreSQL, MSSQL or MongoDB. +* - Your TRE could make data available to researchers using common databases such as PostgreSQL, MSSQL or MongoDB. - Databases must be secured and only accessible to users within the same project. If shared (multi-tenant) database servers are used, database administrators must ensure that the database server enforces segregation of users and databases belonging to different projects. - Optional -* - TREs working with big datasets could integrate with large-scale data analytics tools. +* - Your TRE could integrate with large-scale data analytics tools for working with large datasets. - For example, Spark and Hadoop can be used for distributed computing across a cluster. This may be an advantage where a TRE is using an amount of data that is too large for single-machine computing to be practical. - Optional -* - TREs integrating with cloud-native managed services should consider the associated risks. +* - Your TRE could integrate with cloud-native managed services. - Cloud providers supply many different managed services. Although the cloud provider is responsible for managing the configuration of these services, the TRE operator must ensure that using them does not compromise the security of the TRE. - Optional @@ -131,7 +130,7 @@ _The ability to run analyses requiring more compute resources, or more specialis ## Infrastructure analytics -_The ability of the TRE organisation to record and analyse data about the usage of the TRE._ +_The ability of the TRE operator to record and analyse data about the usage of the TRE._ ```{list-table} :header-rows: 1 @@ -140,20 +139,20 @@ _The ability of the TRE organisation to record and analyse data about the usage * - Statement - Guidance - Importance -* - A TRE must record usage of the TRE. +* - Your TRE must record usage data. - This may include the number of users, number of projects, the amount of data stored, number of datasets, the number of workspaces, etc. - Mandatory -* - A TRE should record which datasets are accessed, and when - - This helps auditability of how sensitive data has been used +* - Your TRE should record which datasets are accessed, when and by who. + - This helps maintain auditability of how sensitive data has been used - Recommended -* - A TRE should record computational resource usage at the user or aggregate level +* - Your TRE should record computational resource usage at the user or aggregate level. - This is useful for optimising allocation of resources, and managing costs. - Recommended ``` ## Network management -_The ability of the TRE organisation to administer and secure network infrastructure using applications, tools and processes._ +_The ability of the TRE operator to administer and secure network infrastructure using applications, tools and processes._ ```{list-table} :header-rows: 1 @@ -162,28 +161,28 @@ _The ability of the TRE organisation to administer and secure network infrastruc * - Statement - Guidance - Importance -* - Networks must be managed and controlled to protect information in systems and applications +* - Your TRE must control and manage any internal and external network infrastructure in order to protect information in systems and applications. - Network infrastructure must prevent unauthorised access to resources on the network. This may include firewalls, network segmentation, and restricting connections to the network. - Mandatory -* - Networks must be continually monitored for misconfigurations and vulnerabilities +* - You must monitor the network configuration of your TRE to check for misconfigurations and vulnerabilities. - This may include regular vulnerability scanning, and penetration testing. - Mandatory -* - Connectivity between users in different projects, or with access to different datasets, must not be allowed. +* - Your TRE must not allow connectivity between users in different projects, or with access to different datasets. - Connectivity between users in the same project may be allowed, for example to support shared network services within the project. - Mandatory -* - Outbound connections to the internet must be blocked by default. +* - Your TRE must block outbound connections to the internet by default. - Limited outbound connectivity may be allowed for some services. - Mandatory ``` ## Infrastructure lifecycle management -_The ability of the TRE organisation to manage necessary physical or virtual infrastructure._ +_The ability of the TRE operator to manage necessary physical or virtual infrastructure._ ### Deployment management -_The ability of the TRE organisation to instantiate, deploy, change or remove deployed infrastructure._ +_The ability of the TRE operator to instantiate, deploy, change or remove deployed infrastructure._ ```{list-table} :header-rows: 1 @@ -195,7 +194,7 @@ _The ability of the TRE organisation to instantiate, deploy, change or remove de * - You must have a documented procedure for deploying infrastructure. - This might, for instance, be a handbook that is followed or a set of automated scripts. - Mandatory -* - Where possible, you should automate any repeatable aspects of your deployment. +* - You should, where possible, automate any repeatable aspects of your deployment. - This might involve using infrastructure-as-code tools or simply a series of scripts. - Recommended * - You must have a documented procedure for making changes to deployed infrastructure. @@ -215,7 +214,7 @@ _The ability of the TRE organisation to instantiate, deploy, change or remove de ### Capacity management -_The ability of the TRE organisation to ensure the right amount of resources are available at the right time to provide a service._ +_The ability of the TRE operator to ensure the right amount of resources are available at the right time to provide a service._ ```{list-table} :header-rows: 1 @@ -245,7 +244,7 @@ _The ability of the TRE organisation to ensure the right amount of resources are ### Configuration management -_The ability of the TRE organisation to identify, maintain, and verify information on IT assets and configurations in the TRE organisation._ +_The ability of the TRE operator to identify, maintain, and verify information on IT assets and configurations in the TRE operator._ ```{list-table} :header-rows: 1 @@ -276,7 +275,7 @@ _The ability of the TRE organisation to identify, maintain, and verify informati ## Availability management -_The ability of the TRE organisation to ensure all IT infrastructure, processes, tools, roles etc are appropriate for the agreed availability targets._ +_The ability of the TRE operator to ensure all IT infrastructure, processes, tools, roles etc are appropriate for the agreed availability targets._ ```{list-table} :header-rows: 1 diff --git a/docs/source/pillars/data_management.md b/docs/source/pillars/data_management.md index 50f60d3c..aff44fec 100644 --- a/docs/source/pillars/data_management.md +++ b/docs/source/pillars/data_management.md @@ -2,7 +2,7 @@ # Data management -This capability concerns the ability of the TRE organisation to manage data assets and ensure information remains secure. +This capability concerns the ability of the TRE operator to manage data assets and ensure information remains secure. ```{figure} ../../images/Capability_Map/full.drawio.svg :alt: SATRE Pillars Capability Map @@ -15,7 +15,7 @@ SATRE Pillars Capability Map ## Data lifecycle management -_The ability of the TRE organisation to manage how and where data is stored, how it moves, changes and is removed._ +_The ability of the TRE operator to manage how and where data is stored, how it moves, changes and is removed._ ```{list-table} :header-rows: 1 @@ -24,45 +24,45 @@ _The ability of the TRE organisation to manage how and where data is stored, how * - Statement - Guidance - Importance -* - A TRE must have processes in place to assess the legal and regulatory implications of handling the data through its full lifecycle. +* - You must have processes in place to assess the legal and regulatory implications of handling the data through its full lifecycle. - This involves considering your obligations to data controllers and subjects, and whether any security controls may be legally or contractually required. An assessment of the risks involved will also be needed. It may involve classifying the project into a predefined sensitivity category or defining bespoke controls. - Mandatory -* - A TRE should keep records of data handling decisions. +* - You should keep records of data handling decisions. - Decisions that are made as part of the process discussed above should be recorded and made available for inspection by all stakeholders. - Recommended -* - A TRE must have a data ingress process which enforces information governance rules/processes. +* - You must have a data ingress process which enforces information governance rules/processes. - The data ingress process needs to ensure that information governance is correctly followed. In particular, it should require that an ingress request has been approved by all required parties. - Mandatory -* - A TRE must have a data egress process which enforces information governance rules/processes. +* - You must have a data egress process which enforces information governance rules/processes. - The data egress process needs to ensure that information governance requirements are adhered to. In particular, it should require that an egress request has been approved by all required parties. - Mandatory -* - A TRE's data egress process could sometimes require project-independent approval. - - There may be cases where there are multiple stakeholders for a piece of analysis including data providers, data analysts, data subjects, the TRE organisation. - A data egress process may then require approval from people not on the project team, for example an external referee or TRE organisation representative +* - Your data egress process could sometimes require project-independent approval. + - There may be cases where there are multiple stakeholders for a piece of analysis including data providers, data analysts, data subjects, the TRE operator. + A data egress process may then require approval from people not on the project team, for example an external referee or TRE operator representative - Optional -* - A TRE must keep a record of what data it holds. +* - You must keep a record of what data it holds. - Good records are important for ensuring compliance with legislation, understanding risk and aiding good data hygiene. The record should include a description of the data, its source, contact details for the data owner, which projects use the data, the date it was received, when it is expected to no longer be needed. - Mandatory -* - A TRE must have a policy on data deletion. +* - You must have a policy on data deletion. - There should be a clear, published policy on when data will be retained or deleted. This may allow time for data owners to consider outputs they may want to extract from the TRE. Any sensitive data, including all backups, should be deleted when they are no longer needed. Having clear policies will help to avoid problems with data being kept longer than necessary or accidental deletion of outputs. - Mandatory -* - A TRE could keep backups of data and research environments, provided that this is permitted by law. +* - You could keep backups of data and research environments, provided that this is permitted by law. - Keeping backups could help reduce the impact of events like accidental deletion and data corruption on work in a TRE. TRE developers may want to consider how different elements, for example sensitive input data or users workspaces, may be backed up or if they should be. - Optional -* - A TRE should log how input data is modified. +* - You should log how input data is modified. - If the input data is mutable a TRE should keep records of its modification. For example, when the data was modified and by who. - Recommended -* - A TRE must, to a reasonable extent, prevent unauthorised data ingress or egress +* - You must, to a reasonable extent, prevent unauthorised data ingress or egress. - Movement of data which has not been subject to information governance processes risks breaking rules and is more likely to result in a data breach. However, it is difficult to control for every possibility. For example, a user may take pictures of their computer screen to remove data, or use a device presenting as a USB HID keyboard to input large amounts of text. @@ -72,7 +72,7 @@ _The ability of the TRE organisation to manage how and where data is stored, how ## Identity and access management -_The ability of the TRE organisation to ensure the right people (identities) can access the tools and data they need and no more._ +_The ability of the TRE operator to ensure the right people (identities) can access the tools and data they need and no more._ ```{list-table} :header-rows: 1 @@ -81,27 +81,27 @@ _The ability of the TRE organisation to ensure the right people (identities) can * - Statement - Guidance - Importance -* - A TRE must not create user accounts for use by more than one person. +* - You must not create user accounts for use by more than one person. - It is important that each user account should be used by one, and only one, person in order to facilitate the assignment of roles or permissions and to log the actions of individuals. - Mandatory -* - A TRE must be reasonably convinced of the identity of the person being granted an account. +* - You must be reasonably convinced of the identity of each person being granted an account. - It is important to ensure access, via an account, has been given to the correct person. For example, multiple credentials may be used before account creation to verify identity or, when appropriate, photo ID checks may be required. - Mandatory -* - A TRE must restrict a users access to only data required in their work. +* - You must restrict a user's access to only data required in their work. - There is no need to grant an individual access to data they do not require. Access may be assigned in a manner appropriate to a TREs design, for example through roles granted to user accounts or through isolated project workspaces. - Mandatory -* - A TRE must ensure multi-factor authentication for users. +* - You must ensure that multi-factor authentication is enabled for all users. - Multi-factor authentication ensures that to successfully connect a user must have more than one piece of evidence in different categories. Categories include something the user knows (_e.g._ a password), something the user possesses (_e.g._ a TOTP key) or something the user is (_e.g._ biometric data). A TRE does not need to implement multi-factor authentication checks itself if it is provided by a third-party identity provider. - Mandatory -* - A TRE could use federated authentication/ single sign-on (SSO) for user login. +* - You could use federated authentication/ single sign-on (SSO) for user login. - Institutions that use a SSO for other applications may wish to extend this login capability to a TRE. This will simplify the login process for researchers using a TRE and prevent them having to remember or store multiple login credentials. - Optional -* - A TRE could restrict access to particular locations. +* - You could restrict access to particular networks or physical locations. - Restricting access to a set of known, static, personal or institutional IP addresses can help avoid speculative attacks. When appropriate, access could also be restricted to physical locations with security controls and access requirements. - Optional @@ -109,7 +109,7 @@ _The ability of the TRE organisation to ensure the right people (identities) can ## Output management -_The ability of the TRE organisation to ensure outputs are safely published and shared._ +_The ability of the TRE operator to ensure outputs are safely published and shared._ ```{list-table} :header-rows: 1 @@ -118,12 +118,12 @@ _The ability of the TRE organisation to ensure outputs are safely published and * - Statement - Guidance - Importance -* - A TRE should have a system to aid classifying outputs. +* - You should have a system to aid in classifying outputs. - Removing data from a TRE can be a difficult process as there is potential for sensitive data to be revealed. Having guidance, processes and methods will help ensure that outputs are correctly classified and, furthermore, that outputs due to be openly published are identified. Encouraging openly published outputs rather than handing all outputs to the data provider will enhance a TRE's impact. - Recommended -* - A TRE should establish each project's intended outputs from the outset. +* - You should establish the intended outputs of each project from the outset. - Identifying the purpose of a piece of work is important for compliance with data protection legislation. Results will be produced which address the project's purpose, some of which may be outputs that are removed from the TRE. Understanding what these outputs are likely to be and their sensitivity as early as possible will help prepare for their processing and publication. @@ -143,7 +143,7 @@ _The ability to query and browse the data within an environment at various level * - Statement - Guidance - Importance -* - TRE operators could make a catalogue of sensitive data that they hold available to users +* - You could make a catalogue of sensitive data that you make available to users. - This is particularly relevant for TREs that are an interface to a common data collection. This may not be appropriate for TREs where each project has its own data sharing agreement with one or more data providers. - Optional @@ -153,7 +153,7 @@ _The ability to query and browse the data within an environment at various level ## Information security -This capability relates to the ability of the TRE organisation to protect against the unauthorised use of information, especially electronic data. +This capability relates to the ability of the TRE operator to protect against the unauthorised use of information, especially electronic data. Measures taken to ensure information security can be further categorised into: @@ -169,7 +169,7 @@ These measures include vulnerability management of TRE infrastructure (whether p ### Vulnerability management -_The ability of the TRE organisation to identify, assess, report on, manage and remediate technical vulnerabilities across endpoints, workloads, and systems._ +_The ability of the TRE operator to identify, assess, report on, manage and remediate technical vulnerabilities across endpoints, workloads, and systems._ ```{list-table} :header-rows: 1 @@ -178,17 +178,20 @@ _The ability of the TRE organisation to identify, assess, report on, manage and * - Statement - Guidance - Importance -* - All computing infrastructure belonging to the TRE should be kept up-to-date with security patches and antivirus (if appropriate) - - This might involve scheduling regular automated scanning and application of updates. Infrastructure that is isolated from the internet or immutable in some way may not need to be updated. +* - You should keep all TRE computing infrastructure up-to-date with security patches and antivirus (if appropriate). + - This might involve scheduling regular automated scanning and application of updates. + Infrastructure that is isolated from the internet or immutable in some way may not need to be updated. - Recommended -* - Regular vulnerability scans of TRE infrastructure should be conducted +* - You should conduct regular vulnerability scans of TRE infrastructure. - Ensuring that scans are done on a regular basis can enable TRE operators can identify and address weaknesses that may have been introduced during the operational lifetime of the TRE. - Recommended -* - TREs should regularly check the compliance of machine and resource configurations - - This might involve automated "desired state" enforcement, manual checks or checks over what is possible, for example ensuring that only certain network connections are allowed. +* - You should regularly check the compliance of machine and resource configurations. + - This might involve automated "desired state" enforcement or manual checks. + It might also include checks over what actions are possible, for example, whether or not certain network connections are allowed. - Recommended -* - TREs should adhere to one or more external security standards - - The TRE organisation should identify appropriate security standards and best practices that it will adhere too. These should be stated to all stakeholders in advance of any data being brought in to the TRE. +* - Your TRE should adhere to one or more external security standards. + - The TRE operator should identify appropriate security standards and best practices that it will adhere too. + These should be stated to all stakeholders in advance of any data being brought in to the TRE. - Recommended ``` @@ -196,7 +199,7 @@ _The ability of the TRE organisation to identify, assess, report on, manage and ### Security testing -_Security testing enables the TRE organisation to gain assurance in the security of a TRE by testing or attempting to breach some or all of that system's security._ +_Security testing enables the TRE operator to gain assurance in the security of a TRE by testing or attempting to breach some or all of that system's security._ ```{list-table} :header-rows: 1 @@ -205,17 +208,20 @@ _Security testing enables the TRE organisation to gain assurance in the security * - Statement - Guidance - Importance -* - Penetration tests should be carried out on TREs - - By intentionally attempting to breach their TRE, organisations can proactively discover unnoticed vulnerabilities before they are exploited maliciously. Tests can evaluate the effectiveness of security controls in preventing data breaches, unauthorised access, or other security incidents +* - You should carry out penetration tests on your TRE. + - By intentionally attempting to breach their TRE, organisations can proactively discover unnoticed vulnerabilities before they are exploited maliciously. Tests can evaluate the effectiveness of security controls in preventing data breaches, unauthorised access, or other security incidents. - Recommended -* - TRE security controls should be updated based on the results of security tests - - Security testing can reveal bugs and discrepancies in the TRE architecture which should be addressed in advance of sensitive data being uploaded, or with urgency in the case of an operational TRE. Regular testing will allow organisations to refine their TRE security controls and incident response capabilities, enabling them to adapt to any new security concerns that may arise as a result of changes in the underlying software. +* - You should update the security controls of your TRE based on the results of security tests. + - Security testing can reveal bugs and discrepancies in the TRE architecture which should be addressed in advance of sensitive data being uploaded, or with urgency in the case of an operational TRE. + Regular testing will allow organisations to refine their TRE security controls and incident response capabilities, enabling them to adapt to any new security concerns that may arise as a result of changes in the underlying software. - Recommended -* - TRE operators must have procedures in place for rapid incident response - - There may well be legal requirements to disclose details of any incidents, _e.g._ data breaches for organisations subject to GDPR. Having robust processes in place will ensure a swift and effective response when an incident occurs. +* - You must have procedures in place for rapid incident response. + - There may well be legal requirements to disclose details of any incidents, _e.g._ data breaches for organisations subject to GDPR. + Having robust processes in place will ensure a swift and effective response when an incident occurs. - Mandatory -* - TREs should publish details of their security testing strategy and positive results or outcomes (e.g. security fixes) resulting from the testing +* - You should publish details of your security testing strategy and, where possible, the results of each test. - Knowledge that regular security testing occurs will help to ensure stakeholders, including researchers and data providers, can trust that the data they work with or are responsible for is secure within a TRE. + If security flaws are identified in a test, it may not be sensible to publicise these until a fix is in place. - Recommended ``` @@ -223,7 +229,7 @@ _Security testing enables the TRE organisation to gain assurance in the security ### Encryption -_The ability of the TRE organisation to deploy and manage encryption to protect information assets, including data for TRE research projects._ +_The ability of the TRE operator to deploy and manage encryption to protect information assets, including data for TRE research projects._ Here we define 'project' data as the data brought in for work which is very likely to be sensitive and 'user' data, as the working files of a project which might hold copies of all or part of the project data or otherwise reveal sensitive data (_e.g._ through hard coded row/column names). @@ -234,19 +240,23 @@ Here we define 'project' data as the data brought in for work which is very like * - Statement - Guidance - Importance -* - TREs must encrypt project and user data at rest - - This prevents unauthorised access to the data even if the storage media is compromised. This may involve encrypted filesystems or tools to encrypt and decrypt data on demand. The encryption keys may be managed by the TRE organisation or by a trusted external actor (_e.g._ a cloud services provider). +* - Your TRE must encrypt project and user data at rest. + - This prevents unauthorised access to the data even if the storage media is compromised. + This may involve encrypted filesystems or tools to encrypt and decrypt data on demand. + The encryption keys may be managed by the TRE operator or by a trusted external actor (_e.g._ a cloud services provider). - Mandatory -* - TREs must encrypt data when in transit between the TRE and the outside world - - Data encryption must be used to safeguard against interception or tampering during transmission. This includes both data ingress and egress and users accessing the TRE, for example over a remote desktop or shell session +* - Your TRE must encrypt data when in transit between the TRE and the outside world. + - Data encryption must be used to safeguard against interception or tampering during transmission. + This includes both data ingress and egress and users accessing the TRE, for example over a remote desktop or shell session. - Mandatory -* - TREs should encrypt data when in transit inside the TRE - - If possible, data transfers between different components of a TRE should also be encrypted +* - Your TRE should encrypt data when in transit inside the TRE. + - If possible, data transfers between different components of a TRE should also be encrypted. - Recommended -* - Encryption software should be updated - - The latest security patches and updates should be applied to any encryption software being used by the TRE. This helps address any known vulnerabilities or weaknesses in the encryption implementation. +* - You should use the latest stable version of any software you use for encryption. + - The latest security patches and updates should be applied to any encryption software being used by the TRE. + This helps address any known vulnerabilities or weaknesses in the encryption implementation. - Recommended -* - TREs should use secure key management +* - Your TRE should use secure key management. - TREs should employ secure key management practices, including storing encryption keys separately from the encrypted data and implementing strong access controls (_e.g._ Single Sign On) for key management systems. - Recommended ``` @@ -255,7 +265,7 @@ Here we define 'project' data as the data brought in for work which is very like ### Physical security -_The ability of the TRE organisation to manage and protect physical assets from unauthorised access, damage or destruction._ +_The ability of the TRE operator to manage and protect physical assets from unauthorised access, damage or destruction._ Physical security controls can provide TREs using highly sensitive data an extra layer of security, even if technical controls are already in place for less sensitive data: @@ -266,10 +276,11 @@ Physical security controls can provide TREs using highly sensitive data an extra * - Statement - Guidance - Importance -* - TREs could offer physical protection measures against data leakage or theft via physical means +* - Your TRE could offer physical protection measures against data leakage or theft via physical means. - Restricting access to research facilities containing computers logged into TREs can help prevent malicious actors from viewing or stealing sensitive data, for example by photographing a computer screen. Physical controls on access to a TRE could include surveillance systems, restricting access to locked rooms that limit entry to authorised personnel only, visitor management systems and employee training. - Optional -* - TREs hosting particularly sensitive data may need to comply with specific regulatory requirements - - Regulatory frameworks such as GDPR emphasise the need for physical security controls to protect sensitive data. Compliance with these regulations could require organisations to implement specific physical security measures to safeguard their TRE from unauthorised access. +* - Your TRE may need to comply with specific regulatory requirements if it is hosting particularly sensitive data. + - Regulatory frameworks such as GDPR emphasise the need for physical security controls to protect sensitive data. + Compliance with these regulations could require organisations to implement specific physical security measures to safeguard their TRE from unauthorised access. - Optional ``` diff --git a/docs/source/pillars/information_governance.md b/docs/source/pillars/information_governance.md index 5f1db034..53b845c5 100644 --- a/docs/source/pillars/information_governance.md +++ b/docs/source/pillars/information_governance.md @@ -2,7 +2,7 @@ # Information governance -This pillar concerns what the TRE organisation does to ensure information risk is measured and managed to an acceptable level. +This pillar concerns what the TRE operator does to ensure information risk is measured and managed to an acceptable level. ```{figure} ../../images/Capability_Map/full.drawio.svg :alt: SATRE Pillars Capability Map @@ -15,7 +15,7 @@ SATRE Pillars Capability Map ## Policy regulation and management -_How the TRE organisation determines what policies and regulations are required and ensures alignment to changes in requirements._ +_How a TRE operator determines what policies and regulations are required and ensures alignment to changes in requirements._ ```{list-table} :header-rows: 1 @@ -24,17 +24,17 @@ _How the TRE organisation determines what policies and regulations are required * - Statement - Guidance - Importance -* - You have a process in place to ensure any new project requiring a TRE meets relevant legal, ethical and contractual requirements - - For example national legislation such as GDPR, discipline specific regulation like GCP or contractural requirements from a specific data provider such as a company or research partner organisation +* - You must have a process in place to ensure any new project requiring a TRE meets relevant legal, ethical and contractual requirements. + - For example national legislation such as GDPR, discipline specific regulation like GCP or contractural requirements from a specific data provider such as a company or research partner organisation. - Mandatory -* - You have a process in place to monitor changes to any legal, ethical and contractual requirements, and to update your policies accordingly +* - You must have a process in place to monitor changes to any legal, ethical and contractual requirements, and to update your policies accordingly. - - Mandatory ``` ## Quality management -_The ability of the TRE organisation to measure and control quality of processes, documentation and outputs._ +_The ability of a TRE operator to measure and control quality of processes, documentation and outputs._ ### Document management @@ -45,16 +45,21 @@ _The ability of the TRE organisation to measure and control quality of processes * - Statement - Guidance - Importance -* - All policies & standard operating procedures relevant to the TRE organisation are controlled - - This may include measures like restricting edit access to relevant documents, and recording acceptance of policies for all TRE organisation members +* - You must control all of your policies and standard operating procedures. + - This may include measures like restricting edit access to relevant documents, and recording acceptance of policies for all TRE operators - Mandatory -* - All policies & standard operating procedures relevant to the TRE organisation are version controlled and have codified change processes +* - You should use codified change processes when altering your policies and standard operating procedures. + - + - Recommended +* - You could use version control to track changes to their policies and processes. - Version control includes recording dates of changes, person responsible for carrying out changes, and summary of changes - - Mandatory + - Optional ``` ### Issue management +_The ability of a TRE operator to track deviations from stated policies._ + ```{list-table} :header-rows: 1 :name: tab-issue-management @@ -62,10 +67,10 @@ _The ability of the TRE organisation to measure and control quality of processes * - Statement - Guidance - Importance -* - You have a clear process in place for addressing activity within your TRE organisation that deviates from your policies and standard operating procedures +* - You must have a clear process in place for addressing any activity that deviates from your policies and standard operating procedures - This can include measures like triage analysis and a process for updating policies - Mandatory -* - You have methods in place to record progress in resolving issues with, and deviations against, your policies +* - You must have methods in place to record progress in resolving issues with, and deviations against, your policies - - Mandatory ``` @@ -80,12 +85,12 @@ _The ability of the TRE organisation to monitor compliance with internal and ext * - Statement - Guidance - Importance -* - You are able to audit your TRE organisation against relevant requirements and standards +* - You must be able to audit your TRE organisation against whichever external standards are relevant to you. - If you are publicly accredited against a standard, for instance ISO27001, DSPT, CE+ etc., you must have processes in place to ensure you remain compliant - Mandatory -* - You report on and share outcomes of each audit of your TRE organisation with the required bodies - - This may included regulatory bodies or the organisations that manage accreditations you have - - Mandatory +* - You should report on and share outcomes of each audit of your TRE organisation with the required bodies. + - This may be a requirement of continued accreditation by external organisations or regulatory bodies. + - Recommended ``` ## Risk management @@ -99,17 +104,17 @@ _The ability of the TRE organisation to measure, forecast and evaluate risks to * - Statement - Guidance - Importance -* - You have a way to score risk to understand the underlying severity - - You have a risk assesment methodology for scoring risks on multiple axes such as impact and likelihood +* - You must have a way to score risk to understand the underlying severity. + - You have a risk assesment methodology for scoring risks on multiple axes such as impact and likelihood. - Mandatory -* - You have a process for mitigating risk using additional controls - - Risks can be reduced to a level which brings it within agreed levels of appetite +* - You must have a process for mitigating risk using additional controls. + - Risks can be reduced to a level which brings it within agreed levels of appetite. - Mandatory -* - You have an understanding of risk appetite - - This includes understanding ownership of risk, and ability to accept risk which falls outside of the appetite should that become necessary +* - You must have an understanding of risk appetite. + - This includes understanding ownership of risk, and ability to accept risk which falls outside of the appetite should that become necessary. - Mandatory -* - You carry out a data processing assessment for all projects requiring a TRE that are working with sensitive data - - A data processing assessment is a process designed to identify risks arising out of the processing of sensitive data and to minimise these risks as far and as early as possible +* - You must carry out a data processing assessment for all projects requiring a TRE that are working with sensitive data. + - A data processing assessment is a process designed to identify risks arising out of the processing of sensitive data and to minimise these risks as far and as early as possible. - Mandatory ``` @@ -126,8 +131,8 @@ _The ability of the TRE organisation to manage projects effectively._ * - Statement - Guidance - Importance -* - You have checks in place to ensure a project has the legal, financial and ethical requirements in place for the duration of the project - - This includes checks that contracts are in place where required, adequate funding is available for the duration of the project, and responsibilities concerning data ownership are understood by all parties +* - You must have checks in place to ensure a project has the legal, financial and ethical requirements in place for the duration of the project. + - This includes checks that contracts are in place where required, adequate funding is available for the duration of the project, and responsibilities concerning data ownership are understood by all parties. - Mandatory ``` @@ -140,8 +145,8 @@ _The ability of the TRE organisation to manage projects effectively._ * - Statement - Guidance - Importance -* - You have standard processes in place for the end of a project, that follow all legal requirements and data security best practice - - This includes the archiving of quality and log data along with the archiving or deletion of data sets +* - You must have standard processes in place for the end of a project, that follow all legal requirements and data security best practice. + - This includes the archiving of quality and log data along with the archiving or deletion of data sets. - Mandatory ``` @@ -153,8 +158,9 @@ _The ability of the TRE organisation to manage projects effectively._ * - Statement - Guidance - Importance -* - You have clearly defined roles and responsibilities within your TRE organisation for all members - - This may include roles such as users, system administrators, system operators, data providers and more. Every member of your TRE organisation should have a pre-defined role with clear powers and responsibilities +* - You must have clearly defined roles and responsibilities for all operators and users of your TRE. + - This may include roles such as users, system administrators, system operators or data providers. + Every member of your TRE organisation should have at least one pre-defined role with clear powers and responsibilities. - Mandatory ``` @@ -171,11 +177,11 @@ _The ability of the TRE organisation to ensure that people with access to data a * - Statement - Guidance - Importance -* - You have clear onboarding processes in place for all roles within your TRE organisation - - This may include all members signing role-specific terms of use, and completing role specific training +* - You must have clear onboarding processes in place for all roles within your TRE organisation. + - This may include all members signing role-specific terms of use, and completing role specific training. - Mandatory -* - You have a robust method for identifying accredited members of your TRE organisation, prior to their accessing of sensitive data - - This may include multi-factor authentication (MFA), ID checks or email/phone verification +* - You must have a robust method for identifying accredited members of your TRE organisation, prior to their accessing of sensitive data. + - This may include multi-factor authentication (MFA), ID checks or email/phone verification. - Mandatory ``` @@ -188,13 +194,17 @@ _The ability of the TRE organisation to ensure that people with access to data a * - Statement - Guidance - Importance -* - You have relevant training for all roles within the TRE organisation, and the ability to deliver this training - - This may include: Cyber security training, GDPR training, and higher level training for system operators - - Mandatory -* - All TRE organisation members have completed relevant training within the last 12 months - - - - Mandatory -* - You have a process in place to monitor all TRE organisation training completions & requirements - - This process should document which members have completed which training, when the training was completed, and the date the training expires. It should also document how you will notify members when their training is about to expire, and ensure they do not have access to any TRE if relevant training is out-of-date +* - You must have relevant training for all roles within the TRE organisation, and the ability to deliver this training. + - This may include, for instance, yber security training, GDPR training, and higher level training for system operators. + - Mandatory +* - You must ensure that all users and operators of your TRE complete their training satisfactorily. + - This may involve assessing their level of knowledge and repeating the training if necessary. + - Mandatory +* - You should ensure that all users and operators of your TRE repeat their training regularly. + - For instance, you may want everyone to have completed their training within the last 12 months. + - Recommended +* - You must have a process in place to monitor all TRE organisation training completions and requirements. + - This process should document which members have completed which training, when the training was completed, and the date the training expires. + It should also document how you will notify members when their training is about to expire, and, if appropriate revoke access to the TRE. - Mandatory ``` diff --git a/docs/source/pillars/supporting.md b/docs/source/pillars/supporting.md index 48e397c7..533ac655 100644 --- a/docs/source/pillars/supporting.md +++ b/docs/source/pillars/supporting.md @@ -13,7 +13,7 @@ SATRE Pillars Capability Map ## Business continuity management -_What the organisation does to ensure the development, testing, and maintenance of business continuity plans._ +_What the TRE operator does to ensure the development, testing, and maintenance of business continuity plans._ ```{list-table} :header-rows: 1 @@ -22,17 +22,17 @@ _What the organisation does to ensure the development, testing, and maintenance * - Statement - Guidance - Importance -* - You have a business continuity plan that includes consideration of loss of service for deployed TREs - - This may be due to downtime from service providers, a breach, or loss of power. Your plan should detail your process for managing loss of service for deployed TREs, and evaluation of impact of such loss +* - You should have a business continuity plan that includes consideration of loss of service for deployed TREs. + - This may be due to downtime from service providers, a breach, or loss of power. Your plan should detail your process for managing loss of service for deployed TREs, and evaluation of impact of such loss. - Recommended -* - You regularly test the aspects of your business continuity plan concerning TREs, and have a process in place to iterate the plan if required +* - You should regularly test the aspects of your business continuity plan concerning TREs, and have a process in place to iterate the plan if required. - - Recommended ``` ## Project and programme management -_What the organisation does to ensure effective management of programmes and projects._ +_What the TRE operator does to ensure effective management of programmes and projects._ ```{list-table} :header-rows: 1 @@ -41,17 +41,18 @@ _What the organisation does to ensure effective management of programmes and pro * - Statement - Guidance - Importance -* - TRE operators should ensure that all projects requiring a TRE have a named project manager - - The project manager has responsibility to ensure the smooth running of the project. Their responsibilities may include budget management, tracking TRE status, managing communications with the TRE operations team, and other project support tasks +* - You should ensure that all projects using your TRE have a named project manager. + - The project manager has responsibility to ensure the smooth running of the project. + Their responsibilities may include budget management, tracking TRE status, managing communications with the TRE operations team, and other project support tasks + - Recommended +* - You should not give project managers direct access to the TRE. + - Doing so ensures a separation between those able to access sensitive data, and those overseeing access to sensitive data. - Recommended -* - Project managers should not have direct access to the TRE - - Doing so ensures a separation between those able to access sensitive data, and those overseeing access to sensitive data - - Optional ``` ## Knowledge management -_What the organisation does to acquire, enrich, share, store, publish and enhance the expertise across the whole organisation._ +_What the TRE operator does to acquire, enrich, share, store, publish and enhance expertise across their organisation._ ```{list-table} :header-rows: 1 @@ -60,20 +61,20 @@ _What the organisation does to acquire, enrich, share, store, publish and enhanc * - Statement - Guidance - Importance -* - All features of your TRE infrastructure must be well documented +* - You must document all features of your TRE implementation. - This includes ensuring all documentation is discoverable, clear, and able to be easily updated based on stakeholder feedback - Mandatory -* - You should have an education programme in place to upskill stakeholders in the use and management of your TRE infrastructure - - This may include learning modules, workshops and other resources on how to effectively access and use a TRE, FAQs pages, and accessible pathways for additional support +* - You should have an education programme in place to upskill stakeholders in the use and management of your TRE. + - This may include learning modules, workshops and other resources on how to effectively access and use a TRE, FAQ pages, and accessible pathways for additional support - Recommended -* - You should periodically carry out a training needs analysis (TNA) for all stakeholders included within your TRE provision +* - You should periodically carry out a training needs analysis (TNA) for all stakeholders included within your TRE provision. - At least once every 12 months you should assess the training needs of your stakeholders, and ensure they have easy access to all required training materials - Recommended ``` ## Financial management -_All activities aimed at the efficient and effective management of money (funds) in such a manner as to allow the organisation to accomplish its objectives._ +_All activities aimed at the efficient and effective management of money (funds) in such a manner as to allow the TRE operator to accomplish its objectives._ ```{list-table} :header-rows: 1 @@ -82,23 +83,23 @@ _All activities aimed at the efficient and effective management of money (funds) * - Statement - Guidance - Importance -* - TRE operators must make all projects using a TRE aware of any financial costs associated with their TRE use and ensure that they are able and willing to pay them. +* - You must ensure that all projects using your TRE are aware of any associated costs and are able and willing to pay them. - Costs may include provision of the underlying TRE infrastructure, additional resources required in a specific TRE (for instance memory or additional compute), hardware including managed devices, and staff support costs - Mandatory -* - The organisation operating the TRE should be able to track costs associated with each TRE project +* - You should be able to track the costs associated with each TRE project - This includes knowing which costs are associated with which project, and having an appropriate charging mechanism in place in line with your organisational policy - Recommended -* - You should have a process in place to ensure your TRE provision remains sustainable +* - You should have a process in place to ensure your TRE provision remains financially sustainable. - This could include having a cost recovery process in place, or setting up a long-term funding mechanism to support projects with TREs. At any given time, you should have funds free to cover all potential foreseen TRE provision for at least 12 months - Recommended * - You should minimise the cost of your TRE infrastructure wherever possible - - You should have regular reviews of your TRE provision and actively work to bring down costs, streamline provision, and optimise support - - Optional + - You should have regular reviews of your TRE provision and actively work to bring down costs, streamline provision, and optimise support. + - Recommended ``` ## Procurement -_What the organisation does to ensure the effective sourcing, purchasing and supply of the goods and services that enable the organisation to operate._ +_What the TRE operator does to ensure the effective sourcing, purchasing and supply of the goods and services that enable them to operate._ ```{list-table} :header-rows: 1 @@ -107,14 +108,14 @@ _What the organisation does to ensure the effective sourcing, purchasing and sup * - Statement - Guidance - Importance -* - The organisation operating the TRE must identify any goods or services that will be needed to operate the TRE and ensure that a plan is in place to purchase them as needed. +* - You must identify any goods or services that will be needed to operate the TRE and ensure that a plan is in place to purchase them as needed. - These may include computing hardware, cloud credits or devices through which users access the TRE. - Mandatory ``` ## IT Service management -_The implementation and management of quality IT services that meet the needs of the organisation._ +_The implementation and management of quality IT services that meet the needs of the TRE operator._ ```{list-table} :header-rows: 1 @@ -123,14 +124,15 @@ _The implementation and management of quality IT services that meet the needs of * - Statement - Guidance - Importance -* - The organisation running the TRE must have a team in place to support projects working with TREs - - This may be part of your organisation's IT support team, or separate. Responsibility should be clear and stakeholders should easily be able to access support appropriate to their needs +* - You TRE must have a team in place to support projects working with TREs. + - This may be part of your organisation's IT support team, or separate. + Responsibility should be clear and stakeholders should easily be able to access support appropriate to their needs. - Mandatory ``` ## Relationship management -_All activities aimed at ensuring a continuous level of engagement is maintained between the organisation and its customers, stakeholders & other interested parties._ +_All activities aimed at ensuring a continuous level of engagement is maintained between the TRE operator and its customers, stakeholders & other interested parties._ ### Stakeholder relationships @@ -141,14 +143,14 @@ _All activities aimed at ensuring a continuous level of engagement is maintained * - Statement - Guidance - Importance -* - You should have a clear process in place for stakeholders to feedback on your TRE infrastructure - - This may include a GitHub repository where people can open issues and discussions, communication streams like Slack or email, or forms stakeholders can fill in +* - You should have a clear process in place for stakeholders to feedback on your TRE infrastructure. + - This may include a GitHub repository where people can open issues and discussions, communication streams like Slack or email, or forms stakeholders can fill in. - Recommended ``` ## Public Involvement and Engagement -_How the TRE organisation involves the public in its processes and work in order to maintain trust in its operations._ +_How the TRE operator involves the public in its processes and work in order to maintain trust in its operations._ ### Legal advisory -_Ability of the organisation to provide suitable and timely legal advice._ +_Ability of the TRE operator to provide suitable and timely legal advice._ ```{list-table} :header-rows: 1 @@ -196,8 +198,9 @@ _Ability of the organisation to provide suitable and timely legal advice._ * - Statement - Guidance - Importance -* - The TRE organisation should have ready access to legal advice - - It is likely that legal advice will be necessary for several issues around the handling of sensitive data, and managing project contracts. TRE organisations should have ready access to legal advice, including a way to solicit advice and carry out associated actions +* - You should have identify areas where legal advice may be required and ensure that you have ready access to it. + - It is likely that legal advice will be necessary for several issues around the handling of sensitive data, and managing project contracts. + TRE operators should have ready access to legal advice, including a way to solicit advice and carry out associated actions - Recommended ``` @@ -212,7 +215,7 @@ _Ability to ensure data is used fairly, lawfully and transparently; for specifie * - Statement - Guidance - Importance -* - The TRE organisation should identify areas where data protection advice may be needed and plan where this will be sourced from. +* - You should have identify areas where legal advice may be required and ensure that you have ready access to it. - It is likely that data protection advice will be necessary for several issues around the handling of sensitive data. - Recommended ``` @@ -228,7 +231,7 @@ _What the organisation does to ensure that all contracts are effectively managed * - Statement - Guidance - Importance -* - The organisation running the TRE should identify who will be responsible for managing contracts related to the TRE. +* - You should identify who will be responsible for managing contracts related to the TRE. - These contracts may include data sharing agreements, secondments of personnel or limitations on how results obtained with the data can be distributed. - Recommended ``` diff --git a/docs/source/specification.md b/docs/source/specification.md index 1463d576..8692aff8 100644 --- a/docs/source/specification.md +++ b/docs/source/specification.md @@ -5,31 +5,34 @@ The SATRE specification follows a capability-evaluation model. +The specification is presented in terms of the capabilities that a team running a TRE should aim for across all aspects of TRE provision. -The specification is presented in terms of capabilities teams should aim for across all aspects of TRE provision. -These capabilities are broken down into components. -Each component is a statement of a process, method or practice teams should have in place to ensure they fulfil the capability requirements. +:::{note} +Throughout this document we will use the term "TRE operator" to refer to the team running a particular TRE. +::: -Any particular component is labelled with an importance. +The TRE capabilities are broken down into components. +Each component is a statement of a process, method or practice that the operators should have in place to ensure they fulfil the capability requirements. +These components are each labelled with an importance. The importance is one of **mandatory**, **recommended** or **optional**. :::{note} The intended meaning of the capability component importance labels is as follows: Mandatory -: We believe this is required. If this component is not supported, then the capability, and the specification, is not met. +: This is required. If this component is not supported, then the capability, and the specification, is not met. Recommended : We believe that TREs should have this component. It makes a TRE better. Optional -: We believe many TREs would benefit from this component. However, we recognise there are reasons a team may actively choose not to support this component. +: We believe many TREs would benefit from this component. However, we recognise there are reasons a TRE operator may actively choose not to support this component. ::: -Teams are able demonstrate that they meet the specification by showing they can fulfil all **mandatory** components. +TRE operators are able to demonstrate that they meet the specification by showing they can fulfil all **mandatory** components. Future versions of the specification may introduce more granular levels of evaluation, for instance tiered level of accreditation based on fulfilment of mandatory, recommended and optional components respectively. -Any particular TRE implementation should be able to score itself against each capability as either supported, partially supported or unsupported (see {ref}`evaluation` for details). +Any particular TRE implementation should be able to score itself against each capability as either **supported**, **partially supported** or **unsupported** (see {ref}`evaluation` for details). ## Structure @@ -43,13 +46,13 @@ SATRE Specification Architecture ``` {ref}`Architectural Principles ` -: The principles that all teams looking to use the specification should hold themselves accountable to. +: The principles that all TRE operators looking to use the specification should hold themselves accountable to. {ref}`Specification Pillars ` : The broad areas of TRE provisioning the specification covers. TRE Capabilities -: The capabilities within these pillars teams can measure themselves against. +: The capabilities within these pillars that TRE operators can measure themselves against. TRE Capability Components : The statements concerning processes, controls, practices and applications that make up a capability, together with an importance label. @@ -67,7 +70,7 @@ The SATRE specification has been developed based on the following principles: - TREs conforming to the specification should be interoperable and provide a familiar end-user experience. - The specification will be managed and updated following an open, community-driven process, and will not be tied to a single vendor or implementation. -Finally, the TRE organisation will need to consider different {ref}`roles ` with which individuals might interact with the TRE. +Finally, the TRE operators will need to consider different {ref}`roles ` with which individuals might interact with the TRE. There might be good reasons why any particular TRE does not possess one or more of the capabilities listed in this specification, but most TREs should aspire to meet them in the long-term. @@ -85,13 +88,13 @@ SATRE Pillars Capability Map ``` {ref}`Information governance ` -: What the organisation does to ensure information risk is measured and managed to an acceptable level. +: What the TRE operators do to ensure information risk is measured and managed to an acceptable level. {ref}`Computing technology ` -: What the organisation does to manage systems for storing, retrieving, and sending information. +: What the TRE operators do to manage systems for storing, retrieving, and sending information. {ref}`Data management ` -: What the organisation does to manage data assets and ensure information remains secure. +: What the TRE operators do to manage data assets and ensure information remains secure. -In addition to these capabilities, any organisation running a TRE (TRE organisation) will need to possess various {ref}`supporting capabilities `. +In addition to these capabilities, any TRE operator will need to possess various {ref}`supporting capabilities `. Examples of supporting capabilities include complying with legal requirements and managing relationships with stakeholders. From 66c9ea8ce4c3ff1abd1409b1a7fe1f940dc088ae Mon Sep 17 00:00:00 2001 From: James Robinson Date: Wed, 5 Jul 2023 19:02:37 +0100 Subject: [PATCH 4/9] :memo: Grammar fixes --- docs/source/contributing/index.md | 14 ++-- docs/source/contributing/walkthrough.md | 65 ++++++++++--------- docs/source/pillars/computing_technology.md | 2 +- docs/source/pillars/data_management.md | 4 +- docs/source/pillars/information_governance.md | 2 +- docs/source/specification.md | 6 +- 6 files changed, 47 insertions(+), 46 deletions(-) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index 3f42bf05..cdbe90f1 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -11,7 +11,7 @@ We hope that the information provided in this document will make it as easy as p We welcome contributions to this project via GitHub issues and pull requests. Please follow these guidelines to make sure your contributions can be easily integrated into the project. -As you start contributing don't forget that your ideas are more important than perfectly formatted contributions :heart:. +As you start contributing, don't forget that your ideas are more important than perfectly formatted contributions :heart:. If you have any questions that aren't discussed below, please let us know through one of the many ways to [get in touch](contributing-get-in-touch). @@ -47,7 +47,7 @@ If you see a part of the specification you don't like, open an issue about it an :::{important} We are in a bootstrapping phase to get an initial specification written. -As part of this initial work we will propose a more formal governance model for the specification going forwards. +As part of this initial work, we will propose a more formal governance model for the specification going forwards. We have chosen to keep all discussion to issues for now, so contributors have a single place to engage in conversation. Pull requests are used when a specific change is ready to be proposed. @@ -78,18 +78,18 @@ Issues should be used to discuss ideas, potential changes and to ask questions. Issue templates have been designed for common issue types to help collect the most important information and present it in a clear, consistent way. It is possible, however, to open a blank issue if none of the templates are suitable. -While we encourage opening issues, we understand that some may be more comfortable contributing ideas in other ways such as through discussions and notes at SATRE Collaboration Cafés. +While we encourage opening issues, we understand that some may be more comfortable contributing ideas in other ways, such as through discussions and notes at SATRE Collaboration Cafés. The SATRE Team will aim to collate ideas and draft issues that welcome further discussion and attribute those involved in initial discussions. The SATRE Team will try to capture the ideas as accurately as possible, in good faith, and be guided by the SATRE Community to correct any misconceptions. When ready, changes will be proposed in pull requests. Similarly to issues, there is a pull request template. -This template prompts contributors to include important details which helps explain the contribution and makes triage and review easier. +This template prompts contributors to include important details, which helps explain the contribution and makes triage and review easier. Pull requests will be used to review changes. During the review process, the pull request will be used for discussion, to suggest amendments and ultimately accept or reject the change. -We use this process to ensure that as much as possible of the discussion and decision making process can be public. +We use this process to ensure that as much as possible of the discussion and decision-making process can be public. This is to provide as open and accessible as possible an environment for all contributors to engage in the conversation. ### Consensus Mechanism @@ -109,7 +109,7 @@ GitHub also has a helpful page on [getting started with writing and formatting o You can think of Markdown as a few little symbols around your text that instruct how to render the text. For example, you could write words in **bold** (`**bold**`), in _italics_ (`_italics_`), or as a [link](https://medium.com/satre) (`[link](https://medium.com/satre)`) to another web page. -Also when writing in Markdown, please [start each new sentence on a new line](https://sembr.org/). +Also, when writing in Markdown, please [start each new sentence on a new line](https://sembr.org/). Having each sentence on a new line will make no difference to how the text is displayed. A blank line is needed to start a new paragraph. However, it makes the source and [diffs produced during the pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests) review easier to read ✨! @@ -177,7 +177,7 @@ It is best to add each contributor in turn and merge the pull request before add Otherwise, you can end up with merge conflicts. Please check the open pull requests first to make sure there aren't any [open requests from the bot](https://github.com/sa-tre/satre-specification/pulls/app%2Fallcontributors) before adding another. -What happens if you accidentally run the bot before the previous run was merged and you got those pesky merge conflicts? +What happens if you accidentally run the bot before the previous run was merged, and you got those pesky merge conflicts? (Don't feel bad, we have all done it! 🙈) Simply close the pull request and delete the branch (`all-contributors/add-`). If you are unable to do this for any reason, please let us know by opening an issue, and SATRE team members will be very happy to help! diff --git a/docs/source/contributing/walkthrough.md b/docs/source/contributing/walkthrough.md index 1f6cbd9f..14a48f23 100644 --- a/docs/source/contributing/walkthrough.md +++ b/docs/source/contributing/walkthrough.md @@ -10,7 +10,7 @@ Your contributions, regardless of your experience level, are highly welcomed and ## Understanding the SATRE Project -Before getting involved, please read [SATRE's Kick Off Blog Post](https://medium.com/satre/satre-kick-off-sessions-87d3237107aa) (a 6 minute read) to understand the motivations of the project. +Before getting involved, please read [SATRE's Kick Off Blog Post](https://medium.com/satre/satre-kick-off-sessions-87d3237107aa) (a 6-minute read) to understand the motivations of the project. ## Join the Community @@ -18,28 +18,28 @@ Before getting involved, please read [SATRE's Kick Off Blog Post](https://medium To get the latest SATRE Newsletter and communications, please sign up to our [Mailing List](https://forms.office.com/pages/responsepage.aspx?id=p_SVQ1XklU-Knx-672OE-XMfskt9FY5HraQ6BiwaEGBUREMxWU9NVDhHTEJNTFM0VEZXRTZZQ0hYVi4u) -### Sign up to our Collaboration Cafes +### Sign up to our Collaboration Cafés -We hold 1 hour online Zoom Collaboration Cafes to facilitate sharing ideas for what should be in the SATRE Specification. -Collaboration Cafe's happen at 3pm on the 1st Tuesday and 3rd Thursday of the month. +We hold one hour online Zoom Collaboration Cafés to facilitate sharing ideas for what should be in the SATRE Specification. +Collaboration Cafés happen at 3pm on the 1st Tuesday and 3rd Thursday of the month. Please fill in [this form](https://forms.office.com/pages/responsepage.aspx?id=p_SVQ1XklU-Knx-672OE-XMfskt9FY5HraQ6BiwaEGBUNUg1T05DNEJMNEtaN0JOOURKTDBFUENFQi4u) to register your attendance in advance. -Collaboration Cafes are run using HackMD documents that will contain the meeting agenda and a place share notes. +Collaboration Cafés are run using HackMD documents that will contain the meeting agenda and a place to share notes. If you are unfamiliar with HackMD, please see [this guide](https://hackmd.io/@turingway/hackmd-guide) on how to use it. -Please also see an [example HackMD](https://hackmd.io/N7EBtM6iS2OQsWCPWC-ojg) from our Collaboration Cafe on the 18th May 2023. -Each Collaboration Cafe uses Breakout Rooms where participants will work on themes e.g. Risk Management or Training Requirements. -Typically each Breakout Room is linked to an Issue on the [SATRE GitHub Issues Board](https://github.com/sa-tre/satre-specification/issues). +Please also see a [sample HackMD](https://hackmd.io/N7EBtM6iS2OQsWCPWC-ojg) from our Collaboration Café on the 18th May 2023. +Each Collaboration Café uses Breakout Rooms where participants will work on themes, e.g. Risk Management or Training Requirements. +Typically, each Breakout Room is linked to an Issue on the [SATRE GitHub Issues Board](https://github.com/sa-tre/satre-specification/issues). :::{important} -The HackMD for each Collaboration Cafe is made available in your calendar invites. -We encourage you to propose a Breakout Room in advanced of the Collaboration Cafe, linking to a [SATRE GitHub Issue](https://github.com/sa-tre/satre-specification/issues) if possible. -This will help participants come prepared to talk about certain topics. We also welcome Breakout Room proposals on the day though! +The HackMD for each Collaboration Café is made available in your calendar invites. +We encourage you to propose a Breakout Room in advanced of the Collaboration Café, linking to a [SATRE GitHub Issue](https://github.com/sa-tre/satre-specification/issues) if possible. +This will help participants come prepared to talk about certain topics. We also welcome Breakout Room proposals on the day, though! ::: ## Review the SATRE Specification Document The latest version of the SATRE Specification Document can be found [here](../specification.md). -It is a living document in which the aim is to have a completed draft by October 2023. +It is a living document, in which the aim is to have a completed draft by October 2023. ## Contribute to the SATRE Specification Document @@ -48,13 +48,14 @@ As a collaborative project driven by community needs, we'd love for you to contr There are two ways to do this: 1. Directly to the specification on GitHub (recommended, but more difficult) -2. To a non-GitHub version for the specification (less recommended, but easier) +2. To a non-GitHub version of the specification (less recommended, but easier) -Why the difference? GitHub is the live version of the specification, and is great for things like community discussions, version control, editing changes and more. -This is why we recommend contributing GitHub - it is the most direct way to work with the SATRE team on the specification. +Why the difference? +GitHub is the live version of the specification, and is great for things like community discussions, version control, editing changes and more. +This is why we recommend contributing via GitHub - it is the most direct way to work with the SATRE team on the specification. However, we realise this may be difficult if you aren't already familiar with GitHub's ways of working. -Therefore we also have a non-GitHub version of the specification you can comment on. +Therefore, we also have a non-GitHub version of the specification you can comment on. Once a week, we will translate comments from this version to the GitHub repository for direct amendments. So you are still able to contribute via this method, though all direct changes will still be taking place on GitHub. @@ -80,7 +81,7 @@ GitHub homepage 1. Once you are logged in, navigate to the [SATRE Specification page](https://github.com/sa-tre/satre-specification) 2. This is the SATRE specification **repository**. You can think of this like a directory containing all files to do with the SATRE specification. - The main things to know about are the link in the `About` Section, and the `Code`, `Issues` and `Pull requests` tabs. + The main things to know about are the link in the Section, and the `Code`, `Issues` and `Pull requests` tabs. Let's look at these in turn. ```{figure} ../../images/satre_specification_repo.png @@ -92,8 +93,8 @@ SATRE specification repository #### About link -This link will take you a readable version of the specification. -You can access the current live version of the specification by clicking on `A Standard Architecture for TREs` from the left hand navigation bar. +This link will take you to a readable version of the specification. +You can access the current live version of the specification by clicking on `A Standard Architecture for TREs` from the left-hand navigation bar. You can navigate directly to it [here](../specification.md). ```{figure} ../../images/read_the_docs.png @@ -115,15 +116,15 @@ The most important one for you to know about is where the actual specification i SATRE repository docs directory ``` -You can find this by navigating to `docs` -> `source` -> `specification.md`. -This is the specification written in [Markdown](https://hackmd.io/@turingway/hackmd-guide), that renders into a website (which you can access from the `About` section). +You can find this by navigating to `docs` → `source` → `specification.md`. +This is the specification, written in [Markdown](https://hackmd.io/@turingway/hackmd-guide), that renders into a website (which you can access from the `About` section). Most `Issues` and `Pull requests` will be related to this file specifically - and this file is the official specification. You can read more about `Issues` and `Pull requests` below. #### Issues -Navigate to the the `Issues` tab. +Navigate to the `Issues` tab. This is where the community is having discussions about ideas for the specification. You can think of it like an online forum where you start discussions and comment on pre-existing discussions. @@ -168,7 +169,7 @@ Comment on SATRE specification issues Create new SATRE specification issue ``` -2. You should be able to select a template for the issue you want to create - you can choose from the available options, or `Open a blank issue` of no template is right. +2. You should be able to select a template for the issue you want to create - you can choose from the available options, or `Open a blank issue` if no template is right. 3. Fill in the template and select `Submit new issue`. @@ -210,12 +211,12 @@ View discussion on a SATRE specification pull request For the purposes of this guide, we will just focus on comments. Make sure you are on the `Conversation` tab. -3. From here, you can comment in the same way as you did with Issues (add your comment at the bottom, and click `Comment`). +3. From here, you can comment in the same way as you did with `Issues` (add your comment at the bottom, and click `Comment`). ##### Create your own Pull Request -If you would like to directly author a change to the specification yourself then you can create a Pull Request. -Currently you will need to make a Fork of the SATRE repository to make a Pull Request. Here's how it works: +If you would like to directly author a change to the specification yourself, then you can create a Pull Request. +Currently, you will need to make a Fork of the SATRE repository to make a Pull Request. Here's how it works: 1. **Create a Fork of the SATRE specification repository:** @@ -240,7 +241,7 @@ Name your fork of the SATRE repository Link to the main SATRE repository ``` -2. **Keep the Fork up to date.** It is common for work to continue on the original repository while you are working with your forked version of the repository. +2. **Keep the fork up to date.** It is common for work to continue on the original repository while you are working with your forked version of the repository. This means work on the original repository will not be reflected in your forked repository. You can keep your forked repository up to date by pressing the sync button (note that we are assuming there aren't any merge conflicts): @@ -251,7 +252,7 @@ Link to the main SATRE repository Update your fork of the SATRE repository ``` -1. **Edit the section you want to change.** Click on the `specification.md` file in the repository where you will be able to edit it: +1. **Edit the section you want to change.** Click on the `specification.md` file in the repository, where you will be able to edit it: ```{figure} ../../images/github_edit_file.png :alt: Edit a file @@ -293,7 +294,7 @@ Create your pull request! ``` You have now just opened a Pull Request intended to merge the changes on your Fork to the original SATRE Repository! -Don't forget to Sync your Fork when the Pull Request gets accepted into the original repository. +Don't forget to sync your Fork when the Pull Request gets accepted into the original repository. ### Additional considerations for GitHub @@ -303,7 +304,7 @@ In order to make sure you stay informed of conversations you have joined, you ne ##### Notifications from the repository -From the `Code` tab, click `Watch` -> `Participating and @mentions`. +From the `Code` tab, click `Watch` → `Participating and @mentions`. This will ensure you get notified to any conversations where you are already taking part, or are mentioned by someone else. If you are really keen, you can turn on notifications for the whole repository, to be notified of any new issues or pull requests people open! @@ -323,7 +324,7 @@ We recommend receiving `Participating and @mentions` notifications by email too, GitHub settings ``` -2. On left hand navigation bar, click `Notifications`. +2. On left-hand navigation bar, click `Notifications`. Ensure your email is the right one, and then in `Participating and @mentions` check both `GitHub` and `Email`, and click save. ```{figure} ../../images/github_notification_settings.png @@ -354,7 +355,7 @@ When you are commenting on Issues/PRs, there are a couple of handy things to kno Pull request number ``` -There will always be a dedicated Breakout Room in the Collaboration Cafes where one of the SATRE Team will be on hand to answer any questions and guide you through the GitHub Repository and help you get set up. +There will always be a dedicated Breakout Room in the Collaboration Cafés where one of the SATRE Team will be on hand to answer any questions and guide you through the GitHub Repository and help you get set up. ### Contribute via alternate streams diff --git a/docs/source/pillars/computing_technology.md b/docs/source/pillars/computing_technology.md index 77ae6d51..814e2c2f 100644 --- a/docs/source/pillars/computing_technology.md +++ b/docs/source/pillars/computing_technology.md @@ -275,7 +275,7 @@ _The ability of the TRE operator to identify, maintain, and verify information o ## Availability management -_The ability of the TRE operator to ensure all IT infrastructure, processes, tools, roles etc are appropriate for the agreed availability targets._ +_The ability of the TRE operator to ensure all IT infrastructure, processes, tools, roles etc. are appropriate for the agreed availability targets._ ```{list-table} :header-rows: 1 diff --git a/docs/source/pillars/data_management.md b/docs/source/pillars/data_management.md index aff44fec..dffbb2e1 100644 --- a/docs/source/pillars/data_management.md +++ b/docs/source/pillars/data_management.md @@ -72,7 +72,7 @@ _The ability of the TRE operator to manage how and where data is stored, how it ## Identity and access management -_The ability of the TRE operator to ensure the right people (identities) can access the tools and data they need and no more._ +_The ability of the TRE operator to ensure the right people (identities) can access the tools and data they need, and no more._ ```{list-table} :header-rows: 1 @@ -163,7 +163,7 @@ Measures taken to ensure information security can be further categorised into: - {ref}`physical security `: restricting TRE access to known secure locations A TRE conforming to the SATRE standard should enact broadly similar measures to protect against the unauthorised use of information, especially electronic data. -These measures include vulnerability management of TRE infrastructure (whether physical or virtual/cloud-based), carrying out compliance checks and security tests of the TRE, common approaches to data encryption, and (where appropriate) physical security measures to prevent unauthorised access to the TRE . +These measures include vulnerability management of TRE infrastructure (whether physical or virtual/cloud-based), carrying out compliance checks and security tests of the TRE, common approaches to data encryption, and (where appropriate) physical security measures to prevent unauthorised access to the TRE. (vulnerability-management)= diff --git a/docs/source/pillars/information_governance.md b/docs/source/pillars/information_governance.md index 53b845c5..6d7acb9b 100644 --- a/docs/source/pillars/information_governance.md +++ b/docs/source/pillars/information_governance.md @@ -166,7 +166,7 @@ _The ability of the TRE organisation to manage projects effectively._ ## Member accreditation -_The ability of the TRE organisation to ensure that people with access to data are identified correctly and they are suitably qualified._ +_The ability of the TRE organisation to ensure that people with access to data are identified correctly, and they are suitably qualified._ ### Onboarding members diff --git a/docs/source/specification.md b/docs/source/specification.md index 8692aff8..d80568ec 100644 --- a/docs/source/specification.md +++ b/docs/source/specification.md @@ -8,7 +8,7 @@ The SATRE specification follows a capability-evaluation model. The specification is presented in terms of the capabilities that a team running a TRE should aim for across all aspects of TRE provision. :::{note} -Throughout this document we will use the term "TRE operator" to refer to the team running a particular TRE. +Throughout this document, we will use the term "TRE operator" to refer to the team running a particular TRE. ::: The TRE capabilities are broken down into components. @@ -57,7 +57,7 @@ TRE Capabilities TRE Capability Components : The statements concerning processes, controls, practices and applications that make up a capability, together with an importance label. -In addition we also describe some {ref}`roles ` that are necessary for the operation and use of a TRE. +In addition, we also describe some {ref}`roles ` that are necessary for the operation and use of a TRE. (satre_principles)= @@ -65,7 +65,7 @@ In addition we also describe some {ref}`roles ` that are necessary The SATRE specification has been developed based on the following principles: -- TREs should be as as easy as possible for end-users to use (_e.g._ researchers) whilst still remaining secure. +- TREs should be as easy as possible for end-users to use (_e.g._ researchers) whilst still remaining secure. - TRE deployments should be offered that support data of different levels of sensitivity (_e.g._ through a tiered system of technical controls and policies). - TREs conforming to the specification should be interoperable and provide a familiar end-user experience. - The specification will be managed and updated following an open, community-driven process, and will not be tied to a single vendor or implementation. From 0030fdc98a307a65625179a02cc1202ea2445ef7 Mon Sep 17 00:00:00 2001 From: James Robinson Date: Thu, 6 Jul 2023 11:33:03 +0100 Subject: [PATCH 5/9] :memo: Additional grammar fixes from @JimMadge Co-authored-by: Jim Madge --- docs/source/contributing/index.md | 7 ++++--- docs/source/contributing/walkthrough.md | 8 ++++---- docs/source/pillars/information_governance.md | 14 +++++++------- docs/source/pillars/supporting.md | 13 +++++++------ 4 files changed, 22 insertions(+), 20 deletions(-) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index cdbe90f1..f874ff16 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -78,13 +78,14 @@ Issues should be used to discuss ideas, potential changes and to ask questions. Issue templates have been designed for common issue types to help collect the most important information and present it in a clear, consistent way. It is possible, however, to open a blank issue if none of the templates are suitable. -While we encourage opening issues, we understand that some may be more comfortable contributing ideas in other ways, such as through discussions and notes at SATRE Collaboration Cafés. +While we encourage opening issues, we understand that some may be more comfortable contributing ideas in other ways. +We support other methods of contribution such as discussions and notes taken at SATRE Collaboration Cafés. The SATRE Team will aim to collate ideas and draft issues that welcome further discussion and attribute those involved in initial discussions. The SATRE Team will try to capture the ideas as accurately as possible, in good faith, and be guided by the SATRE Community to correct any misconceptions. When ready, changes will be proposed in pull requests. Similarly to issues, there is a pull request template. -This template prompts contributors to include important details, which helps explain the contribution and makes triage and review easier. +This template prompts contributors to include important details in order to explain the contribution and make triage and review easier. Pull requests will be used to review changes. During the review process, the pull request will be used for discussion, to suggest amendments and ultimately accept or reject the change. @@ -177,7 +178,7 @@ It is best to add each contributor in turn and merge the pull request before add Otherwise, you can end up with merge conflicts. Please check the open pull requests first to make sure there aren't any [open requests from the bot](https://github.com/sa-tre/satre-specification/pulls/app%2Fallcontributors) before adding another. -What happens if you accidentally run the bot before the previous run was merged, and you got those pesky merge conflicts? +What happens if you accidentally run the bot before the previous run was merged and you got those pesky merge conflicts? (Don't feel bad, we have all done it! 🙈) Simply close the pull request and delete the branch (`all-contributors/add-`). If you are unable to do this for any reason, please let us know by opening an issue, and SATRE team members will be very happy to help! diff --git a/docs/source/contributing/walkthrough.md b/docs/source/contributing/walkthrough.md index 14a48f23..e4e31122 100644 --- a/docs/source/contributing/walkthrough.md +++ b/docs/source/contributing/walkthrough.md @@ -33,13 +33,13 @@ Typically, each Breakout Room is linked to an Issue on the [SATRE GitHub Issues :::{important} The HackMD for each Collaboration Café is made available in your calendar invites. We encourage you to propose a Breakout Room in advanced of the Collaboration Café, linking to a [SATRE GitHub Issue](https://github.com/sa-tre/satre-specification/issues) if possible. -This will help participants come prepared to talk about certain topics. We also welcome Breakout Room proposals on the day, though! +This will help participants come prepared to talk about certain topics. We also welcome Breakout Room proposals on the day though! ::: ## Review the SATRE Specification Document The latest version of the SATRE Specification Document can be found [here](../specification.md). -It is a living document, in which the aim is to have a completed draft by October 2023. +It is a living document, and we aim to have a completed draft by October 2023. ## Contribute to the SATRE Specification Document @@ -51,8 +51,8 @@ There are two ways to do this: 2. To a non-GitHub version of the specification (less recommended, but easier) Why the difference? -GitHub is the live version of the specification, and is great for things like community discussions, version control, editing changes and more. -This is why we recommend contributing via GitHub - it is the most direct way to work with the SATRE team on the specification. +GitHub is the live version of the specification and is great for things like community discussions, version control, editing changes and more. +This is why we recommend contributing via GitHub — it is the most direct way to work with the SATRE team on the specification. However, we realise this may be difficult if you aren't already familiar with GitHub's ways of working. Therefore, we also have a non-GitHub version of the specification you can comment on. diff --git a/docs/source/pillars/information_governance.md b/docs/source/pillars/information_governance.md index 6d7acb9b..3210e3d2 100644 --- a/docs/source/pillars/information_governance.md +++ b/docs/source/pillars/information_governance.md @@ -46,13 +46,13 @@ _The ability of a TRE operator to measure and control quality of processes, docu - Guidance - Importance * - You must control all of your policies and standard operating procedures. - - This may include measures like restricting edit access to relevant documents, and recording acceptance of policies for all TRE operators + - This may include measures like restricting edit access to relevant documents, and recording acceptance of policies for all TRE operators. - Mandatory * - You should use codified change processes when altering your policies and standard operating procedures. - - Recommended * - You could use version control to track changes to their policies and processes. - - Version control includes recording dates of changes, person responsible for carrying out changes, and summary of changes + - Version control includes recording dates of changes, person responsible for carrying out changes, and summary of changes. - Optional ``` @@ -67,10 +67,10 @@ _The ability of a TRE operator to track deviations from stated policies._ * - Statement - Guidance - Importance -* - You must have a clear process in place for addressing any activity that deviates from your policies and standard operating procedures - - This can include measures like triage analysis and a process for updating policies +* - You must have a clear process in place for addressing any activity that deviates from your policies and standard operating procedures. + - This can include measures like triage analysis and a process for updating policies. - Mandatory -* - You must have methods in place to record progress in resolving issues with, and deviations against, your policies +* - You must have methods in place to record progress in resolving issues with, and deviations against, your policies. - - Mandatory ``` @@ -86,7 +86,7 @@ _The ability of the TRE organisation to monitor compliance with internal and ext - Guidance - Importance * - You must be able to audit your TRE organisation against whichever external standards are relevant to you. - - If you are publicly accredited against a standard, for instance ISO27001, DSPT, CE+ etc., you must have processes in place to ensure you remain compliant + - If you are publicly accredited against a standard, for example ISO27001, DSPT or CyberEssentials+, you must have processes in place to ensure you remain compliant - Mandatory * - You should report on and share outcomes of each audit of your TRE organisation with the required bodies. - This may be a requirement of continued accreditation by external organisations or regulatory bodies. @@ -195,7 +195,7 @@ _The ability of the TRE organisation to ensure that people with access to data a - Guidance - Importance * - You must have relevant training for all roles within the TRE organisation, and the ability to deliver this training. - - This may include, for instance, yber security training, GDPR training, and higher level training for system operators. + - This may include, for instance, cyber security training, GDPR training, and higher level training for system operators. - Mandatory * - You must ensure that all users and operators of your TRE complete their training satisfactorily. - This may involve assessing their level of knowledge and repeating the training if necessary. diff --git a/docs/source/pillars/supporting.md b/docs/source/pillars/supporting.md index 533ac655..208c9fd6 100644 --- a/docs/source/pillars/supporting.md +++ b/docs/source/pillars/supporting.md @@ -43,7 +43,7 @@ _What the TRE operator does to ensure effective management of programmes and pro - Importance * - You should ensure that all projects using your TRE have a named project manager. - The project manager has responsibility to ensure the smooth running of the project. - Their responsibilities may include budget management, tracking TRE status, managing communications with the TRE operations team, and other project support tasks + Their responsibilities may include budget management, tracking TRE status, managing communications with the TRE operations team, and other project support tasks. - Recommended * - You should not give project managers direct access to the TRE. - Doing so ensures a separation between those able to access sensitive data, and those overseeing access to sensitive data. @@ -86,11 +86,12 @@ _All activities aimed at the efficient and effective management of money (funds) * - You must ensure that all projects using your TRE are aware of any associated costs and are able and willing to pay them. - Costs may include provision of the underlying TRE infrastructure, additional resources required in a specific TRE (for instance memory or additional compute), hardware including managed devices, and staff support costs - Mandatory -* - You should be able to track the costs associated with each TRE project - - This includes knowing which costs are associated with which project, and having an appropriate charging mechanism in place in line with your organisational policy +* - You should be able to track the costs associated with each TRE project. + - This includes knowing which costs are associated with which project, and having an appropriate charging mechanism in place in line with your organisational policy. - Recommended * - You should have a process in place to ensure your TRE provision remains financially sustainable. - - This could include having a cost recovery process in place, or setting up a long-term funding mechanism to support projects with TREs. At any given time, you should have funds free to cover all potential foreseen TRE provision for at least 12 months + - This could include having a cost recovery process in place, or setting up a long-term funding mechanism to support projects with TREs. + At any given time, you should have funds free to cover all potential foreseen TRE provision for at least 12 months. - Recommended * - You should minimise the cost of your TRE infrastructure wherever possible - You should have regular reviews of your TRE provision and actively work to bring down costs, streamline provision, and optimise support. @@ -200,7 +201,7 @@ _Ability of the TRE operator to provide suitable and timely legal advice._ - Importance * - You should have identify areas where legal advice may be required and ensure that you have ready access to it. - It is likely that legal advice will be necessary for several issues around the handling of sensitive data, and managing project contracts. - TRE operators should have ready access to legal advice, including a way to solicit advice and carry out associated actions + TRE operators should have ready access to legal advice, including a way to solicit advice and carry out associated actions. - Recommended ``` @@ -215,7 +216,7 @@ _Ability to ensure data is used fairly, lawfully and transparently; for specifie * - Statement - Guidance - Importance -* - You should have identify areas where legal advice may be required and ensure that you have ready access to it. +* - You should identify areas where legal advice may be required and ensure that you have ready access to it. - It is likely that data protection advice will be necessary for several issues around the handling of sensitive data. - Recommended ``` From 3841fa4f049bb402a05bcb16840d24bdb660f7b4 Mon Sep 17 00:00:00 2001 From: James Robinson Date: Thu, 6 Jul 2023 11:39:27 +0100 Subject: [PATCH 6/9] :memo: Apply phrasing/grammar suggestions from @craddm Co-authored-by: Matt Craddock --- docs/source/contributing/walkthrough.md | 10 ++++---- docs/source/index.md | 2 +- docs/source/pillars/computing_technology.md | 12 +++++----- docs/source/pillars/data_management.md | 26 +++++++++++---------- 4 files changed, 26 insertions(+), 24 deletions(-) diff --git a/docs/source/contributing/walkthrough.md b/docs/source/contributing/walkthrough.md index e4e31122..8f08f368 100644 --- a/docs/source/contributing/walkthrough.md +++ b/docs/source/contributing/walkthrough.md @@ -33,13 +33,13 @@ Typically, each Breakout Room is linked to an Issue on the [SATRE GitHub Issues :::{important} The HackMD for each Collaboration Café is made available in your calendar invites. We encourage you to propose a Breakout Room in advanced of the Collaboration Café, linking to a [SATRE GitHub Issue](https://github.com/sa-tre/satre-specification/issues) if possible. -This will help participants come prepared to talk about certain topics. We also welcome Breakout Room proposals on the day though! +This will help participants come prepared to talk about certain topics. We also welcome Breakout Room proposals on the day! ::: ## Review the SATRE Specification Document The latest version of the SATRE Specification Document can be found [here](../specification.md). -It is a living document, and we aim to have a completed draft by October 2023. +It is a living document, and we intend to have a complete draft by October 2023. ## Contribute to the SATRE Specification Document @@ -64,7 +64,7 @@ So you are still able to contribute via this method, though all direct changes w Below is a walkthrough of all the steps required to contribute via GitHub, from the very beginning. This walkthrough is designed to give you the critical path steps to contributing directly to the Specification repository. -For a more broad, deeper introduction to GitHub, check out the Turing Way's [Introduction to GitHub Workshop](https://www.youtube.com/watch?v=Vcckl-2dASM), run at CarpentryCon22. +For a broader, deeper introduction to GitHub, check out the Turing Way's [Introduction to GitHub Workshop](https://www.youtube.com/watch?v=Vcckl-2dASM), run at [CarpentryCon2022](https://2022.carpentrycon.org/). 1. Go to the [GitHub homepage](https://github.com/) @@ -81,7 +81,7 @@ GitHub homepage 1. Once you are logged in, navigate to the [SATRE Specification page](https://github.com/sa-tre/satre-specification) 2. This is the SATRE specification **repository**. You can think of this like a directory containing all files to do with the SATRE specification. - The main things to know about are the link in the Section, and the `Code`, `Issues` and `Pull requests` tabs. + The main things to know about are the link in the `About` Section, and the `Code`, `Issues` and `Pull requests` tabs. Let's look at these in turn. ```{figure} ../../images/satre_specification_repo.png @@ -355,7 +355,7 @@ When you are commenting on Issues/PRs, there are a couple of handy things to kno Pull request number ``` -There will always be a dedicated Breakout Room in the Collaboration Cafés where one of the SATRE Team will be on hand to answer any questions and guide you through the GitHub Repository and help you get set up. +There will always be a dedicated Breakout Room in the Collaboration Cafés where one of the SATRE Team will be on hand to answer any questions, guide you through the GitHub Repository, and help you get set up. ### Contribute via alternate streams diff --git a/docs/source/index.md b/docs/source/index.md index 18f6a6ca..bdbae0d4 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -53,7 +53,7 @@ Personal or sensitive data which have been collected for operational, commercial TREs are designed to enable access to sensitive data only for authorised projects and researchers, whilst minimising risk of data release or exposure. Influential reports from DARE UK and Health Data Research UK, together with the UK Government Goldacre review and ‘Data Saves Lives’ policy paper, have all highlighted the need for change in how sensitive data are handled. -The SATRE team contains representatives from several existing UK TREs, which between them host many different types of sensitive data. +The SATRE team contains representatives from several existing UK TREs, which host many different types of sensitive data. We will use the reference architecture specified here to bring these into closer alignment and make it easy for others to do the same. This supports DARE UK's aim of developing a coordinated national data research infrastructure. diff --git a/docs/source/pillars/computing_technology.md b/docs/source/pillars/computing_technology.md index 814e2c2f..c1862626 100644 --- a/docs/source/pillars/computing_technology.md +++ b/docs/source/pillars/computing_technology.md @@ -44,7 +44,7 @@ _The interfaces used for interacting with the TRE management system and the TRE A TRE may allow user to paste text into a workspace. - Recommended * - A TRE could restrict data access from researchers entirely and provide an interface for submitting code. - - For example, you might use a system where users submit jobs which run over the data and return results without allowing direct data acces. + - For example, you might use a system where users submit jobs that run over the data and return results without allowing direct data access. - Optional ``` @@ -74,7 +74,7 @@ _The tools used by researchers inside a TRE, such as programming languages, IDEs This may include version control software, and tools for developing and running data analysis pipelines. - Recommended * - Your TRE should, where possible, automatically apply security related updates for user software. - - Reducing the risk of expoitable vulnerabilities in installed software will increase the security of your TRE. + - Reducing the risk of exploitable vulnerabilities in installed software will increase the security of your TRE. - Recommended * - Your TRE could provide shared services that are accessible to users in the same project. - This may include shared file storage, databases, collaborative writing, and other web applications. @@ -85,7 +85,7 @@ _The tools used by researchers inside a TRE, such as programming languages, IDEs Similarly a subset of public containers could be made available, or individual container images via an internal container registry. - Optional * - Your TRE could include licenced commercial software if required by researchers, but additional risks must be recorded and mitigated where neccesary. - - For example, if an application must connect to an external licensing server TREs must be confident that only licensing information is sent to this server, and that any network proxies to allow this are secured. + - For example, if an application must connect to an external licensing server, you must be confident that only licensing information is sent to this server, and that any network connections are secure. - Optional ``` @@ -142,8 +142,8 @@ _The ability of the TRE operator to record and analyse data about the usage of t * - Your TRE must record usage data. - This may include the number of users, number of projects, the amount of data stored, number of datasets, the number of workspaces, etc. - Mandatory -* - Your TRE should record which datasets are accessed, when and by who. - - This helps maintain auditability of how sensitive data has been used +* - Your TRE should record which datasets are accessed, when and by whom. + - This helps maintain auditability of how sensitive data has been used. - Recommended * - Your TRE should record computational resource usage at the user or aggregate level. - This is useful for optimising allocation of resources, and managing costs. @@ -161,7 +161,7 @@ _The ability of the TRE operator to administer and secure network infrastructure * - Statement - Guidance - Importance -* - Your TRE must control and manage any internal and external network infrastructure in order to protect information in systems and applications. +* - Your TRE must control and manage all of its network infrastructure in order to protect information in systems and applications. - Network infrastructure must prevent unauthorised access to resources on the network. This may include firewalls, network segmentation, and restricting connections to the network. - Mandatory diff --git a/docs/source/pillars/data_management.md b/docs/source/pillars/data_management.md index dffbb2e1..57c73a9d 100644 --- a/docs/source/pillars/data_management.md +++ b/docs/source/pillars/data_management.md @@ -44,7 +44,7 @@ _The ability of the TRE operator to manage how and where data is stored, how it - There may be cases where there are multiple stakeholders for a piece of analysis including data providers, data analysts, data subjects, the TRE operator. A data egress process may then require approval from people not on the project team, for example an external referee or TRE operator representative - Optional -* - You must keep a record of what data it holds. +* - You must keep a record of what data your TRE holds. - Good records are important for ensuring compliance with legislation, understanding risk and aiding good data hygiene. The record should include a description of the data, its source, contact details for the data owner, which projects use the data, the date it was received, when it is expected to no longer be needed. - Mandatory @@ -56,7 +56,7 @@ _The ability of the TRE operator to manage how and where data is stored, how it - Mandatory * - You could keep backups of data and research environments, provided that this is permitted by law. - Keeping backups could help reduce the impact of events like accidental deletion and data corruption on work in a TRE. - TRE developers may want to consider how different elements, for example sensitive input data or users workspaces, may be backed up or if they should be. + TRE developers may want to consider how different elements such as sensitive input data or users' workspaces may be backed up, and whether they should be. - Optional * - You should log how input data is modified. - If the input data is mutable a TRE should keep records of its modification. @@ -72,7 +72,7 @@ _The ability of the TRE operator to manage how and where data is stored, how it ## Identity and access management -_The ability of the TRE operator to ensure the right people (identities) can access the tools and data they need, and no more._ +_The ability of the TRE operator to ensure the right people (identities) can only access the tools and data they need._ ```{list-table} :header-rows: 1 @@ -85,7 +85,7 @@ _The ability of the TRE operator to ensure the right people (identities) can acc - It is important that each user account should be used by one, and only one, person in order to facilitate the assignment of roles or permissions and to log the actions of individuals. - Mandatory * - You must be reasonably convinced of the identity of each person being granted an account. - - It is important to ensure access, via an account, has been given to the correct person. + - It is important to ensure an account has been given to the correct person. For example, multiple credentials may be used before account creation to verify identity or, when appropriate, photo ID checks may be required. - Mandatory * - You must restrict a user's access to only data required in their work. @@ -97,7 +97,7 @@ _The ability of the TRE operator to ensure the right people (identities) can acc Categories include something the user knows (_e.g._ a password), something the user possesses (_e.g._ a TOTP key) or something the user is (_e.g._ biometric data). A TRE does not need to implement multi-factor authentication checks itself if it is provided by a third-party identity provider. - Mandatory -* - You could use federated authentication/ single sign-on (SSO) for user login. +* - You could use federated authentication or single sign-on (SSO) for user login. - Institutions that use a SSO for other applications may wish to extend this login capability to a TRE. This will simplify the login process for researchers using a TRE and prevent them having to remember or store multiple login credentials. - Optional @@ -118,7 +118,7 @@ _The ability of the TRE operator to ensure outputs are safely published and shar * - Statement - Guidance - Importance -* - You should have a system to aid in classifying outputs. +* - You should have a system to help classify outputs. - Removing data from a TRE can be a difficult process as there is potential for sensitive data to be revealed. Having guidance, processes and methods will help ensure that outputs are correctly classified and, furthermore, that outputs due to be openly published are identified. Encouraging openly published outputs rather than handing all outputs to the data provider will enhance a TRE's impact. @@ -153,7 +153,7 @@ _The ability to query and browse the data within an environment at various level ## Information security -This capability relates to the ability of the TRE operator to protect against the unauthorised use of information, especially electronic data. +_This capability relates to the ability of the TRE operator to protect against the unauthorised use of information, especially electronic data._ Measures taken to ensure information security can be further categorised into: @@ -213,10 +213,11 @@ _Security testing enables the TRE operator to gain assurance in the security of - Recommended * - You should update the security controls of your TRE based on the results of security tests. - Security testing can reveal bugs and discrepancies in the TRE architecture which should be addressed in advance of sensitive data being uploaded, or with urgency in the case of an operational TRE. - Regular testing will allow organisations to refine their TRE security controls and incident response capabilities, enabling them to adapt to any new security concerns that may arise as a result of changes in the underlying software. + Regular testing will allow organisations to refine their TRE security controls and incident response capabilities. + It enables them to adapt to any new security concerns that may arise as a result of changes in the underlying software. - Recommended * - You must have procedures in place for rapid incident response. - - There may well be legal requirements to disclose details of any incidents, _e.g._ data breaches for organisations subject to GDPR. + - There may be legal requirements to disclose details of any incidents, such as data breaches for organisations subject to GDPR. Having robust processes in place will ensure a swift and effective response when an incident occurs. - Mandatory * - You should publish details of your security testing strategy and, where possible, the results of each test. @@ -243,9 +244,9 @@ Here we define 'project' data as the data brought in for work which is very like * - Your TRE must encrypt project and user data at rest. - This prevents unauthorised access to the data even if the storage media is compromised. This may involve encrypted filesystems or tools to encrypt and decrypt data on demand. - The encryption keys may be managed by the TRE operator or by a trusted external actor (_e.g._ a cloud services provider). + The encryption keys may be managed by the TRE operator or by a trusted external actor, for example a cloud provider. - Mandatory -* - Your TRE must encrypt data when in transit between the TRE and the outside world. +* - Your TRE must encrypt data when in transit between the TRE and external networks or computers. - Data encryption must be used to safeguard against interception or tampering during transmission. This includes both data ingress and egress and users accessing the TRE, for example over a remote desktop or shell session. - Mandatory @@ -277,7 +278,8 @@ Physical security controls can provide TREs using highly sensitive data an extra - Guidance - Importance * - Your TRE could offer physical protection measures against data leakage or theft via physical means. - - Restricting access to research facilities containing computers logged into TREs can help prevent malicious actors from viewing or stealing sensitive data, for example by photographing a computer screen. Physical controls on access to a TRE could include surveillance systems, restricting access to locked rooms that limit entry to authorised personnel only, visitor management systems and employee training. + - Restricting access to research facilities containing computers logged into TREs can help prevent malicious actors from viewing or stealing sensitive data, for example by photographing a computer screen. + Physical controls on access to a TRE could include surveillance systems, restricting physical access to authorised personnel only, visitor management systems and employee training. - Optional * - Your TRE may need to comply with specific regulatory requirements if it is hosting particularly sensitive data. - Regulatory frameworks such as GDPR emphasise the need for physical security controls to protect sensitive data. From 991cce41bc1dde366073a23b1c831031da1379a0 Mon Sep 17 00:00:00 2001 From: James Robinson Date: Thu, 6 Jul 2023 11:48:16 +0100 Subject: [PATCH 7/9] :rotating_light: Fix linting --- docs/source/contributing/index.md | 2 +- docs/source/pillars/supporting.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index f874ff16..20313cc7 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -78,7 +78,7 @@ Issues should be used to discuss ideas, potential changes and to ask questions. Issue templates have been designed for common issue types to help collect the most important information and present it in a clear, consistent way. It is possible, however, to open a blank issue if none of the templates are suitable. -While we encourage opening issues, we understand that some may be more comfortable contributing ideas in other ways. +While we encourage opening issues, we understand that some may be more comfortable contributing ideas in other ways. We support other methods of contribution such as discussions and notes taken at SATRE Collaboration Cafés. The SATRE Team will aim to collate ideas and draft issues that welcome further discussion and attribute those involved in initial discussions. The SATRE Team will try to capture the ideas as accurately as possible, in good faith, and be guided by the SATRE Community to correct any misconceptions. diff --git a/docs/source/pillars/supporting.md b/docs/source/pillars/supporting.md index 208c9fd6..1347ff7a 100644 --- a/docs/source/pillars/supporting.md +++ b/docs/source/pillars/supporting.md @@ -90,7 +90,7 @@ _All activities aimed at the efficient and effective management of money (funds) - This includes knowing which costs are associated with which project, and having an appropriate charging mechanism in place in line with your organisational policy. - Recommended * - You should have a process in place to ensure your TRE provision remains financially sustainable. - - This could include having a cost recovery process in place, or setting up a long-term funding mechanism to support projects with TREs. + - This could include having a cost recovery process in place, or setting up a long-term funding mechanism to support projects with TREs. At any given time, you should have funds free to cover all potential foreseen TRE provision for at least 12 months. - Recommended * - You should minimise the cost of your TRE infrastructure wherever possible From 8f53f66bc878cef8756492307331f6a89ce592f8 Mon Sep 17 00:00:00 2001 From: James Robinson Date: Thu, 6 Jul 2023 12:54:10 +0100 Subject: [PATCH 8/9] :memo: Apply rewording from @JimMadge Co-authored-by: Jim Madge --- docs/source/contributing/index.md | 2 +- docs/source/contributing/walkthrough.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index 20313cc7..90d34eb5 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -178,7 +178,7 @@ It is best to add each contributor in turn and merge the pull request before add Otherwise, you can end up with merge conflicts. Please check the open pull requests first to make sure there aren't any [open requests from the bot](https://github.com/sa-tre/satre-specification/pulls/app%2Fallcontributors) before adding another. -What happens if you accidentally run the bot before the previous run was merged and you got those pesky merge conflicts? +What happens if you accidentally run the bot before the previous run was merged and you get those pesky merge conflicts? (Don't feel bad, we have all done it! 🙈) Simply close the pull request and delete the branch (`all-contributors/add-`). If you are unable to do this for any reason, please let us know by opening an issue, and SATRE team members will be very happy to help! diff --git a/docs/source/contributing/walkthrough.md b/docs/source/contributing/walkthrough.md index 8f08f368..ce140d2f 100644 --- a/docs/source/contributing/walkthrough.md +++ b/docs/source/contributing/walkthrough.md @@ -33,7 +33,8 @@ Typically, each Breakout Room is linked to an Issue on the [SATRE GitHub Issues :::{important} The HackMD for each Collaboration Café is made available in your calendar invites. We encourage you to propose a Breakout Room in advanced of the Collaboration Café, linking to a [SATRE GitHub Issue](https://github.com/sa-tre/satre-specification/issues) if possible. -This will help participants come prepared to talk about certain topics. We also welcome Breakout Room proposals on the day! +This will help participants come prepared to talk about certain topics. +We also welcome Breakout Room proposals on the day! ::: ## Review the SATRE Specification Document From c3c96fbdf70a465f163bf27bc9a2b7b331d03c9b Mon Sep 17 00:00:00 2001 From: Jim Madge Date: Thu, 6 Jul 2023 13:00:56 +0100 Subject: [PATCH 9/9] Update docs/source/pillars/computing_technology.md --- docs/source/pillars/computing_technology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/pillars/computing_technology.md b/docs/source/pillars/computing_technology.md index c1862626..68d38c58 100644 --- a/docs/source/pillars/computing_technology.md +++ b/docs/source/pillars/computing_technology.md @@ -142,7 +142,7 @@ _The ability of the TRE operator to record and analyse data about the usage of t * - Your TRE must record usage data. - This may include the number of users, number of projects, the amount of data stored, number of datasets, the number of workspaces, etc. - Mandatory -* - Your TRE should record which datasets are accessed, when and by whom. +* - Your TRE should record which datasets are accessed, when and by who. - This helps maintain auditability of how sensitive data has been used. - Recommended * - Your TRE should record computational resource usage at the user or aggregate level.