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](../../model/02-definitions.html#control)** are safeguards with a stated **objective** and a list of **[assessment requirements](../../model/02-definitions.html#assessment-requirement)**.
13* **Groups** group related controls by domain (e.g., supply chain, access control).
14* **[Threats](../../model/02-definitions.html#threat)** 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| `metadata.type` | Must be `ControlCatalog` | Identifies the artifact kind for validation |
41| `metadata.gemara-version` | String (e.g. `1.2.0`) | Declares which Gemara specification version the file conforms to (required in current schema) |
42| `mapping-references` with `id: CCC` | Optional pointer to CCC or another control/threat catalog | Resolve imported capability and control IDs from the referenced catalog |
43| `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 |
44
45> **Note:** Applicability groups **must** be defined to assign applicability to controls.
46
47**Example (YAML):**
48
49```yaml
50title: Container Management Tool Security Control Catalog
51metadata:
52 id: SEC.SLAM.CM
53 type: ControlCatalog
54 gemara-version: "1.2.0"
55 description: Control catalog for container management tool security; mitigates threats from the SEC.SLAM.CM threat catalog.
56 version: 1.0.0
57 author:
58 id: example
59 name: Example
60 type: Human
61 mapping-references:
62 - id: SEC.SLAM.CM
63 title: Container Management Tool Security Threat Catalog
64 version: "1.0.0"
65 url: file://threats.yaml
66 description: |
67 Threat catalog for the same scope; provides threat IDs referenced from each
68 control's threats.
69 - id: CCC
70 title: Common Cloud Controls Core
71 version: v2025.10
72 url: https://github.com/finos/common-cloud-controls/releases
73 description: |
74 Foundational repository of reusable security controls, capabilities,
75 and threat models maintained by FINOS.
76 applicability-groups:
77 - id: production
78 title: Production
79 description: |
80 Production container workloads and clusters; controls apply to
81 live environments where security posture is enforced.
82 - id: all_deployments
83 title: All Deployments
84 description: |
85 Requirements that apply whenever container images are built, pulled, or run—
86 regardless of environment (dev, staging, production) or pipeline stage.
87 - id: untrusted_networks
88 title: Untrusted Networks
89 description: |
90 Applies when registry or image traffic traverses untrusted networks.
91 - id: ci_cd
92 title: CI/CD
93 description: |
94 Applies in continuous integration and deployment pipelines.
95```
96
97### Step 2: Define Control Groups
98
99**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.
100
101Required fields for each group:
102
103| Field | Required | Description |
104|---------------|----------|----------------------------------------------|
105| `id` | Yes | Unique identifier referenced by controls |
106| `title` | Yes | Short name for the group |
107| `description` | Yes | Explanation of what controls in this group address |
108
109**Example (YAML):**
110
111```yaml
112groups:
113 - id: SEC.SLAM.CM.FAM01
114 title: Image Integrity and Supply Chain
115 description: |
116 Controls that ensure container images are authentic, unmodified,
117 and from trusted sources throughout retrieval and use.
118```
119
120### Step 3: Import or Define Controls
121
122> **Note:** For how controls are automatically pulled into policy to mitigate high-severity risks, see the FAQ.
123
124
125**Option A — Import Controls:** If an external catalog (e.g., CCC) defines controls that address your threats, reference it in `mapping-references` and list imported controls under top-level `imports`.
126
127**Example (YAML):**
128
129```yaml
130imports:
131 - reference-id: CCC
132 entries:
133 - reference-id: CCC.Core.CTL42
134 remarks: Image signing and verification
135```
136
137**Option B — Define your own controls:** For controls specific to your scope, define them under `controls`. Required and common fields (see `controlcatalog.cue`):
138
139| Field | Required | Description |
140|--------------------------|----------|-----------------------------------------------------------------------------|
141| `id` | Yes | Unique identifier (e.g., `ORG.PROJ.COMPONENT.CTL##`) |
142| `title` | Yes | Short name describing the control |
143| `objective` | Yes | Unified statement of intent for the control |
144| `group` | Yes | `id` of a group in this catalog (or in a referenced catalog for imports) |
145| `assessment-requirements`| Yes | List of verifiable conditions; each has `id`, `text`, `applicability` |
146| `threats` | No | Links to threat catalog(s) and threat IDs this control mitigates |
147| `state` | No | Lifecycle: `Active`, `Draft`, `Deprecated`, `Retired`; omitted is treated as `Active`. |
148
149Each **assessment requirement** must have:
150
151| Field | Required | Description |
152|-----------------|----------|-----------------------------------------------------------------------------|
153| `id` | Yes | Unique within the control (e.g., `SEC.SLAM.CM.CTL01.AR01`) |
154| `text` | Yes | Verifiable condition (typically a MUST statement) |
155| `applicability` | Yes | List of strings describing when this requirement applies |
156
157**Example (YAML):**
158
159```yaml
160controls:
161 - id: SEC.SLAM.CM.CTL01
162 title: Use Immutable Image References by Digest
163 objective: |
164 Require signature validation so that only legitimate, trusted images are
165 accepted; then pin each image to an immutable digest (e.g., sha256)
166 after the check so that what is used matches what was verified and
167 TOCTOU (time-of-check to time-of-use) attacks are prevented.
168 group: SEC.SLAM.CM.FAM01
169 assessment-requirements:
170 - id: SEC.SLAM.CM.CTL01.AR01
171 text: |
172 The system MUST verify image signature before pull or run, then pin
173 the image to a digest (e.g., sha256:...) after the check and use that
174 digest for all subsequent use.
175 applicability: ["all_deployments"]
176 - id: SEC.SLAM.CM.CTL01.AR02
177 text: |
178 Configuration and policies MUST disallow or override use of tag-only
179 references for production or sensitive workloads where supported.
180 applicability: ["production"]
181 threats:
182 - reference-id: SEC.SLAM.CM
183 entries:
184 - reference-id: SEC.SLAM.CM.THR01
185 - reference-id: SEC.SLAM.CM.THR03
186 - reference-id: SEC.SLAM.CM.THR04
187 - reference-id: CCC
188 entries:
189 - reference-id: CCC.Core.TH14
190 - id: SEC.SLAM.CM.CTL02
191 title: Require TLS/SSL with Certificate Pinning
192 objective: |
193 Mitigate MITM Container Image Interception by protecting registry traffic and verifying artifact integrity: use
194 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.
195 group: SEC.SLAM.CM.FAM01
196 state: Active
197 assessment-requirements:
198 - id: SEC.SLAM.CM.CTL02.AR01
199 text: |
200 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.
201 applicability: ["all_deployments"]
202 state: Active
203 - id: SEC.SLAM.CM.CTL02.AR02
204 text: |
205 On untrusted networks, the system or deployment pipeline MUST use a VPN or other trusted path for registry traffic, or MUST restrict
206 image pulls to environments where the network is trusted.
207 applicability: ["untrusted_networks", "ci_cd"]
208 state: Active
209 - id: SEC.SLAM.CM.CTL02.AR03
210 text: |
211 The system MUST verify artifact signatures or hashes (e.g. signature verification, digest check) before use so that tampered or redirected artifacts are rejected.
212 applicability: ["all_deployments"]
213 state: Active
214 threats:
215 - reference-id: SEC.SLAM.CM
216 entries:
217 - reference-id: SEC.SLAM.CM.THR02
218 - reference-id: CCC
219 entries:
220 - reference-id: CCC.Core.TH02
221```
222
223### Step 4: Validate Against the Gemara Schema
224
225Validate the final catalog with CUE:
226
227**Validation commands:**
228
229```bash
230go install cuelang.org/go/cmd/cue@latest
231cue vet -c -d '#ControlCatalog' github.com/gemaraproj/gemara@v1 your-control-catalog.yaml
232```
233
234Fix any reported errors (e.g., missing required fields, invalid `group` reference, or malformed `threats`) so the catalog is schema-consistent.
235
236### Step 5: Assemble the Full Catalog and Validate
237
238Combine metadata, mapping-references, groups, `imports` (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).
239
240**Complete example (SEC.SLAM.CM):**
241
242```yaml
243title: Container Management Tool Security Control Catalog
244
245metadata:
246 id: SEC.SLAM.CM
247 type: ControlCatalog
248 gemara-version: "1.2.0"
249 description: |
250 Control catalog for container management tool security; mitigates threats
251 from the SEC.SLAM.CM threat catalog.
252 version: 1.0.0
253 author:
254 id: example
255 name: Example
256 type: Human
257 mapping-references:
258 - id: SEC.SLAM.CM
259 title: Container Management Tool Security Threat Catalog
260 version: "1.0.0"
261 url: https://example.org/catalogs/SEC.SLAM.CM-threats.yaml
262 description: |
263 Threat catalog for the same scope; provides threat IDs referenced from each
264 control's threats.
265 - id: CCC
266 title: Common Cloud Controls Core
267 version: v2025.10
268 url: https://github.com/finos/common-cloud-controls/releases
269 description: |
270 Foundational repository of reusable security controls, capabilities,
271 and threat models maintained by FINOS.
272 applicability-groups:
273 - id: production
274 title: Production
275 description: |
276 Production container workloads and clusters; controls apply to
277 live environments where security posture is enforced.
278 - id: all_deployments
279 title: All Deployments
280 description: |
281 Requirements that apply whenever container images are built, pulled, or run—
282 regardless of environment (dev, staging, production) or pipeline stage.
283 - id: untrusted_networks
284 title: Untrusted Networks
285 description: |
286 Applies when registry or image traffic traverses untrusted networks.
287 - id: ci_cd
288 title: CI/CD
289 description: |
290 Applies in continuous integration and deployment pipelines.
291
292groups:
293 - id: SEC.SLAM.CM.FAM01
294 title: Image Integrity and Supply Chain
295 description: |
296 Controls that ensure container images are authentic, unmodified,
297 and from trusted sources throughout retrieval and use.
298
299imports:
300 - reference-id: CCC
301 entries:
302 - reference-id: CCC.Core.CTL42
303 remarks: Image signing and verification
304
305controls:
306 - id: SEC.SLAM.CM.CTL01
307 title: Use Immutable Image References by Digest
308 objective: |
309 Require signature validation so that only legitimate, trusted images are
310 accepted; then pin each image to an immutable digest (e.g., sha256)
311 after the check so that what is used matches what was verified and
312 TOCTOU (time-of-check to time-of-use) attacks are prevented.
313 group: SEC.SLAM.CM.FAM01
314 assessment-requirements:
315 - id: SEC.SLAM.CM.CTL01.AR01
316 text: |
317 The system MUST verify image signature before pull or run, then pin
318 the image to a digest (e.g., sha256:...) after the check and use that
319 digest for all subsequent use.
320 applicability: ["all_deployments"]
321 - id: SEC.SLAM.CM.CTL01.AR02
322 text: |
323 Configuration and policies MUST disallow or override use of tag-only
324 references for production or sensitive workloads where supported.
325 applicability: ["production"]
326 threats:
327 - reference-id: SEC.SLAM.CM
328 entries:
329 - reference-id: SEC.SLAM.CM.THR01
330 - reference-id: SEC.SLAM.CM.THR03
331 - reference-id: SEC.SLAM.CM.THR04
332 - reference-id: CCC
333 entries:
334 - reference-id: CCC.Core.TH14
335 - id: SEC.SLAM.CM.CTL02
336 title: Require TLS/SSL with Certificate Pinning
337 objective: |
338 Mitigate MITM Container Image Interception by protecting registry
339 traffic and verifying artifact integrity: use TLS/SSL with certificate
340 pinning for all registry communication, use VPNs on untrusted networks
341 to reduce interception risk, and verify artifact signatures or hashes so
342 that tampered or redirected content is detected even if the channel is
343 compromised.
344 group: SEC.SLAM.CM.FAM01
345 state: Active
346 assessment-requirements:
347 - id: SEC.SLAM.CM.CTL02.AR01
348 text: |
349 The system MUST use TLS/SSL for all registry communication and MUST
350 pin to the expected server certificate or public key (or certificate
351 chain) for the registry.
352 applicability: ["all_deployments"]
353 state: Active
354 - id: SEC.SLAM.CM.CTL02.AR02
355 text: |
356 On untrusted networks, the system or deployment pipeline MUST use a
357 VPN or other trusted path for registry traffic, or MUST restrict
358 image pulls to environments where the network is trusted.
359 applicability: ["untrusted_networks", "ci_cd"]
360 state: Active
361 - id: SEC.SLAM.CM.CTL02.AR03
362 text: |
363 The system MUST verify artifact signatures or hashes (e.g. signature
364 verification, digest check) before use so that tampered or redirected
365 artifacts are rejected.
366 applicability: ["all_deployments"]
367 state: Active
368 threats:
369 - reference-id: SEC.SLAM.CM
370 entries:
371 - reference-id: SEC.SLAM.CM.THR02
372 - reference-id: CCC
373 entries:
374 - reference-id: CCC.Core.TH02
375```
376**Validation commands:**
377
378Using the **published** module:
379
380```bash
381go install cuelang.org/go/cmd/cue@latest
382cue vet -c -d '#ControlCatalog' github.com/gemaraproj/gemara@v1 your-control-catalog.yaml
383```
384
385Fix any reported errors (e.g., missing required fields, invalid `group` reference, or malformed `threats`) so the catalog is schema-consistent.
386
387## Summary: From Threat Assessment to Control Catalog
388
389| From threat assessment | Use in control catalog |
390|-------------------------------|-------------------------------------------------------------|
391| Scope / catalog id (e.g. SEC.SLAM.CM) | Same id in control catalog metadata |
392| Threat IDs (e.g. SEC.SLAM.CM.THR01, CCC.Core.TH14) | `threats` on each control that mitigates those threats |
393| Understanding of what goes wrong | Control objectives and assessment requirements that prevent or detect it |
394
395## What's Next
396
397Use 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.
398
399**Layer 2 schema documentation:**
400- [Threat Catalog](https://gemara.openssf.org/schema/threatcatalog.html)
401- [Capability Catalog](https://gemara.openssf.org/schema/capabilitycatalog.html)
402- [Control Catalog](https://gemara.openssf.org/schema/controlcatalog.html)