What This Is

This guide walks through a threat assessment using the Gemara project.

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”).

In technical terms:

  • 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.
  • Threats define specific ways those capabilities could be misused or exploited.

This exercise helps you systematically identify what could go wrong so you can build appropriate defenses.

Gemara 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.

Walkthrough

Step 0: Define Scope

Select a component or technology to assess (service, API, infrastructure component, or technology stack).

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 defines well-vetted capabilities and threats that apply broadly across cloud services. These pre-built items can help accelerate your assessment.

We will explore how this is leveraged below as we dive into our container management tool example (i.e., SEC.SLAM.CM).

Step 1: Setting Up Metadata (Threat catalog)

Declare your scope and mapping references for the ThreatCatalog. Key fields:

Field What It Is Why
title Display name for the threat catalog (top-level field) Human-readable label used in reports and tooling output
metadata.type Must be ThreatCatalog Identifies the artifact for #ThreatCatalog validation
metadata.gemara-version String (e.g. 1.0.0) Declares which Gemara specification version the file conforms to (required)
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
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
Top-level imports (optional) List of #MultiEntryMapping rows Pull CCC (or other) capability/threat entries into this catalog without redefining them

Example (YAML) — threat catalog metadata only:

title: Container Management Tool Security Threat Catalog
metadata:
  id: SEC.SLAM.CM
  type: ThreatCatalog
  gemara-version: "1.0.0"
  description: Threat catalog for container management tool security assessment
  version: 1.0.0
  author:
    id: example
    name: Example
    type: Human
  mapping-references:
    - id: CCC
      title: Common Cloud Controls Core
      version: v2025.10
      url: https://github.com/finos/common-cloud-controls/releases
      description: |
        Foundational repository of reusable security controls, capabilities,
        and threat models maintained by FINOS.
    - id: SEC.SLAM.CM.CAP
      title: Container Management Tool Security Capability Catalog
      version: "1.0.0"
      url: https://example.org/catalogs/SEC.SLAM.CM-capabilities.yaml
      description: |
        Scope-specific capabilities for this assessment (see Step 2).

Step 2: Identify Capabilities (Capability catalog)

Capabilities 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 (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.

Start with the imported capabilities you can leverage from FINOS CCC. Ask: “Which common cloud capabilities does this technology have?”

A 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.

Note: Those IDs are referenced from threats under each threat’s capabilities and may also appear under top-level imports in the ThreatCatalog.

Then, define specific capabilities unique to your target. Required fields:

Field Required Description
id Yes Unique identifier (e.g. ORG.PROJ.COMPONENT.CAP##)
title Yes Clear name for the capability
description Yes What this capability does
group Yes id of a group defined in the same capability catalog

Example (YAML) — see capabilities.yaml:

title: Container Management Tool Security Capability Catalog
metadata:
  id: SEC.SLAM.CM.CAP
  type: CapabilityCatalog
  gemara-version: "1.0.0"
  description: |
    Capabilities unique to the container management tool scope.
  version: 1.0.0
  author:
    id: example
    name: Example
    type: Human

groups:
  - id: SEC.SLAM.CM.CAPGRP01
    title: Image retrieval and resolution
    description: |
      How the tool retrieves images and resolves references to artifacts.

capabilities:
  - id: SEC.SLAM.CM.CAP01
    title: Image Retrieval by Tag
    description: |
      Ability to retrieve container images from registries using mutable tag names
      (e.g., 'latest', 'v1.0').
    group: SEC.SLAM.CM.CAPGRP01
  - id: SEC.SLAM.CM.CAP02
    title: Image Reference Lookup
    description: |
      The tool resolves image references via network requests; resolution time may
      differ from use time, and references may be mutable.
    group: SEC.SLAM.CM.CAPGRP01

Step 3: Identify Threats (Threat catalog)

Threats are specific ways capabilities can be misused, exploited, or cause problems. For each capability, identify potential threats.

Check for imported threats first. As with capabilities, 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.

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.

Example (YAML) — imports on the threat catalog:

imports:
  - reference-id: CCC
    entries:
      - reference-id: CCC.Core.CP29
        remarks: Active Ingestion
      - reference-id: CCC.Core.CP18
        remarks: Resource Versioning
      - reference-id: CCC.Core.TH14
        remarks: Older Resource Versions are Used

Then, define specific threats unique to your target. Required fields:

Field Required Description
id Yes Unique identifier following the pattern ORG.PROJ.COMPONENT.THR##
title Yes Short name for the threat
description Yes What goes wrong and why it matters
group Yes id of a group defined in this threat catalog
capabilities Yes Links this threat to the capabilities it exploits
vectors No Optional link to vector catalog entries
actors No Optional threat actors (#Actor)

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).

groups:
  - id: SEC.SLAM.CM.FAM01
    title: Image integrity and supply chain
    description: |
      Threats affecting container image retrieval, integrity, and trust.

threats:
  - id: SEC.SLAM.CM.THR01
    title: Container Image Tampering or Poisoning
    description: |
      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.
    group: SEC.SLAM.CM.FAM01
    capabilities:
      - reference-id: CCC
        entries:
          - reference-id: CCC.Core.CP29
          - reference-id: CCC.Core.CP18
      - reference-id: SEC.SLAM.CM.CAP
        entries:
          - reference-id: SEC.SLAM.CM.CAP01

Step 4: Validate

The final YAML should look something like this:

title: Container Management Tool Security Threat Catalog

metadata:
  id: SEC.SLAM.CM
  type: ThreatCatalog
  gemara-version: "1.0.0"
  description: Threat catalog for container management tool security assessment
  version: 1.0.0
  author:
    id: example
    name: Example
    type: Human
  mapping-references:
    - id: CCC
      title: Common Cloud Controls Core
      version: v2025.10
      url: https://github.com/finos/common-cloud-controls/releases
      description: |
        Foundational repository of reusable security controls, capabilities,
        and threat models maintained by FINOS.
    - id: SEC.SLAM.CM.CAP
      title: Container Management Tool Security Capability Catalog
      version: "1.0.0"
      url: https://example.org/catalogs/SEC.SLAM.CM-capabilities.yaml
      description: |
        Scope-specific capabilities (CAP01, CAP02) for this threat assessment.

groups:
  - id: SEC.SLAM.CM.FAM01
    title: Image integrity and supply chain
    description: |
      Threats affecting container image retrieval, integrity, and trust.

imports:
  - reference-id: CCC
    entries:
      - reference-id: CCC.Core.CP29
        remarks: Active Ingestion
      - reference-id: CCC.Core.CP18
        remarks: Resource Versioning
      - reference-id: CCC.Core.TH14
        remarks: Older Resource Versions are Used

threats:
  - id: SEC.SLAM.CM.THR01
    title: Container Image Tampering or Poisoning
    description: |
      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.
    group: SEC.SLAM.CM.FAM01
    capabilities:
      - reference-id: CCC
        entries:
          - reference-id: CCC.Core.CP29
          - reference-id: CCC.Core.CP18
      - reference-id: SEC.SLAM.CM.CAP
        entries:
          - reference-id: SEC.SLAM.CM.CAP01

The complete tutorial adds more CCC imports and additional threats; see threat-catalog.yaml.

Validation commands:

go install cuelang.org/go/cmd/cue@latest
cue vet -c -d '#CapabilityCatalog' github.com/gemaraproj/gemara@v1 docs/tutorials/controls/your-capabilities.yaml
cue vet -c -d '#ThreatCatalog' github.com/gemaraproj/gemara@v1 docs/tutorials/controls/your-threat-catalog.yaml

What’s Next

Create a Gemara control catalog that maps security controls to these threats using the Control Catalog Guide.

Layer 2 schema documentation: