Skip to content

Commit f1cb8b9

Browse files
mlysaght2017mlysaght2017
authored
add(docs): add in guide on how to prepare threats and controls for release candidate (#705)
1 parent 6b1642a commit f1cb8b9

File tree

1 file changed

+167
-0
lines changed

1 file changed

+167
-0
lines changed

‎docs/community-guidelines/content-standards-and-practices/staging-for-a-release-candidate.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# How to Prepare a Service for a Release Candidate
2+
3+
This guide explains how to audit and update threats and controls for a specific cloud service in the FINOS Common Cloud Controls project, ensuring it is ready to be released. By following these steps, contributors will produce high-quality, consistent outputs aligned with our “common” and “service-specific” model.
4+
5+
---
6+
7+
## Table of Contents
8+
9+
- [How to Prepare a Service for a Release Candidate](#how-to-prepare-a-service-for-a-release-candidate)
10+
- [Table of Contents](#table-of-contents)
11+
- [Overview](#overview)
12+
- [Conceptual Diagram](#conceptual-diagram)
13+
- [Key Points](#key-points)
14+
- [Preparing Threats](#preparing-threats)
15+
- [Preparing Controls](#preparing-controls)
16+
- [Final Checks and Pull Request](#final-checks-and-pull-request)
17+
- [Additional Resources](#additional-resources)
18+
19+
---
20+
21+
## Overview
22+
23+
When preparing a cloud service (e.g., `services/networking/loadbalancer`) for a release candidate, you will:
24+
25+
1. **Identify & validate existing threats** (both common and service-specific).
26+
2. **Remove duplicates** by leveraging the “common-threats” reference.
27+
3. **Identify & validate existing controls** (both common and service-specific).
28+
4. **Remove duplicates** by leveraging the “common-controls” reference.
29+
5. **Confirm ID ordering** and naming consistency.
30+
6. **Ensure adherence to style guides** for threats and controls.
31+
32+
Perform these tasks in the `threats.yaml` and `controls.yaml` files located under the service you’re auditing or in new files if they do not yet exist.
33+
34+
---
35+
36+
## Conceptual Diagram
37+
38+
### Key Points
39+
40+
- **Common artifacts** (Features, Threats, Controls) are designed to be reusable across multiple services.
41+
- **Service-specific artifacts** build on or refine the common artifacts where the needs of the service differ from the norm.
42+
- When preparing for a release candidate, **minimize duplication** by referencing the common artifacts whenever possible.
43+
44+
---
45+
46+
## Preparing Threats
47+
48+
Threats for a given service typically reside in a `threats.yaml` file (e.g., `services/networking/loadbalancer/threats.yaml`). If none exists, create a new file.
49+
50+
1. **Check Alignment With Service Features**
51+
52+
- Open `features.yaml` in the same directory (e.g., `services/networking/loadbalancer/features.yaml`).
53+
- Ensure existing threats in `threats.yaml` correspond to these features. Confirm IDs, titles, and descriptions are consistent and relevant.
54+
55+
2. **Add Any Missing Common Threats**
56+
57+
- Review the [common-threats.yaml](https://github.com/finos/common-cloud-controls/blob/main/services/common-threats.yaml) to see the full list of common threats.
58+
- In `threats.yaml`, find or create a top-level `common_threats` key.
59+
- Add references to any relevant common threats not already included.
60+
- See an example of a fully populated list in the [object storage threats.yaml](https://github.com/finos/common-cloud-controls/blob/main/services/storage/object/threats.yaml).
61+
62+
3. **Add Any Missing Service-Specific Threats**
63+
64+
- Under the top-level `threats` list, define any threats unique to this service that are not already captured as “common threats.”
65+
- Use the object storage example (linked above) as a guide.
66+
67+
4. **Remove Duplications**
68+
69+
- If a threat already exists in `common-threats.yaml` but is also listed separately under `threats`, move or reference it under `common_threats` and remove the duplicate.
70+
- This step ensures we don’t maintain two versions of the same threat.
71+
72+
5. **Check ID Ordering**
73+
74+
- IDs for threats should be sequential and grouped properly.
75+
- Make sure newly added items fit into the numerical sequence without breaking existing references.
76+
77+
6. **Final Review Against the Style Guide**
78+
- Refer to the [Threat Definitions Style Guide](https://github.com/finos/common-cloud-controls/blob/main/docs/community-guidelines/content-standards-and-practices/threat-definitions.md).
79+
- Check titles, descriptions, and formatting match these standards.
80+
81+
---
82+
83+
## Preparing Controls
84+
85+
Controls for a given service typically reside in a `controls.yaml` file (e.g., `services/networking/loadbalancer/controls.yaml`). If none exists, create a new file.
86+
87+
1. **Check Alignment With Threats**
88+
89+
- Ensure that every threat in `threats.yaml` is appropriately mitigated by at least one control in `controls.yaml` (or by a “common control” reference).
90+
- Verify IDs, titles, and descriptions match the relevant threats where applicable.
91+
92+
2. **Add Any Missing Common Controls**
93+
94+
- Review the [common-controls.yaml](https://github.com/finos/common-cloud-controls/blob/main/services/common-controls.yaml).
95+
- In your `controls.yaml`, find or create a top-level `common_controls` key.
96+
- Add references to any relevant common controls not already included.
97+
- See the [object storage controls.yaml](https://github.com/finos/common-cloud-controls/blob/main/services/storage/object/controls.yaml) for an example.
98+
99+
3. **Add Any Missing Service-Specific Controls**
100+
101+
- Under the `controls` list, add controls that are specific to your service’s unique threats or features.
102+
- Ensure each new control has a clear and accurate title, description, and testing requirement if appropriate.
103+
104+
4. **Remove Duplications**
105+
106+
- If a control is already provided in `common-controls.yaml` but also exists as a service-specific control, migrate or reference it under `common_controls` and remove the duplicate from `controls`.
107+
108+
5. **Check ID Ordering**
109+
110+
- Ensure the IDs are in the correct numerical order and don’t conflict with existing controls.
111+
112+
6. **Final Review Against the Style Guide**
113+
- Refer to the [Control Definitions Style Guide](https://github.com/finos/common-cloud-controls/blob/main/docs/community-guidelines/content-standards-and-practices/control-definitions.md).
114+
- Validate all controls and their testing requirements align with these standards.
115+
116+
---
117+
118+
## Final Checks and Pull Request
119+
120+
1. **Create or Update the Files**
121+
122+
- Commit your updated or newly created `threats.yaml` and `controls.yaml` to a feature branch.
123+
124+
2. **Self-Review**
125+
126+
- Confirm all the boxes in the [Preparing Threats](#preparing-threats) and [Preparing Controls](#preparing-controls) sections are checked.
127+
- Ensure the numbering and referencing are accurate.
128+
129+
3. **Open a Pull Request**
130+
131+
- Submit a PR from your feature branch to the main branch of the [finos/common-cloud-controls](https://github.com/finos/common-cloud-controls) repository.
132+
- Reference the relevant issue (e.g., “resolves #12345”) and summarize your changes.
133+
134+
4. **Request Review**
135+
136+
- Assign members of the Security Working Group or other relevant maintainers.
137+
- Incorporate feedback where needed.
138+
139+
5. **Merge**
140+
- Once approved, merge your PR. Your service is now ready for the release candidate!
141+
142+
---
143+
144+
## Additional Resources
145+
146+
- **Common Threats**
147+
[services/common-threats.yaml](https://github.com/finos/common-cloud-controls/blob/main/services/common-threats.yaml)
148+
149+
- **Common Controls**
150+
[services/common-controls.yaml](https://github.com/finos/common-cloud-controls/blob/main/services/common-controls.yaml)
151+
152+
- **Example Completed Service**
153+
154+
- Threats: [services/storage/object/threats.yaml](https://github.com/finos/common-cloud-controls/blob/main/services/storage/object/threats.yaml)
155+
- Controls: [services/storage/object/controls.yaml](https://github.com/finos/common-cloud-controls/blob/main/services/storage/object/controls.yaml)
156+
157+
- **Style Guides**
158+
159+
- [Threat Definitions](https://github.com/finos/common-cloud-controls/blob/main/docs/community-guidelines/content-standards-and-practices/threat-definitions.md)
160+
- [Control Definitions](https://github.com/finos/common-cloud-controls/blob/main/docs/community-guidelines/content-standards-and-practices/control-definitions.md)
161+
162+
- **Contact & Discussion**
163+
- If you have questions or need clarification, contact the Security Working Group or open a discussion/issue on the repository.
164+
165+
---
166+
167+
**Thank you for contributing to the FINOS Common Cloud Controls project!** By following these guidelines, you help ensure that each service’s threats and controls are consistent, complete, and ready for a smooth release.

0 commit comments

Comments
 (0)