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** (e.g., "allow entry/exit", "store belongings"). Then, you identify **threats**, what could go wrong with those capabilities (e.g., "unauthorized entry through unlocked door", "theft of stored belongings").
 12
 13In technical terms:
 14* **Capabilities** 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** 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
 19## Walkthrough
 20
 21### Step 0: Define Scope
 22
 23Select a component or technology to assess (service, API, infrastructure component, or technology stack).
 24
 25**Leverage existing resources**: Gemara supports importing threats and capabilities 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.
 26
 27We will explore how this is leveraged below as we dive into our container management tool example (i.e., SEC.SLAM.CM).
 28
 29### Step 1: Setting Up Metadata
 30
 31Declare your scope and mapping references. Key fields:
 32
 33| Field                               | What It Is                                                   | Why                                                                                       |
 34|-------------------------------------|--------------------------------------------------------------|-------------------------------------------------------------------------------------------|
 35| `title`                             | Display name for the threat catalog (top-level field)        | Human-readable label used in reports and tooling output                                   |
 36| `mapping-references` with `id: CCC` | A pointer to the CCC Core catalog release                    | Tells parsers where to resolve the imported capability and threat IDs used in later steps |
 37| `imported-capabilities` (Step 2)    | Specific CCC Core capabilities by ID (e.g., `CCC.Core.CP29`) | Brings in common capabilities without redefining them                                     |
 38| `imported-threats` (Step 3)         | Specific CCC Core threats by ID (e.g., `CCC.Core.TH14`)      | Brings in common threats without redefining them                                         |
 39
 40**Example (YAML):**
 41
 42```yaml
 43title: Container Management Tool Security Threat Catalog
 44metadata:
 45  id: SEC.SLAM.CM
 46  description: Threat catalog for container management tool security assessment
 47  version: 1.0.0
 48  author:
 49    id: example
 50    name: Example
 51    type: Human
 52  mapping-references:
 53    - id: CCC
 54      title: Common Cloud Controls Core
 55      version: v2025.10
 56      url: https://github.com/finos/common-cloud-controls/releases
 57      description: |
 58        Foundational repository of reusable security controls, capabilities,
 59        and threat models maintained by FINOS.
 60```
 61
 62### Step 2: Identify Capabilities
 63
 64Capabilities are the core functions or features within the scope.
 65
 66**Start with the imported capabilities** you can leverage from FINOS CCC. Ask: "Which common cloud capabilities does this technology have?"
 67
 68A container management tool actively reaches out to registries to pull images and configuration.
 69Since CCC Core already defines this as **CP29** (Active Ingestion), we import it rather than redefining it.
 70Image tags also function as version identifiers — the tool resolves a tag like `latest` or `v1.0` to a specific image.
 71CCC Core defines this as **CP18** (Resource Versioning), so we import that as well.
 72
 73**Example (YAML)**
 74
 75```yaml
 76imports:
 77  capabilities:
 78  - reference-id: CCC
 79    entries:
 80      - reference-id: CCC.Core.CP29
 81        remarks: Active Ingestion
 82      - reference-id: CCC.Core.CP18
 83        remarks: Resource Versioning
 84```
 85
 86**Then, define specific capabilities** unique to your target. Required fields:
 87
 88| Field         | Required | Description                                                        |
 89|---------------|----------|--------------------------------------------------------------------|
 90| Capability ID | Yes      | Unique identifier following the pattern `ORG.PROJ.COMPONENT.CAP##` |
 91| Title         | Yes      | A clear, concise name that describes the capability                |
 92| Description   | Yes      | A specific explanation of what this capability does                |
 93
 94**Example (YAML)**
 95
 96```yaml
 97capabilities:
 98  - id: SEC.SLAM.CM.CAP01
 99    title: Image Retrieval by Tag
100    description: |
101      Ability to retrieve container images from registries using mutable tag names
102      (e.g., 'latest', 'v1.0').
103```
104
105### Step 3: Identify Threats
106
107Threats are specific ways capabilities can be misused, exploited, or cause problems. For each capability, identify potential threats.
108
109**Check for imported threats first.** As with capabilities, review the CCC Core catalog for threats linked to the capabilities you imported.
110If a threat fits your scope, import it. In this example, CCC Core defines **TH14** ("Older Resource Versions are Used") which is linked to **CP18**.
111It applies because mutable image tags let the tool resolve to a stale or compromised version.
112
113**Example (YAML)**
114
115```yaml
116imports:
117  threats:
118  - reference-id: CCC
119    entries:
120      - reference-id: CCC.Core.TH14
121```
122
123**Then, define specific threats** unique to your target. Required fields:
124
125| Field             | Required | Description                                                                        |
126|-------------------|----------|------------------------------------------------------------------------------------|
127| Threat ID         | Yes      | Unique identifier following the pattern `ORG.PROJ.COMPONENT.THR##`                 |
128| Title             | Yes      | A clear, concise name describing the threat                                        |
129| Description       | Yes      | A specific explanation of what goes wrong and why it matters                       |
130| Capabilities      | Yes      | Links this threat to the capability(ies) it exploits                               |
131
132**Example (YAML)**
133
134Example: a custom threat (Container Image Tampering or Poisoning) linked to the capabilities it exploits — CCC CP29 (Active Ingestion), CP18 (Resource Versioning), and SEC.SLAM.CM CAP01 (Image Retrieval by Tag).
135
136```yaml
137threats:
138  - id: SEC.SLAM.CM.THR01
139    title: Container Image Tampering or Poisoning
140    description: |
141      Attackers may replace a legitimately published image tag with a malicious image
142      by exploiting tag mutability in image registries, especially when the container
143      management tool retrieves images by tag name rather than digest. This enables
144      unauthorized access, data exfiltration, and system compromise.
145    capabilities:
146      - reference-id: CCC
147        entries:
148          - reference-id: CCC.Core.CP29
149          - reference-id: CCC.Core.CP18
150      - reference-id: SEC.SLAM.CM
151        entries:
152          - reference-id: SEC.SLAM.CM.CAP01
153```
154
155### Step 4: Validate
156
157The final YAML should look something like this:
158```yaml
159metadata:
160  id: SEC.SLAM.CM
161  description: Threat catalog for container management tool security assessment
162  version: 1.0.0
163  author:
164    id: example
165    name: Example
166    type: Human
167  mapping-references:
168    - id: CCC
169      title: Common Cloud Controls Core
170      version: v2025.10
171      url: https://github.com/finos/common-cloud-controls/releases
172      description: |
173        Foundational repository of reusable security controls, capabilities,
174        and threat models maintained by FINOS.
175title: Container Management Tool Security Threat Catalog
176imported-capabilities:
177  - reference-id: CCC
178    entries:
179      - reference-id: CCC.Core.CP29
180        remarks: Active Ingestion
181      - reference-id: CCC.Core.CP18
182        remarks: Resource Versioning
183      - reference-id: CCC.Core.CP01 # Map to TH02 and THR02 for transit capability
184        remarks: Encryption in Transit Enabled by Default
185imported-threats:
186  - reference-id: CCC
187    entries:
188      - reference-id: CCC.Core.TH14
189      - reference-id: CCC.Core.TH02
190capabilities:
191  - id: SEC.SLAM.CM.CAP01
192    title: Image Retrieval by Tag
193    description: |
194      Ability to retrieve container images from registries using mutable tag names (e.g., 'latest', 'v1.0').
195  - id: SEC.SLAM.CM.CAP02
196    title: Image Reference Lookup
197    description: |
198      The container management tool determines which artifact
199      an image reference (e.g. tag, URL) refers to via network
200      requests; that determination may occur at a different time
201      than use, and references may be mutable.
202threats:
203  - id: SEC.SLAM.CM.THR01
204    title: Container Image Tampering or Poisoning # TODO: Add granularity for this tutorial
205    description: |
206      Attackers may replace a legitimately published image tag with a malicious image by exploiting tag mutability in image registries, especially when the container management tool retrieves images by tag name rather than digest. This enables unauthorized access, data exfiltration, and system compromise.
207    capabilities:
208      - reference-id: CCC
209        entries:
210          - reference-id: CCC.Core.CP29
211          - reference-id: CCC.Core.CP18
212      - reference-id: SEC.SLAM.CM
213        entries:
214          - reference-id: SEC.SLAM.CM.CAP01
215  - id: SEC.SLAM.CM.THR02 # Mitigate using TLS/SSL with certificate pinning 
216    title: MITM Container Image Interception
217    description: |
218      Attackers redirect the client to an unauthorized or malicious mirror so that image pulls (or other artifact downloads) fetch compromised artifacts instead of the intended ones—via DNS spoofing, MITM, or compromise of resolution or redirect. The client believes it is pulling from the trusted vendor but is served malware or tampered images. 
219    capabilities:
220      - reference-id: CCC
221        entries:
222          - reference-id: CCC.Core.CP29
223          - reference-id: CCC.Core.CP01
224      - reference-id: SEC.SLAM.CM
225        entries:
226          - reference-id: SEC.SLAM.CM.CAP01
227          - reference-id: SEC.SLAM.CM.CAP02
228- id: SEC.SLAM.CM.THR03
229    title: TOCTOU Attacks during time-of-check-time-of-use
230    description: |
231      Attackers exploit the gap between when the container management tool (or pipeline) validates an image and 
232      when it is used: they modify the resource after the 
233      check and before use (e.g. replacing the image in
234      cache, swapping the file on disk, or changing what a tag resolves to) so the tool runs or distributes a malicious image that bypassed the check, leading to compromised workloads, credential theft, or supply chain poisoning. 
235    capabilities:
236      - reference-id: CCC
237        entries:
238          - reference-id: CCC.Core.CP29
239          - reference-id: CCC.Core.CP18
240      - reference-id: SEC.SLAM.CM
241        entries:
242          - reference-id: SEC.SLAM.CM.CAP01
243          - reference-id: SEC.SLAM.CM.CAP02
244- id: SEC.SLAM.CM.THR04
245    title: Supply chain compromise from tag substitution 
246    description: |
247      Attackers substitute the content behind a mutable tag (e.g. "latest", "v1.0") by retagging a malicious image or publishing under the same tag after the legitimate one, so that consumers who pull by tag receive a malicious artifact. CI/CD and deployments that use tags (rather than digests) pull the substituted artifact, introducing malware, backdoors, or credential theft into the supply chain. 
248    capabilities:
249      - reference-id: CCC
250        entries:
251          - reference-id: CCC.Core.CP29
252          - reference-id: CCC.Core.CP18 
253      - reference-id: SEC.SLAM.CM
254        entries:
255          - reference-id: SEC.SLAM.CM.CAP01
256          - reference-id: SEC.SLAM.CM.CAP02  
257- id: SEC.SLAM.CM.THR05
258    title: Container Registry Typosquatting 
259    description: |
260      Attackers register container image or registry names that closely mimic legitimate ones (typos, homoglyphs, character omission or transposition) so that users or automation accidentally pull a malicious image instead of the intended one, leading to malware, credential theft, or backdoors.
261    capabilities:
262      - reference-id: CCC
263        entries:
264          - reference-id: CCC.Core.CP29
265          - reference-id: CCC.Core.CP18 
266      - reference-id: SEC.SLAM.CM
267        entries:
268          - reference-id: SEC.SLAM.CM.CAP01
269          - reference-id: SEC.SLAM.CM.CAP02
270```
271
272**Validation commands:**
273
274```bash
275go install cuelang.org/go/cmd/cue@latest
276cue vet -c -d '#ThreatCatalog' github.com/gemaraproj/gemara@latest your-threats.yaml
277```
278
279## What's Next
280
281Create a Gemara Control Catalog that maps security controls to the identified threats using the [Control Catalog Guide](control-catalog-guide). See the [Gemara Layer 2 schema documentation](https://gemara.openssf.org/schema/layer-2.html) for the full specification.