Issue 533: Update developer documentation

docs/contributors_guide.md

@@ -0,0 +1,97 @@
+# Contributors Guide
+
+## Overview
+
+This file holds general documentation relevant to contributing to the Common Cloud Controls project such as [project structure](#project-structure) and [VSCode](#vscode-1) information. For more specific documentation on contributing to the GitHub repository please see the [GitHub specific documentation](/.github/CONTRIBUTING.md). This is a working document and as such if you feel there is information missing please highlight it using the [issue section of the GitHub repository](https://github.com/finos/common-cloud-controls/issues).
+
+## Project structure
+
+This section provides a high-level overview of the project structure.
+
+### Top level
+
+- [.gitignore](https://git-scm.com/docs/gitignore): Standard ignore file for exclusion of files from source control.
+- [.gitvote.yml](https://github.com/cncf/gitvote): config file for GitVote.
+- [.prettierignore](https://prettier.io/): paths to exclude from prettier checks.
+- [Governance.md](/Governance.md):
+
+### .config
+
+The [`.config`](/.config) directory contains config for various tooling used in the project, e.g. [prettier](<(https://prettier.io/)>) and [markdownlint](https://github.com/DavidAnson/markdownlint).
+
+### .github
+
+The [`.github`](/.github) directory contains documents relevant specifically to github. These include the [CODEOWNERS](/.github/CODEOWNERS) file, documentation on [contributing](/.github/CONTRIBUTING.md) to the repository, [workflow](https://docs.github.com/en/actions/writing-workflows/about-workflows) definitions and [issue templates](/.github/ISSUE_TEMPLATE) for various common [github issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) such as meeting minutes.
+
+### .vscode
+
+The [`.vscode`](/.vscode) directory contains files and configuration specific to the [vscode](https://code.visualstudio.com/docs/getstarted/settings) text editor. These include, settings, extensions and [snippet definitions](#snippets).
+
+### Delivery Tooling
+
+The [`delivery-tooling`](/delivery-tooling/) directory contains a selection of [`.go`](https://go.dev/) tooling and markdown files for use with creating a release.
+
+### Documentation
+
+The [`docs`](/docs/) directory is a centralised store for all documentation related to the project (excluding the top-level [README](/README.md) file). It contains information on the community guidelines, community policies, detailed information on governance, including the various [working groups](/docs/governance/working-groups/). The documentation directory also contains information on various reusable [resources](/docs/resources/readme.md) utilised in the project.
+
+### Schemas
+
+The [`schemas`](/schemas) directory contains the yaml validation schemas used in the project. Yaml validation schemas have been created for controls, features, metadata and threats files, to ensure that contributions follow the approved structure and contain required values.
+
+### Services
+
+The [`services`](/services/) directory is the main working directory of the project. It contains a list of common cloud services organised in a hierarchical way from high level resource type first becoming more granular. For example:
+
+```ascii
+services/
+└── database/
+    └── relational/
+    └── warehouse/
+```
+
+Each resource should contain the following files in `.yaml` format:
+
+- `controls.yaml`: The common compliance controls for the resource.
+- `features.yaml`: The common features which define the resource.
+- `threats.yaml`: The security threats related to the resource.
+- `metadata.yaml`: Metadata on the resource such as resource details.
+
+The resource should also contain a `tests` directory containing details on how to test the resource is compliant.
+
+The top level of the `services` directory contains `yaml` files for common controls, features and threats which are common to multiple resources. It also contains the [`service-families.yaml`](/services/service-families.yaml) file which documents the service families and their descriptions.
+
+## VSCode
+
+### Snippets
+
+[VSCode snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets) are defined for common [features](../.vscode/common-features.code-snippets), [threats](../.vscode/common-threats.code-snippets) and [controls](../.vscode/common-controls.code-snippets).
+To make use of these snippets start typing the snippet prefix in any `yaml` file and VSCode will offer you the option to auto-complete the snippet e.g.
+
+```yaml
+CF3
+```
+
+![snippet](/docs/resources/snippet.gif)
+
+### YAML Schema validation
+
+By default, the contents of `.vscode/settings.json` should automatically be considered by Visual Studio Code. In-line suggestions should appear in the event that your file is not compatible with the corresponding schema.
+
+If this does not satisfy your use case for some reason, you can update your global VSCode settings to highlight issues using the schema files with the following steps:
+
+1. Install VSCode [Red Hat YAML extension](https://github.com/redhat-developer/vscode-yaml)
+2. Under VSCode `settings.json` add the following (or your local equivalent):
+
+   ```json
+       "yaml.schemas": {
+           "file:///<PATH_TO_CCC_REPO>/common-cloud-controls/schemas/controls-schema.json": "controls.yaml",
+           "file:///<PATH_TO_CCC_REPO>/common-cloud-controls/schemas/features-schema.json": "features.yaml",
+           "file:///<PATH_TO_CCC_REPO>/common-cloud-controls/schemas/metadata-schema.json": "metadata.yaml",
+           "file:///<PATH_TO_CCC_REPO>/common-cloud-controls/schemas/threats-schema.json": "threats.yaml"
+       }
+   ```
+
+3. Save these settings and reload VSCode.
+
+![yaml](/docs/resources/yaml-validate.gif)

services/database/relational/threats.yaml

@@ -16,8 +16,8 @@ threats:
     title: Unauthorized Access to Database
     description: A threat actor gains unauthorized access to the cloud relational database by using a compromised role or using default administrative credentials.
     features:
-      - CCC.RDMS.F01  # SQL Support
-      - CCC.F06       # Identity Based Access Control
+      - CCC.RDMS.F01 # SQL Support
+      - CCC.F06 # Identity Based Access Control
     mitre_technique:
       - TA0006
       - T1552
@@ -26,9 +26,9 @@ threats:
     title: Unauthorized Cross Organization Snapshot Collection
     description: A threat actor initiates a snapshot collection activity using a privileged role and copies the snapshot outside of the organization, which allows for data exfiltration and theft.
     features:
-      - CCC.F11       # Backup
-      - CCC.F12       # Recovery
-      - CCC.F21       # Replication
+      - CCC.F11 # Backup
+      - CCC.F12 # Recovery
+      - CCC.F21 # Replication
     mitre_technique:
       - TA0009
       - T1530
@@ -37,8 +37,8 @@ threats:
     title: Disabled Logging & Monitoring
     description: A threat actor disables the logging and monitoring of the relational database, which allows evasion and removes traces of malicious actions.
     features:
-      - CCC.F10       # Logging
-      - CCC.F09       # Monitoring
+      - CCC.F10 # Logging
+      - CCC.F09 # Monitoring
     mitre_technique:
       - TA0005
       - T1562
@@ -47,9 +47,9 @@ threats:
     title: Unauthorized Configuration Modification
     description: A threat actor attempts to make changes to the configuration of the cloud RDMS with a malicious role.
     features:
-      - CCC.RDMS.F01  # SQL Support
-      - CCC.F06       # Identity Based Access Control
-      - CCC.F13       # Infrastructure as Code
+      - CCC.RDMS.F01 # SQL Support
+      - CCC.F06 # Identity Based Access Control
+      - CCC.F13 # Infrastructure as Code
     mitre_technique:
       - TA0004
       - T1548
@@ -58,8 +58,8 @@ threats:
     title: Unencrypted Connection To Database
     description: An end-user connects to the database over HTTP, which is susceptible to network sniffing attacks and other exploits.
     features:
-      - CCC.F01       # Encryption in Transit
-      - CCC.F02       # Encryption at Rest
+      - CCC.F01 # Encryption in Transit
+      - CCC.F02 # Encryption at Rest
     mitre_technique:
       - TA0006
       - T1040
@@ -68,8 +68,8 @@ threats:
     title: Snapshot Collection with Unauthorized Encryption Key
     description: A threat actor attempts to perform snapshot collection using a non-default encryption key associated with the RDMS.
     features:
-      - CCC.F11       # Backup
-      - CCC.F12       # Recovery
+      - CCC.F11 # Backup
+      - CCC.F12 # Recovery
     mitre_technique:
       - TA0009
       - T1530