1---
2layout: page
3title: Risk Catalog Guide
4description: Step-by-step guide to creating Gemara-compatible risk catalogs
5---
6
7## What This Is
8
9This guide walks through creating a **Risk Catalog** using the [Gemara](https://gemara.openssf.org/) project. The document conforms to `#RiskCatalog` in [riskcatalog.cue](https://github.com/gemaraproj/gemara/blob/main/riskcatalog.cue) and the published [Risk Catalog schema](https://gemara.openssf.org/schema/riskcatalog.html). Examples use `gemara-version: "1.2.0"` to match the [v1.2.0](https://github.com/gemaraproj/gemara/releases/tag/v1.2.0) specification release; adjust if you target a different Gemara version.
10
11**The basic idea:** A Risk Catalog is a structured list of **[risks](../../model/02-definitions.html#risk)** that might affect an organization, system, or service. You organize them into **groups** (schema type `#RiskCategory`) that express how much risk you are willing to carry ( risk appetite) and optionally cap how bad a single risk in that group can be (**max-severity**). Each risk has an assessed **severity** and can point to Layer 2 **[threats](../../model/02-definitions.html#threat)** so mitigations and policies stay traceable to threat catalogs. Optionally, **`rank`** records a total order among risks in this catalog (for example when several share the same severity); see Step 2.
12
13In technical terms:
14* **[Risk catalogs](../../model/02-definitions.html#risk-catalog)** declare `metadata` (including `type: RiskCatalog`), **groups** as `#RiskCategory` (id, title, description, `#RiskAppetite` appetite, optional `#Severity` max-severity), and **[risks](../../model/02-definitions.html#risk)** (`#Risk`) with required id, title, description, `group`, and `severity`, plus optional **`rank`**, owner (`#RACI`), impact, and `threats` (`#MultiEntryMapping` from [mapping_inline.cue](https://github.com/gemaraproj/gemara/blob/main/mapping_inline.cue).
15* **When the catalog lists any risks**, the schema requires at least one group (`groups` becomes required in that case).
16* **Groups** use appetite values `Minimal`, `Low`, `Moderate`, or `High` and optional group-level **max-severity** (`Low`, `Medium`, `High`, `Critical`).
17* **Risks** use **severity** at the same scale (`Low` through `Critical`). Optional **`rank`** is an integer; **lower values mean higher relative importance** among risks that set `rank`. Each `rank` value must be **unique** among risks that specify it (partial ranking is allowed: risks without `rank` are unconstrained). Links under `threats` use the same multi-entry mapping pattern as control and threat catalogs; every outer `reference-id` must match an id in `metadata.mapping-references`.
18
19This exercise produces a risk catalog that you can reference from a [Policy](policy-guide) when documenting mitigated and accepted risks.
20
21The example risks in this guide are drawn from the same scope as the [Threat Assessment Guide](../controls/threat-assessment-guide): the container management tool (SEC.SLAM.CM) and the CCC Core catalog. They correspond to the imported threat **TH14** (Older Resource Versions are Used) and the custom threat **SEC.SLAM.CM.THR01** (Container Image Tampering or Poisoning) defined there.
22
23## Walkthrough
24
25### Step 0: Metadata and mapping-references
26
27Set `title` and `metadata`. Use `type: RiskCatalog` and the usual Gemara metadata fields (`id`, `gemara-version`, `description`, `author`, and optional `version`). Include `mapping-references` for every external threat catalog (or other document) you reference in risks under `threats` (by `reference-id`). Key fields:
28
29| Field | What It Is | Why |
30|-------------------------------|----------------------------------------------------------------------------|---------------------------------------------------------------------|
31| `title` | Display name for the catalog (top-level) | Human-readable label in reports and tooling |
32| `metadata.id` | Unique identifier for this catalog | Used when policies or other documents reference this catalog |
33| `metadata.description` | High-level summary of the catalog's purpose and scope | Required by schema; clarifies intent |
34| `metadata.author` | Actor (id, name, type) primarily responsible for this catalog | Required by schema; identifies the author |
35| `metadata.mapping-references` | Pointers to external threat catalogs (or artifacts) referenced in risks | Required for `threats`; each `reference-id` used there must match here |
36
37> **Note:** Include a `mapping-references` entry for every external catalog you reference in any risk's `threats` (by `reference-id`).
38
39**Example (YAML):**
40
41```yaml
42title: "Organization Risk Catalog for Cloud and Container Workloads"
43metadata:
44 id: "org-risk-catalog-001"
45 type: RiskCatalog
46 gemara-version: "1.2.0"
47 description: "Risks relevant to cloud and container management; threats linked to CCC Core and SEC.SLAM.CM threat catalog."
48 version: "1.0.0"
49 author:
50 id: security-team
51 name: "Security Team"
52 type: Human
53 mapping-references:
54 - id: CCC
55 title: Common Cloud Controls Core
56 version: v2025.10
57 url: https://github.com/finos/common-cloud-controls/releases
58 description: |
59 Foundational repository of reusable security controls, capabilities,
60 and threat models maintained by FINOS.
61 - id: "SEC.SLAM.CM"
62 title: "Container Management Tool Security Threat Catalog"
63 version: "1.0.0"
64 description: "Threat catalog from the Threat Assessment Guide (SEC.SLAM.CM)."
65```
66
67
68### Step 1: Groups (risk categories)
69
70Define at least one **group** when the catalog has risks. In CUE these are `#RiskCategory` values (embedded `#Group` plus appetite). Groups classify risks and set appetite boundaries. Each group entry has:
71
72| Field | Required | What It Is |
73|------------------|----------|----------------------------------------------------------------------------|
74| `id` | Yes | Unique identifier; risks reference this id in their `group` field |
75| `title` | Yes | Short name for the group |
76| `description` | Yes | Explains what kinds of risks belong in this group |
77| `appetite` | Yes | Acceptable level of risk: `Minimal`, `Low`, `Moderate`, or `High` |
78| `max-severity` | No | Highest allowed severity in this group: `Low`, `Medium`, `High`, `Critical` |
79
80**Example (YAML):**
81
82```yaml
83groups:
84 - id: "infrastructure"
85 title: "Infrastructure and Operations"
86 description: "Risks related to cloud infrastructure, container platforms, and operational security."
87 appetite: "Low"
88 max-severity: "High"
89 - id: "data"
90 title: "Data and Privacy"
91 description: "Risks related to data exposure, residency, and compliance."
92 appetite: "Minimal"
93 max-severity: "Low"
94```
95
96
97### Step 2: Risks
98
99Define **[risks](../../model/02-definitions.html#risk)** with required fields and optional links to Layer 2 threats and RACI owner. Each risk must reference a group id defined in Step 1. When a group sets **`max-severity`**, keep the risk’s **`severity`** at or below that cap so the catalog stays internally consistent (otherwise the risk sits outside the category’s stated tolerance).
100
101| Field | Required | What It Is |
102|-----------------|----------|----------------------------------------------------------------------------|
103| `id` | Yes | Unique identifier for this risk; used when policies reference it |
104| `title` | Yes | Clear, concise name for the risk |
105| `description` | Yes | Explains the risk scenario and context |
106| `group` | Yes | Id of a group in this catalog (from Step 1) |
107| `severity` | Yes | Impact level: `Low`, `Medium`, `High`, or `Critical` |
108| `rank` | No | Optional ordering within the catalog: integer; **lower = more important**. Unique among risks that set `rank`. Omit when severity alone is enough. |
109| `owner` | No | RACI roles (responsible, accountable, consulted, informed) for this risk |
110| `impact` | No | Business or operational impact description |
111| `threats` | No | Links to Layer 2 threat entries via reference-id and entries (see below) |
112
113For `threats`, use the same structure as in control and threat catalogs: a list of `#MultiEntryMapping` values. Each item has a `reference-id` (must match a `mapping-references` id) and `entries` (nested `#ArtifactMapping` rows). Each entry uses `reference-id` for the threat id in that catalog and optional `remarks`.
114
115**Example (YAML):**
116
117```yaml
118risks:
119 - id: "R01"
120 title: "Older or Compromised Container Images in Use"
121 description: "Mutable image tags or lack of verification can lead to pulling stale or compromised images, increasing supply chain and runtime risk."
122 group: "infrastructure"
123 severity: "High"
124 rank: 2
125 impact: "Supply chain compromise, unauthorized code execution, or data exfiltration."
126 owner:
127 responsible:
128 - name: "Platform Engineering"
129 affiliation: "Engineering"
130 accountable:
131 - name: "CISO"
132 affiliation: "Security"
133 threats:
134 - reference-id: CCC
135 entries:
136 - reference-id: CCC.Core.TH14
137 remarks: "Older Resource Versions are Used"
138 - id: "R02"
139 title: "Container Image Tampering or Poisoning"
140 description: "Images may be tampered with in transit or at rest, or built from poisoned dependencies or build pipelines."
141 group: "infrastructure"
142 severity: "High"
143 rank: 1
144 threats:
145 - reference-id: CCC
146 entries:
147 - reference-id: CCC.Core.TH14
148 remarks: "Older Resource Versions are Used"
149 - reference-id: "SEC.SLAM.CM"
150 entries:
151 - reference-id: "SEC.SLAM.CM.THR01"
152 remarks: "Container Image Tampering or Poisoning"
153```
154
155
156### Step 3: Validation
157
158The catalog must validate against `#RiskCatalog` in [riskcatalog.cue](https://github.com/gemaraproj/gemara/blob/main/riskcatalog.cue) (see also the [Risk Catalog schema](https://gemara.openssf.org/schema/riskcatalog.html) on the site). Validate with CUE:
159
160**Validation commands:**
161
162Using the **published** module:
163
164```bash
165go install cuelang.org/go/cmd/cue@latest
166cue vet -c -d '#RiskCatalog' github.com/gemaraproj/gemara@latest your-risk-catalog.yaml
167```
168
169From a **clone of this repository** (uses the working tree’s CUE package, including `riskcatalog.cue`):
170
171```bash
172cue vet -c -d '#RiskCatalog' . docs/tutorials/policy/risk-catalog-example.yaml
173```
174
175Fix any errors (e.g. missing required fields, risks present without `groups`, invalid `group` reference, severity or appetite not in allowed enums, **duplicate `rank` values** among risks that set `rank`, or a `threats` outer `reference-id` not listed in `metadata.mapping-references`) so the catalog is schema-valid.
176
177
178## Minimal Full Example
179
180A complete, schema-valid example is in [risk-catalog-example.yaml](risk-catalog-example.yaml) in this directory. The following matches that file (omit optional sections such as `rank`, `owner`, `impact`, or `threats` in your own catalogs if you do not need them). Both align with `#RiskCatalog` in [riskcatalog.cue](https://github.com/gemaraproj/gemara/blob/main/riskcatalog.cue).
181
182```yaml
183# Organization Risk Catalog for Cloud and Container Workloads (Layer 3)
184# Conforms to Gemara #RiskCatalog (riskcatalog.cue).
185# gemara-version: v1.2.0 — https://github.com/gemaraproj/gemara/releases/tag/v1.2.0
186# Risks drawn from Threat Assessment Guide: CCC (CCC.Core.TH14) and SEC.SLAM.CM (SEC.SLAM.CM.THR01).
187title: "Organization Risk Catalog for Cloud and Container Workloads"
188metadata:
189 id: "org-risk-catalog-001"
190 type: RiskCatalog
191 gemara-version: "1.2.0"
192 description: "Risks relevant to cloud and container management; threats linked to CCC Core and SEC.SLAM.CM threat catalog."
193 version: "1.0.0"
194 author:
195 id: security-team
196 name: "Security Team"
197 type: Human
198 mapping-references:
199 - id: CCC
200 title: Common Cloud Controls Core
201 version: v2025.10
202 url: https://github.com/finos/common-cloud-controls/releases
203 description: |
204 Foundational repository of reusable security controls, capabilities,
205 and threat models maintained by FINOS.
206 - id: "SEC.SLAM.CM"
207 title: "Container Management Tool Security Threat Catalog"
208 version: "1.0.0"
209 description: "Threat catalog from the Threat Assessment Guide (SEC.SLAM.CM)."
210
211groups:
212 - id: "infrastructure"
213 title: "Infrastructure and Operations"
214 description: "Risks related to cloud infrastructure, container platforms, and operational security."
215 appetite: "Low"
216 max-severity: "High"
217 - id: "data"
218 title: "Data and Privacy"
219 description: "Risks related to data exposure, residency, and compliance."
220 appetite: "Minimal"
221 max-severity: "Low"
222
223risks:
224 - id: "R01"
225 title: "Older or Compromised Container Images in Use"
226 description: "Mutable image tags or lack of verification can lead to pulling stale or compromised images, increasing supply chain and runtime risk."
227 group: "infrastructure"
228 severity: "High"
229 rank: 2
230 impact: "Supply chain compromise, unauthorized code execution, or data exfiltration."
231 owner:
232 responsible:
233 - name: "Platform Engineering"
234 affiliation: "Engineering"
235 accountable:
236 - name: "CISO"
237 affiliation: "Security"
238 threats:
239 - reference-id: CCC
240 entries:
241 - reference-id: CCC.Core.TH14
242 remarks: "Older Resource Versions are Used"
243 - id: "R02"
244 title: "Container Image Tampering or Poisoning"
245 description: "Images may be tampered with in transit or at rest, or built from poisoned dependencies or build pipelines."
246 group: "infrastructure"
247 severity: "High"
248 rank: 1
249 threats:
250 - reference-id: CCC
251 entries:
252 - reference-id: CCC.Core.TH14
253 remarks: "Older Resource Versions are Used"
254 - reference-id: "SEC.SLAM.CM"
255 entries:
256 - reference-id: "SEC.SLAM.CM.THR01"
257 remarks: "Container Image Tampering or Poisoning"
258```
259
260
261## What's Next
262
263- Reference this risk catalog from a **Policy** document: in the policy's `risks` section, use `mitigated` and `accepted` entries that reference risk ids (and, for accepted risks, justification and optional scope). See the [Policy Guide](policy-guide) and the `risks` section of the [Policy schema](https://gemara.openssf.org/schema/policy.html).
264- Use **Layer 5** evaluations to assess whether controls and implementations address the threats linked to these risks.
265- Use **Layer 7** audit and continuous monitoring to review risk posture and policy effectiveness.