Documentation

• 1: Overview
• 2: Getting Started
• 3: Examples
• 4: Concepts

1 - Overview

What is Kudo?

Kudo is a Kubernetes controller that allows individual users to temporarily escalate their permissions while still maintaining security and crystal clear auditability.

It comes in complement of existing access control systems (Kubernetes RBAC, GCP IAM), and relies on them to temporarily grant or reclaim permissions. In the context of Kubernetes, Kudo temporarily creates a RoleBinding or a ClusterRoleBinding between an existing role and the escalation requestor.

It is built around two main concepts, defined as Kubernetes Custom Resources:

• Escalation Policies: Created by the cluster administrators, escalation policies defines the “rules” of escalations. To be more specific, it defines who has the right to escalate, what needs to be checked when the escalation is created, and what escalating grants.
• Escalations are created by users who want to escalate temporarily their permissions and refers to a policy. If the escalation is accepted, kudo grants temporarily new permissions, and reclaims them when the escalation expires.

Why Allowing Users to Escalate ?

Defining minimal and secure authorization model is a difficult exercise, because it is often hard to predict which permissions people are going to need to actually get their job done. In many situations, this model is limiting and people need to temporarily bypass it.

Let’s take an example: What happens when someone asks to temporarily get more permissions? Your administration team grants them after checking if their demand is legit. Then they may or may not reclaim those permissions… depending on if they think about it or not!

At best this is tedious work, at worst this becomes a security issue!

Kudo aims to address this growing pains by automating the process of escalating while still maintaining a high level of security.

In other words, Kudo allows you to:

• Enforce a minimal set of permissions default, to implement the principle of least privilege.
• Provision escalation policies, to define precisely who has the right to get what.
• Get your users to easilly escalate their permissions, without having to ask an administrator, while still maintaining security. No friction for them, less work for your admins!
• Control who’s escalating, by defining escalation challenges. For example requiring an escalation to be approved by a peer from another team before being granted.
• Temporarily Grant permissions across systems: could it be Kubernetes RBAC, AWS or GCP IAM. It all boils done to what the escalation policy defines.
• Audit escalations: Automatically record escalation events into third party systems to keep a trail of what happened.

Where should I go next?

Interested into going deeper? Feel free to check out the following sections:

• Getting Started: Get started with Kudo
• Core Concepts: Get to know Kudo core concepts
• Examples: Check out some example use cases for Kudo!

2 - Getting Started

Prerequisites

• Kubernetes 1.24 (earlier versions might work but we haven’t tested it yet).
• Helm 3

Installation

Kudo has no release yet so we can’t properly document this.

Installing the Controller

This will probably look like helm install -f values.yaml -n kudo kudo/kudo-controller kudo-controller

We need to mention here:

• A cert is generated in the helm chart, so people need to be cautious about this. We also need to provide a way of refreshing the cert (I’m thinking helm template only the cert file, but this needs to be tested.)

Installing the kubectl Plugin

I would say kubectl krew install kudo but only future will tell.

Setup

Refers to the examples page to get examples.

3 - Examples

Grant Port Forward On Some Namespaces

This example walks you through defining a ClusterRole and an EscalationPolicy that allows your user to temporarily get the port-forward permission on two different namespaces.

First, let’s define a ClusterRole that grants the create pods/portforward permission.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: port-forwarder
rules:
- apiGroups: [""]
  resources: ["pods/portforward"]
  verbs: ["create"]

Defining a cluster role by itself doesn’t do much. Let’s define an EscalationPolicy to allow our users to use this new-role.

apiVersion: k8s.kudo.dev/v1alpha1
kind: EscalationPolicy
metadata:
  name: gain-port-forward
spec:
  subjects:
    - kind: Group
      name: system:authenticated # All the authenticated users.
  challenges:
    - kind: PeerReview
      reviewers:
        - kind: Group
          name: admin@my-company.io
  target:
    defaultDuration: 60m
    maxDuration: 4h
    grants:
    - kind: KubernetesRoleBinding
      defaultNamespace: application-a
      allowedNamespaces:
        - application-a
        - application-b
      roleRef:
        kind: ClusterRole
        name: port-forwarder
        apiGroup: rbac.authorization.k8s.io

Let’s review the configuration, This EscalationPolicy call gain-port-forward translates to the following statements:

• The subjects section tells that all the authenticated users are allowed to escalate using this policy
• The challenges sections tells that an escalation using this policy must be approved by one member of the group admin@my-company.io
• The target sections defines what the escalation actually grants:
  • Kudo will create a RoleBinding between the requestor and the role port-forwarder by default in the application-a namespace, but is allowed to be used in the application-a and application-b namespace.
  • The escalation lasts 60 minutes by default, but users can ask up to 4h.

From there, you can escalate using this policy using kudo kubectl plugin:

kubectl kudo escalate gain-port-forward --namespace application-b --reason "need to debug application B, ticket #3939"

4 - Concepts

Core Concepts

Escalation Policy

An escalation policy define a possible path to escalation. It is composed by the following sections:

• subjects: list of principals allowed to use the policy. A principal is expressed as a Kind (being potentially Group or User) and a name which could be either an user identifier or a Kubernetes group name. This is the same model than the one Kubernetes RBAC uses for ClusterRoleBindings and RoleBindings.
• challenges: Expresses a list of verifications that have to be performed at escalation time. For example, this where you specify that an escalations needs to be peer reviewed by a member of another group.
• target: Defines what the escalation actually grants. It is composed by common settings like how much time this escalation is actually valid and also a one or more esclation grants, which represent an action to be done to actually grant permissions. For example, the escalation grant KubernetesRoleBinding tells Kudo to create a role binding in the requested namespace.

# Grants any members of squad-a the authorization to gain the RBAC role `some-escalated-role`
# on the namespace `some-app` for 60 minutes if and only if a member of squad-b approves the escalation
---
apiVersion: k8s.kudo.dev/v1alpha1
kind: EscalationPolicy
metadata:
  name: rbac-escalation-example
spec:
  subjects: # (required) who has the right to trigger this escalation.
    - kind: Group
      name: squad-a@group.com
  challenges: # (optional) list of challenges being applied when esclating.
    - kind: PeerReview
      reviewers:
        - kind: Group
          name: squad-b@voiapp.io
  target: # (required) what the escalation grants
    defaultDuration: 60m
    maxDuration: 2h
    grants:
    - kind: KubernetesRoleBinding
      defaultNamespace: some-app
      allowedNamespaces:
        - some-app
        - some-other-app
      roleRef:
        kind: ClusterRole
        name: some-escalated-role
        apiGroup: rbac.authorization.k8s.io

Escalation

An escalation represents the actual demand of permission escalation by an user.

It is composed by the following attributes:

• spec: spec of the escalation

  • policyName: name of the policy being used to escalate
  • requestor: identifier of the user asking for permission escalation
  • reason: a reason to explain why the user is asking to escalate their permissions
  • namespace: (optional) a namespace requested by the user.
  • duration: (optional) how much time the escalation should last.

• status: current status of the escalation:

  • state:
    • PENDING: the escalation is awaiting challenge completion
    • DENIED: user isn’t allowed to escalate, one of the challenges has failed or Kudo has defensively decided to deny the escalation.
    • ACCEPTED: the escalation is accepted and the user has now access to extended privileges
    • EXPIRED: the escalation has expired
  • stateDetails: some aditional information regarding the state
  • policyUID and PolicyResourceVersion: which policy resource instance is this escalation based on.
  • expiresAt when the escalation expires

• grantRefs: List of references to all the resource being granted by Kudo with their status.

  • status: status of the referenced resource (CREATED or RECLAIMED)
  • ref: grant specific information (kind, and metadata that allows to keep track of the resource)

---
apiVersion: k8s.kudo.dev/v1alpha1
kind: Escalation
metadata:
  name: escalation-abbdfff3
spec:
  policyName: rbac-escalation-exaple
  requestor: user-1@kubecluster.com
  reason: "Needs access to squad-b namespace to debug my service"
  duration: 2h
status:
  state: "ACCEPTED"
  stateDetails: "Escalation accepted, all resources are created"
  policyUID: aaa-bb-cc
  policyVersion: 484
  grantRefs:
    - status: "CREATED"
      ref:
        kind: KubernetesRoleBinding
        name: binding-343df
        namespace: some-app
        UID: aaaa-bbb-ccc
        ResourceVersion: 493