1---
  2layout: page
  3title: Threat Assessment Guide
  4description: Step-by-step guide to performing Gemara-compatible threat assessments
  5---
  6
  7## What This Is
  8
  9This guide walks through a threat assessment using the [Gemara](https://gemara.openssf.org/) project.
 10
 11**The basic idea:** Think of a project like a house. First, you identify what the house can do: its **[capabilities](../../model/02-definitions.html#capability)** (e.g., "allow entry/exit", "store belongings"). Then, you identify **[threats](../../model/02-definitions.html#threat)**, what could go wrong with those capabilities (e.g., "unauthorized entry through unlocked door", "theft of stored belongings").
 12
 13In technical terms:
 14 * **[Capabilities](../../model/02-definitions.html#capability)** define what the technology can do. These form a primary component of the **attack surface** because every intended function represents a potential path for unintended use.
 15 * **[Threats](../../model/02-definitions.html#threat)** define specific ways those capabilities could be misused or exploited.
 16
 17This exercise helps you systematically identify what could go wrong so you can build appropriate defenses.
 18
 19Gemara splits these into two artifact kinds: `CapabilityCatalog` for capability definitions, and `ThreatCatalog` for threats. A threat catalog references capabilities via `mapping-references` on each threat. 
 20
 21## Walkthrough
 22
 23### Step 0: Define Scope
 24
 25Select a component or technology to assess (service, API, infrastructure component, or technology stack).
 26
 27**Leverage existing resources**: Gemara supports importing entries from external catalogs so you don't have to start from scratch. The FINOS Common Cloud Controls (CCC) Core [catalog](https://github.com/finos/common-cloud-controls/releases/download/v2025.10/CCC.Core_v2025.10.yaml) defines well-vetted capabilities and threats that apply broadly across cloud services. These pre-built items can help accelerate your assessment.
 28
 29We will explore how this is leveraged below as we dive into our container management tool example (i.e., **SEC.SLAM.CM**).
 30
 31### Step 1: Setting Up Metadata (Threat catalog)
 32
 33Declare your scope and mapping references for the `ThreatCatalog`. Key fields:
 34
 35| Field | What It Is | Why |
 36|-------|------------|-----|
 37| `title` | Display name for the threat catalog (top-level field) | Human-readable label used in reports and tooling output |
 38| `metadata.type` | Must be `ThreatCatalog` | Identifies the artifact for `#ThreatCatalog` validation |
 39| `metadata.gemara-version` | String (e.g. `1.2.0`) | Declares which Gemara specification version the file conforms to (required) |
 40| `mapping-references` with `id: CCC` | Pointer to the CCC Core catalog release | Resolve imported CCC capability and threat IDs used in `imports` and in each threat's `capabilities` |
 41| `mapping-references` for scope capabilities | Pointer to your `CapabilityCatalog` (see Step 2) | Resolve IDs such as `SEC.SLAM.CM.CAP01` referenced from each threat's `capabilities` |
 42| Top-level `imports` (optional) | List of `#MultiEntryMapping` rows | Pull CCC (or other) capability/threat entries into this catalog without redefining them |
 43
 44**Example (YAML)** — threat catalog metadata only:
 45
 46```yaml
 47title: Container Management Tool Security Threat Catalog
 48metadata:
 49  id: SEC.SLAM.CM
 50  type: ThreatCatalog
 51  gemara-version: "1.2.0"
 52  description: Threat catalog for container management tool security assessment
 53  version: 1.0.0
 54  author:
 55    id: example
 56    name: Example
 57    type: Human
 58  mapping-references:
 59    - id: CCC
 60      title: Common Cloud Controls Core
 61      version: v2025.10
 62      url: https://github.com/finos/common-cloud-controls/releases
 63      description: |
 64        Foundational repository of reusable security controls, capabilities,
 65        and threat models maintained by FINOS.
 66    - id: SEC.SLAM.CM.CAP
 67      title: Container Management Tool Security Capability Catalog
 68      version: "1.0.0"
 69      url: https://example.org/catalogs/SEC.SLAM.CM-capabilities.yaml
 70      description: |
 71        Scope-specific capabilities for this assessment (see Step 2).
 72```
 73
 74### Step 2: Identify Capabilities (Capability catalog)
 75
 76Capabilities are the core functions or features within the scope. In Gemara they live in a `CapabilityCatalog`. For SEC.SLAM.CM, scope-specific capabilities are in [capabilities.yaml](capabilities.yaml) (`metadata.id` `SEC.SLAM.CM.CAP`) so threats can reference them with `reference-id: SEC.SLAM.CM.CAP` and `entries` listing IDs such as `SEC.SLAM.CM.CAP01`.
 77
 78**Start with the imported capabilities** you can leverage from FINOS CCC. Ask: "Which common cloud capabilities does this technology have?" 
 79
 80A container management tool actively reaches out to registries to pull images and configuration. Since CCC Core already defines that as **CP29** (Active Ingestion), we import it rather than redefining it. Image tags also function as version identifiers - the tool resolves a tag like `latest` or `v1.0` to a specific image. CCC Core defines that behavior as **CP18** (Resource Versioning), so we import that as well. 
 81
 82> **Note:** Those IDs are referenced from threats under each threat’s `capabilities` and may also appear under top-level `imports` in the `ThreatCatalog`.
 83
 84**Then, define specific capabilities** unique to your target. Required fields:
 85
 86| Field | Required | Description |
 87|-------|----------|-------------|
 88| `id` | Yes | Unique identifier (e.g. `ORG.PROJ.COMPONENT.CAP##`) |
 89| `title` | Yes | Clear name for the capability |
 90| `description` | Yes | What this capability does |
 91| `group` | Yes | `id` of a **group** defined in the same capability catalog |
 92
 93**Example (YAML)** — see [capabilities.yaml](capabilities.yaml):
 94
 95```yaml
 96title: Container Management Tool Security Capability Catalog
 97metadata:
 98  id: SEC.SLAM.CM.CAP
 99  type: CapabilityCatalog
100  gemara-version: "1.2.0"
101  description: |
102    Capabilities unique to the container management tool scope.
103  version: 1.0.0
104  author:
105    id: example
106    name: Example
107    type: Human
108
109groups:
110  - id: SEC.SLAM.CM.CAPGRP01
111    title: Image retrieval and resolution
112    description: |
113      How the tool retrieves images and resolves references to artifacts.
114
115capabilities:
116  - id: SEC.SLAM.CM.CAP01
117    title: Image Retrieval by Tag
118    description: |
119      Ability to retrieve container images from registries using mutable tag names
120      (e.g., 'latest', 'v1.0').
121    group: SEC.SLAM.CM.CAPGRP01
122  - id: SEC.SLAM.CM.CAP02
123    title: Image Reference Lookup
124    description: |
125      The tool resolves image references via network requests; resolution time may
126      differ from use time, and references may be mutable.
127    group: SEC.SLAM.CM.CAPGRP01
128```
129
130### Step 3: Identify Threats (Threat catalog)
131
132 **[Threats](../../model/02-definitions.html#threat)** are specific ways **[capabilities](../../model/02-definitions.html#capability)** can be misused, exploited, or cause problems. For each **capability**, identify potential **threats**.
133
134Check for imported **[threats](../../model/02-definitions.html#threat)** first. As with **[capabilities](../../model/02-definitions.html#capability)**, review the CCC Core catalog for threats linked to the capabilities you imported. If a threat fits your scope, import it. In this example, CCC Core defines **TH14** ("Older Resource Versions are Used") which is linked to **CP18**. It applies because mutable image tags let the tool resolve to a stale or compromised version.
135
136**Importing from CCC.** List CCC rows under top-level `imports` as a list of mappings. You can include both capability and threat IDs from CCC in the same `entries` list when they come from that single mapping reference.
137
138**Example (YAML)** — `imports` on the threat catalog:
139
140```yaml
141imports:
142  - reference-id: CCC
143    entries:
144      - reference-id: CCC.Core.CP29
145        remarks: Active Ingestion
146      - reference-id: CCC.Core.CP18
147        remarks: Resource Versioning
148      - reference-id: CCC.Core.TH14
149        remarks: Older Resource Versions are Used
150```
151
152**Then, define specific threats** unique to your target. Required fields:
153
154| Field | Required | Description |
155|-------|----------|-------------|
156| `id` | Yes | Unique identifier following the pattern `ORG.PROJ.COMPONENT.THR##` |
157| `title` | Yes | Short name for the threat |
158| `description` | Yes | What goes wrong and why it matters |
159| `group` | Yes | `id` of a **group** defined in this threat catalog |
160| `capabilities` | Yes | Links this threat to the capabilities it exploits |
161| `vectors` | No | Optional link to vector catalog entries |
162| `actors` | No | Optional threat actors (`#Actor`) |
163
164**Example (YAML)** — a custom threat (*Container Image Tampering or Poisoning*) linked to the capabilities it exploits: **CCC.Core.CP29** (Active Ingestion), **CCC.Core.CP18** (Resource Versioning), and **SEC.SLAM.CM.CAP01** (Image Retrieval by Tag) via your scope capability catalog reference (`SEC.SLAM.CM.CAP`).
165
166```yaml
167groups:
168  - id: SEC.SLAM.CM.FAM01
169    title: Image integrity and supply chain
170    description: |
171      Threats affecting container image retrieval, integrity, and trust.
172
173threats:
174  - id: SEC.SLAM.CM.THR01
175    title: Container Image Tampering or Poisoning
176    description: |
177      Attackers may replace a legitimately published image tag with a malicious image
178      by exploiting tag mutability in image registries, especially when the container
179      management tool retrieves images by tag name rather than digest. This enables
180      unauthorized access, data exfiltration, and system compromise.
181    group: SEC.SLAM.CM.FAM01
182    capabilities:
183      - reference-id: CCC
184        entries:
185          - reference-id: CCC.Core.CP29
186          - reference-id: CCC.Core.CP18
187      - reference-id: SEC.SLAM.CM.CAP
188        entries:
189          - reference-id: SEC.SLAM.CM.CAP01
190```
191
192### Step 4: Validate
193
194The final YAML should look something like this:
195
196```yaml
197title: Container Management Tool Security Threat Catalog
198
199metadata:
200  id: SEC.SLAM.CM
201  type: ThreatCatalog
202  gemara-version: "1.2.0"
203  description: Threat catalog for container management tool security assessment
204  version: 1.0.0
205  author:
206    id: example
207    name: Example
208    type: Human
209  mapping-references:
210    - id: CCC
211      title: Common Cloud Controls Core
212      version: v2025.10
213      url: https://github.com/finos/common-cloud-controls/releases
214      description: |
215        Foundational repository of reusable security controls, capabilities,
216        and threat models maintained by FINOS.
217    - id: SEC.SLAM.CM.CAP
218      title: Container Management Tool Security Capability Catalog
219      version: "1.0.0"
220      url: https://example.org/catalogs/SEC.SLAM.CM-capabilities.yaml
221      description: |
222        Scope-specific capabilities (CAP01, CAP02) for this threat assessment.
223
224groups:
225  - id: SEC.SLAM.CM.FAM01
226    title: Image integrity and supply chain
227    description: |
228      Threats affecting container image retrieval, integrity, and trust.
229
230imports:
231  - reference-id: CCC
232    entries:
233      - reference-id: CCC.Core.CP29
234        remarks: Active Ingestion
235      - reference-id: CCC.Core.CP18
236        remarks: Resource Versioning
237      - reference-id: CCC.Core.TH14
238        remarks: Older Resource Versions are Used
239
240threats:
241  - id: SEC.SLAM.CM.THR01
242    title: Container Image Tampering or Poisoning
243    description: |
244      Attackers may replace a legitimately published image tag with a malicious image
245      by exploiting tag mutability in image registries, especially when the container
246      management tool retrieves images by tag name rather than digest. This enables
247      unauthorized access, data exfiltration, and system compromise.
248    group: SEC.SLAM.CM.FAM01
249    capabilities:
250      - reference-id: CCC
251        entries:
252          - reference-id: CCC.Core.CP29
253          - reference-id: CCC.Core.CP18
254      - reference-id: SEC.SLAM.CM.CAP
255        entries:
256          - reference-id: SEC.SLAM.CM.CAP01
257```
258
259The complete tutorial adds more CCC imports and additional threats; see [threat-catalog.yaml](threat-catalog.yaml). 
260
261**Validation commands:**
262
263```bash
264go install cuelang.org/go/cmd/cue@latest
265cue vet -c -d '#CapabilityCatalog' github.com/gemaraproj/gemara@v1 docs/tutorials/controls/your-capabilities.yaml
266cue vet -c -d '#ThreatCatalog' github.com/gemaraproj/gemara@v1 docs/tutorials/controls/your-threat-catalog.yaml
267```
268
269## What's Next
270
271Create a Gemara control catalog that maps security controls to these threats using the [Control Catalog Guide](control-catalog-guide).
272
273**Layer 2 schema documentation:** 
274- [Capability Catalog](https://gemara.openssf.org/schema/capabilitycatalog.html)
275- [Threat Catalog](https://gemara.openssf.org/schema/threatcatalog.html)
276- [Control Catalog](https://gemara.openssf.org/schema/controlcatalog.html)