[Question] Should we support Capability Profiles?

[jpower432]

Motivation

Organizations need to inventory their system capabilities in domain-specific terms. A Kubernetes team thinks in API resources and admission controllers. A Linux security team thinks in kernel capabilities and syscalls. An identity governance team thinks in the authorization surface their system exposes.

Today, #CapabilityCatalog gives them id, title, description, and group, enough to name a capability, but not
enough to describe it in the language of the domain.

What is a Capability?

A Gemara capability describes what a system can do, a feature, component, or object. Capabilities are neutral: they flow
into threats (how the capability can be exploited), controls (how to mitigate), and assessments (how to verify). They are
properties of the system, not of the users or policies that govern the system.

For example:

• "The system can pull container images by tag", a capability. It can be exploited (tag mutation attacks), controlled
  (require digest-based references), and assessed (verify no tag-only references in deployment configs).
• "The system exposes a funds transfer API", also a capability. The system is capable of moving money between accounts. The
  threat is unauthorized access to that surface. The control is proper authorization enforcement.

Profiles add domain-specific structure to these capabilities. A Kubernetes profile adds API group and admission controller
fields. An identity profile adds the action and resource that describe the authorization surface the system exposes, what the system is capable of doing, not who is allowed to do it. That distinction matters: "the system exposes transfer on bank-account" is a capability; "Alice is authorized to transfer funds" is an entitlement, which is runtime policy and not a capability.

Capability Profiles

A profile is a CUE module that imports Gemara and refines #Capability via unification. No changes to the Gemara schema are
required.

GovOps snippet

EDITED to better match GovOps design

package authorization

import "github.com/gemaraproj/gemara@v1:gemara"

#AuthorizationCapability: {
    gemara.#Capability
    action:              string
    resource:            string
    "risk-tier"?:        "critical" | "high" | "medium" | "low"
    "data-sensitivity"?: "public" | "internal" | "confidential" | "restricted"
}

#AuthorizationCapabilityCatalog: {
    gemara.#CapabilityCatalog
    capabilities: [#AuthorizationCapability, ...#AuthorizationCapability]
}

Kubernetes

package kubernetes

import "github.com/gemaraproj/gemara@v1:gemara"

#KubernetesCapability: {
    gemara.#Capability
    "api-group"?:    string
    "api-resource":  string
    verb:            "get" | "list" | "watch" | "create" | "update" | "patch" | "delete" | "deletecollection"
    namespaced:      bool
}

#KubernetesCapabilityCatalog: {
    gemara.#CapabilityCatalog
    capabilities: [#KubernetesCapability, ...#KubernetesCapability]
}

Linux

package linux

import "github.com/gemaraproj/gemara@v1:gemara"

#LinuxCapability: {
    gemara.#Capability
    "linux-capability": string
    syscalls?: [string, ...string]
    "privilege-required": bool
}

#LinuxCapabilityCatalog: {
    gemara.#CapabilityCatalog
    capabilities: [#LinuxCapability, ...#LinuxCapability]
}

Cloud

package cloud

import "github.com/gemaraproj/gemara@v1:gemara"

#CloudCapability: {
    gemara.#Capability
    provider:           string
    service:            string
    "iam-action"?:      string
    "deployment-model": "public" | "private" | "hybrid"
}

#CloudCapabilityCatalog: {
    gemara.#CapabilityCatalog
    capabilities: [#CloudCapability, ...#CloudCapability]
}

Example: Base Capability Catalog (no profile)

A plain #CapabilityCatalog — what Gemara supports today:

title: Acme Capability Catalog

metadata:
  id: ACME-CAP
  type: CapabilityCatalog
  gemara-version: "1.0.0"
  version: "1.0.0"
  description: Core capabilities for the Acme platform.
  author:
    id: acme-security
    name: Acme Security Team
    type: Human

groups:
  - id: access-control
    title: Access Control
    description: Capabilities related to authentication and authorization.
  - id: workloads
    title: Workloads
    description: Capabilities related to workload orchestration.

capabilities:
  - id: CAP-AC-001
    title: User authentication
    description: Ability to authenticate users against an identity provider.
    group: access-control
  - id: CAP-WL-001
    title: Container orchestration
    description: Ability to schedule and manage containerized workloads.
    group: workloads

Example: Identity Profile

The authorization surface of a banking system. Each capability describes what the system exposes, not who is authorized to
use it. Validates as both #IdentityCapabilityCatalog and #CapabilityCatalog:

title: Acme Bank Identity Capability Catalog

metadata:
  id: ACME-IDN
  type: CapabilityCatalog
  gemara-version: "1.0.0"
  version: "0.1.0"
  description: Authorization surface capabilities for Acme Bank's core banking platform.
  author:
    id: acme-security
    name: Acme Security Team
    type: Human

groups:
  - id: payments
    title: Payments
    description: Capabilities related to funds movement and payment processing.
  - id: lending
    title: Lending
    description: Capabilities related to loan origination and management.

capabilities:
  - id: CAP-PAY-001
    title: Transfer funds
    description: The system exposes the ability to initiate funds transfers between bank accounts.
    group: payments
    action: transfer
    resource: bank-account
    risk-tier: critical
    data-sensitivity: confidential
  - id: CAP-PAY-002
    title: View transaction history
    description: The system exposes the ability to read transaction records for a bank account.
    group: payments
    action: read
    resource: transaction
    risk-tier: medium
    data-sensitivity: confidential
  - id: CAP-LND-001
    title: Approve loan
    description: The system exposes the ability to approve a loan application for disbursement.
    group: lending
    action: approve
    resource: loan
    risk-tier: critical
    data-sensitivity: restricted

Example: Kubernetes Profile

Security-relevant capabilities of a Kubernetes cluster. Validates as both #KubernetesCapabilityCatalog and
#CapabilityCatalog:

title: Acme Kubernetes Capability Catalog

metadata:
  id: ACME-K8S
  type: CapabilityCatalog
  gemara-version: "1.0.0"
  version: "0.1.0"
  description: Kubernetes workload capabilities for the Acme platform.
  author:
    id: acme-platform
    name: Acme Platform Team
    type: Human

groups:
  - id: workloads
    title: Workloads
    description: Capabilities related to pod and deployment management.
  - id: secrets
    title: Secrets
    description: Capabilities related to secret and config management.

capabilities:
  - id: CAP-K8S-001
    title: Create deployments
    description: The cluster can create deployment resources in application namespaces.
    group: workloads
    api-group: apps
    api-resource: deployments
    verb: create
    namespaced: true
  - id: CAP-K8S-002
    title: List pods
    description: The cluster can list running pods across namespaces.
    group: workloads
    api-group: ""
    api-resource: pods
    verb: list
    namespaced: true
  - id: CAP-K8S-003
    title: Read secrets
    description: The cluster can read secret values in application namespaces.
    group: secrets
    api-group: ""
    api-resource: secrets
    verb: get
    namespaced: true

Example: Linux Profile

Linux kernel capabilities required by container workloads. Validates as both #LinuxCapabilityCatalog and
#CapabilityCatalog:

title: Acme Linux Capability Catalog

metadata:
  id: ACME-LNX
  type: CapabilityCatalog
  gemara-version: "1.0.0"
  version: "0.1.0"
  description: Linux kernel capabilities required by Acme container workloads.
  author:
    id: acme-platform
    name: Acme Platform Team
    type: Human

groups:
  - id: networking
    title: Networking
    description: Capabilities related to network operations.
  - id: process
    title: Process Management
    description: Capabilities related to process and signal handling.

capabilities:
  - id: CAP-LNX-001
    title: Bind privileged ports
    description: The system can bind to TCP/UDP ports below 1024.
    group: networking
    linux-capability: CAP_NET_BIND_SERVICE
    syscalls:
      - bind
    privilege-required: false
  - id: CAP-LNX-002
    title: Raw network access
    description: The system can use raw and packet sockets.
    group: networking
    linux-capability: CAP_NET_RAW
    syscalls:
      - socket
    privilege-required: true
  - id: CAP-LNX-003
    title: Send signals to processes
    description: The system can send signals to arbitrary processes.
    group: process
    linux-capability: CAP_KILL
    syscalls:
      - kill
      - tkill
      - tgkill
    privilege-required: true

Validation

# Base — works with any of the YAMLs above
cue vet example.yaml -d '#CapabilityCatalog'

# Single profile
cue vet k8s-example.yaml -d '#KubernetesCapabilityCatalog'
cue vet linux-example.yaml -d '#LinuxCapabilityCatalog'
cue vet identity-example.yaml -d '#IdentityCapabilityCatalog'

# Composed
cue vet cloud-k8s-example.yaml -d '#ComposedCapabilityCatalog'

Why this works

• No Gemara schema changes required. Profiles import Gemara as a dependency.
• Backward compatible. Profile-extended YAML validates against both the profile schema and the base #CapabilityCatalog.
• Composable. CUE unification handles multi-profile catalogs naturally.
• Independent versioning. Each profile module has its own lifecycle — community-maintained or organization-specific.

Prior art

This idea was motivated by the GovOps Technical Initiative proposal from @nynymike, which proposes an Authorization Capability Catalog as the first consumer of this pattern. The design document details the identity profile shape and phased adoption path.

[jpower432]

Adding a note here: all profiles suggestions and snippets here are purely demonstrative to explore how profiles could be useful to the community. They are not intended to represent final fields for specific profiles.