1---
2layout: page
3title: Control Catalog Guide
4description: Step-by-step guide to creating Gemara-compatible control catalogs
5---
6
7## What This Is
8
9This guide walks through creating a **control catalog** using the [Gemara](https://gemara.openssf.org/) project, building on the threats and scope you identified in the [Threat Assessment Guide](threat-assessment-guide).
10
11In technical terms:
12* **Controls** are safeguards with a stated objective and a list of assessment requirements.
13* **Groups** group related controls by domain (e.g., supply chain, access control).
14* **Threats** link each control to the threat(s) it mitigates, connecting your control catalog to your layer 2 threat catalog.
15
16This exercise produces a structured way to develop control objectives and corresponding testable conditions to determine if the objective is met.
17
18## Optional Workflow
19
20Complete the [Threat Assessment Guide](threat-assessment-guide) for your scope (e.g., the container management tool **SEC.SLAM.CM**). You can reference the linked `threats` and `guidelines` to support the intent of Controls in the catalog.
21
22
23## Walkthrough
24
25### Step 0: Define Scope and References
26
27Reuse the same component or technology as your threat assessment. You will reference that threat catalog so controls can map to the threats you identified.
28
29**Leverage existing resources**: As with threat catalogs, you can import controls from external catalogs (e.g., FINOS Common Cloud Controls, OSPS Baseline) via `mapping-references` and list imported controls in your catalog.
30
31We continue with the container management tool example (SEC.SLAM.CM) and assume a threat catalog for it already exists.
32
33### Step 1: Setting Up Metadata
34
35Declare your control catalog and mapping references. Key fields:
36
37| Field | What It Is | Why |
38|-------------------------------------|--------------------------------------------------------------|-------------------------------------------------------------------------------------------|
39| `title` | Display name for the control catalog (top-level field) | Human-readable label used in reports and tooling output |
40| `mapping-references` with `id: CCC` | Optional pointer to CCC or another control/threat catalog | Resolve imported capability and control IDs from the referenced catalog |
41| `applicability-groups` | List of groups (id, title, description) for when controls apply | Scope assessment requirements by context (e.g., production, CI/CD) so evaluators know when each requirement applies |
42
43> **Note:** Applicability groups must be defined to assign applicability to controls.
44
45**Example (YAML):**
46
47```yaml
48title: Container Management Tool Security Control Catalog
49metadata:
50 id: SEC.SLAM.CM
51 description: Control catalog for container management tool security; mitigates threats from the SEC.SLAM.CM threat catalog.
52 version: 1.0.0
53 author:
54 id: example
55 name: Example
56 type: Human
57 mapping-references:
58 - id: SEC.SLAM.CM
59 title: Container Management Tool Security Threat Catalog
60 version: "1.0.0"
61 url: file://threats.yaml
62 description: |
63 Threat catalog for the same scope; provides threat IDs for threat-mappings.
64 - id: CCC
65 title: Common Cloud Controls Core
66 version: v2025.10
67 url: https://github.com/finos/common-cloud-controls/releases
68 description: |
69 Foundational repository of reusable security controls, capabilities,
70 and threat models maintained by FINOS.
71 applicability-groups:
72 - id: production
73 title: Production
74 description: |
75 Production container workloads and clusters; controls apply to
76 live environments where security posture is enforced.
77 - id: all_deployments
78 title: All Deployments
79 description: |
80 Requirements that apply whenever container images are built, pulled, or run—
81 regardless of environment (dev, staging, production) or pipeline stage.
82 - id: untrusted_networks
83 title: Untrusted Networks
84 description: |
85 Applies when registry or image traffic traverses untrusted networks.
86 - id: ci_cd
87 title: CI/CD
88 description: |
89 Applies in continuous integration and deployment pipelines.
90```
91
92### Step 2: Define Control Groups
93
94**Groups** group controls by theme. The Layer 2 schema requires at least one group when the catalog defines its own `controls`. Each control's `group` field must match the `id` of one of these groups.
95
96Required fields for each group (see `base.cue`):
97
98| Field | Required | Description |
99|---------------|----------|----------------------------------------------|
100| `id` | Yes | Unique identifier referenced by controls |
101| `title` | Yes | Short name for the group |
102| `description` | Yes | Explanation of what controls in this group address |
103
104**Example (YAML):**
105
106```yaml
107groups:
108 - id: SEC.SLAM.CM.FAM01
109 title: Image Integrity and Supply Chain
110 description: |
111 Controls that ensure container images are authentic, unmodified,
112 and from trusted sources throughout retrieval and use.
113```
114
115### Step 3: Import or Define Controls
116
117> **Note:** For how controls are automatically pulled into policy to mitigate high-severity risks, see the FAQ.
118
119
120**Option A — Import Controls:** If an external catalog (e.g., CCC) defines controls that address your threats, reference it in the `mapping-references` and list the control IDs in `imports.controls`.
121
122**Example (YAML):**
123
124```yaml
125imports:
126 controls
127 - reference-id: CCC
128 entries:
129 - reference-id: CCC.Core.CTL42
130 remarks: Image signing and verification
131```
132
133**Option B — Define your own controls:** For controls specific to your scope, define them under `controls`. Required and common fields (see `layer-2.cue`):
134
135| Field | Required | Description |
136|--------------------------|----------|-----------------------------------------------------------------------------|
137| `id` | Yes | Unique identifier (e.g., `ORG.PROJ.COMPONENT.CTL##`) |
138| `title` | Yes | Short name describing the control |
139| `objective` | Yes | Unified statement of intent for the control |
140| `group` | Yes | `id` of a group in this catalog (or in a referenced catalog for imports) |
141| `assessment-requirements`| Yes | List of verifiable conditions; each has `id`, `text`, `applicability` |
142| `threats` | No | Links to threat catalog(s) and threat IDs this control mitigates |
143| `state` | Yes | Lifecycle: `Active` (default), `Draft`, `Deprecated`, `Retired` |
144
145Each **assessment requirement** (see `layer-2.cue`) must have:
146
147| Field | Required | Description |
148|-----------------|----------|-----------------------------------------------------------------------------|
149| `id` | Yes | Unique within the control (e.g., `SEC.SLAM.CM.CTL01.AR01`) |
150| `text` | Yes | Verifiable condition (typically a MUST statement) |
151| `applicability` | Yes | List of strings describing when this requirement applies |
152
153**Example (YAML):**
154
155```yaml
156controls:
157 - id: SEC.SLAM.CM.CTL01
158 title: Use Immutable Image References by Digest
159 objective: |
160 Require signature validation so that only legitimate, trusted images are
161 accepted; then pin each image to an immutable digest (e.g., sha256)
162 after the check so that what is used matches what was verified and
163 TOCTOU (time-of-check to time-of-use) attacks are prevented.
164 threats:
165 - reference-id: SEC.SLAM.CM
166 entries:
167 - reference-id: SEC.SLAM.CM.THR01
168 - reference-id: SEC.SLAM.CM.THR03
169 - reference-id: SEC.SLAM.CM.THR04
170 - reference-id: CCC
171 entries:
172 - reference-id: CCC.Core.TH14
173 - id: SEC.SLAM.CM.CTL02
174 title: Require TLS/SSL with Certificate Pinning
175 objective: |
176 Mitigate MITM Container Image Interception by protecting registry traffic and verifying artifact integrity: use
177 TLS/SSL with certificate pinning for all registry communication, use VPNs on untrusted networks to reduce interception risk, and verify artifact signatures or hashes so that tampered or redirected content is detected even if the channel is compromised.
178 threats:
179 - reference-id: SEC.SLAM.CM
180 entries:
181 - reference-id: SEC.SLAM.CM.THR02
182 - reference-id: CCC
183 entries:
184 - reference-id: CCC.Core.TH02
185 group: SEC.SLAM.CM.FAM01
186 state: Active
187 assessment-requirements:
188 - id: SEC.SLAM.CM.CTL02.AR01
189 text: |
190 The system MUST use TLS/SSL for all registry communication and MUST pin to the expected server certificate or public key (or certificate chain) for the registry.
191 applicability: ["all_deployments"]
192 state: Active
193 - id: SEC.SLAM.CM.CTL02.AR02
194 text: |
195 On untrusted networks, the system or deployment pipeline MUST use a VPN or other trusted path for registry traffic, or MUST restrict
196 image pulls to environments where the network is trusted.
197 applicability: ["untrusted_networks", "ci_cd"]
198 state: Active
199 - id: SEC.SLAM.CM.CTL02.AR03
200 text: |
201 The system MUST verify artifact signatures or hashes (e.g. signature verification, digest check) before use so that tampered or redirected artifacts are rejected.
202 applicability: ["all_deployments"]
203 state: Active
204```
205
206### Step 4: Validate Against the Layer 2 Schema
207
208Validate the final catalog with CUE:
209
210**Validation commands:**
211
212```bash
213go install cuelang.org/go/cmd/cue@latest
214cue vet -c -d '#ControlCatalog' github.com/gemaraproj/gemara@latest your-control-catalog.yaml
215```
216
217Fix any reported errors (e.g., missing required fields, invalid `group` reference, or malformed `threats`) so the catalog is schema-consistent.
218
219### Step 5: Assemble the Full Catalog and Validate
220
221Combine metadata, mapping-references, groups, imported-controls (if any), and controls into a single YAML document. A complete, schema-valid catalog for the SEC.SLAM.CM scenario is in [control-catalog.yaml](control-catalog.yaml) in this directory.
222
223**Complete example (SEC.SLAM.CM):**
224
225```yaml
226title: Container Management Tool Security Control Catalog
227
228metadata:
229 id: SEC.SLAM.CM
230 description: |
231 Control catalog for container management tool security; mitigates threats
232 from the SEC.SLAM.CM threat catalog.
233 version: 1.0.0
234 author:
235 id: example
236 name: Example
237 type: Human
238 mapping-references:
239 - id: SEC.SLAM.CM
240 title: Container Management Tool Security Threat Catalog
241 version: "1.0.0"
242 url: https://example.org/catalogs/SEC.SLAM.CM-threats.yaml
243 description: |
244 Threat catalog for the same scope; provides threat IDs for threat-mappings.
245 - id: CCC
246 title: Common Cloud Controls Core
247 version: v2025.10
248 url: https://github.com/finos/common-cloud-controls/releases
249 description: |
250 Foundational repository of reusable security controls, capabilities,
251 and threat models maintained by FINOS.
252 applicability-groups:
253 - id: production
254 title: Production
255 description: |
256 Production container workloads and clusters; controls apply to
257 live environments where security posture is enforced.
258 - id: all_deployments
259 title: All Deployments
260 description: |
261 Requirements that apply whenever container images are built, pulled, or run—
262 regardless of environment (dev, staging, production) or pipeline stage.
263 - id: untrusted_networks
264 title: Untrusted Networks
265 description: |
266 Applies when registry or image traffic traverses untrusted networks.
267 - id: ci_cd
268 title: CI/CD
269 description: |
270 Applies in continuous integration and deployment pipelines.
271
272groups:
273 - id: SEC.SLAM.CM.FAM01
274 title: Image Integrity and Supply Chain
275 description: |
276 Controls that ensure container images are authentic, unmodified, and from trusted sources throughout retrieval and use.
277
278imports:
279 controls:
280 - reference-id: CCC
281 entries:
282 - reference-id: CCC.Core.CTL42
283 remarks: Image signing and verification
284
285controls:
286 - id: SEC.SLAM.CM.CTL01
287 title: Use Immutable Image References by Digest
288 objective: |
289 Require signature validation so that only legitimate, trusted images are accepted; then pin each image to an immutable digest (e.g., sha256) after the check so that what is used matches what was verified and TOCTOU (time-of-check to time-of-use) attacks are prevented.
290 threats:
291 - reference-id: SEC.SLAM.CM
292 entries:
293 - reference-id: SEC.SLAM.CM.THR01
294 - reference-id: SEC.SLAM.CM.THR03
295 - reference-id: SEC.SLAM.CM.THR04
296 - reference-id: CCC
297 entries:
298 - reference-id: CCC.Core.TH14
299 - id: SEC.SLAM.CM.CTL02
300 title: Require TLS/SSL with Certificate Pinning
301 objective: |
302 Mitigate MITM Container Image Interception by protecting registry traffic and verifying artifact integrity: use
303 TLS/SSL with certificate pinning for all registry communication, use VPNs on untrusted networks to reduce interception risk, and verify artifact signatures or hashes so that tampered or redirected content is detected even if the channel is compromised.
304 threats:
305 - reference-id: SEC.SLAM.CM
306 entries:
307 - reference-id: SEC.SLAM.CM.THR02
308 - reference-id: CCC
309 entries:
310 - reference-id: CCC.Core.TH02
311 group: SEC.SLAM.CM.FAM01
312 state: Active
313 assessment-requirements:
314 - id: SEC.SLAM.CM.CTL02.AR01
315 text: |
316 The system MUST use TLS/SSL for all registry communication and MUST pin to the expected server certificate or public key (or certificate chain) for the registry.
317 applicability: ["all_deployments"]
318 state: Active
319 - id: SEC.SLAM.CM.CTL02.AR02
320 text: |
321 On untrusted networks, the system or deployment pipeline MUST use a VPN or other trusted path for registry traffic, or MUST restrict image pulls to environments where the network is trusted.
322 applicability: ["untrusted_networks", "ci_cd"]
323 state: Active
324 - id: SEC.SLAM.CM.CTL02.AR03
325 text: |
326 The system MUST verify artifact signatures or hashes (e.g. signature verification, digest check) before use so that tampered or redirected artifacts are rejected.
327 applicability: ["all_deployments"]
328 state: Active
329```
330
331**Validate** from the repo root:
332
333```bash
334cue vet -c -d '#ControlCatalog' ./layer-2.cue ./metadata.cue ./mapping.cue ./base.cue docs/tutorials/controls/control-catalog.yaml
335```
336
337Fix any reported errors (e.g., missing required fields, invalid `group` reference, or malformed `threats`) so the catalog is schema-consistent.
338
339## Summary: From Threat Assessment to Control Catalog
340
341| From threat assessment | Use in control catalog |
342|-------------------------------|-------------------------------------------------------------|
343| Scope / catalog id (e.g. SEC.SLAM.CM) | Same id in control catalog metadata |
344| Threat IDs (e.g. SEC.SLAM.CM.THR01, CCC.Core.TH14) | `threats` on each control that mitigates those threats |
345| Understanding of what goes wrong | Control objectives and assessment requirements that prevent or detect it |
346
347## What's Next
348
349Use the control catalog in downstream Gemara layers: for example, map controls to Layer 1 guidelines via `guidelines`, or use the catalog in Layer 5 evaluations to record which assessment requirements have been verified.
350
351See the [Gemara Layer 2 schema documentation](https://gemara.openssf.org/schema/layer-2.html) for the full specification and optional fields (e.g., `state`, `replaced-by`, `guidelines`).