access

Documentation

Overview

Package access provides tools for checking user permissions on Kubernetes clusters.

This package implements the "can_i" tool, which allows agents to query whether the authenticated user has permission to perform specific actions before attempting them. This provides better user experience by failing fast with clear error messages and reduces noise in Kubernetes audit logs from failed requests.

Security Model

The can_i tool uses Kubernetes SelfSubjectAccessReview to check permissions. Because the MCP server uses user impersonation, the access check is performed as the authenticated user, not with elevated admin credentials.

Usage Examples

Check if user can delete pods in a namespace:

{
  "verb": "delete",
  "resource": "pods",
  "namespace": "production"
}

Check if user can create deployments cluster-wide:

{
  "verb": "create",
  "resource": "deployments",
  "apiGroup": "apps"
}

Check access on a specific workload cluster:

{
  "verb": "list",
  "resource": "secrets",
  "namespace": "kube-system",
  "cluster": "prod-cluster-01"
}

Index

• Variables
• func HandleCanI(ctx context.Context, request mcp.CallToolRequest, sc *server.ServerContext) (*mcp.CallToolResult, error)
• func RegisterTools(mcpServer *server.MCPServer, sc *mcpserver.ServerContext)
• type AccessCheckInfo
• type CanIResponse

Variables

var CanITool = mcp.NewTool("can_i",
	mcp.WithDescription("Check if you have permission to perform an action on a Kubernetes resource. "+
		"Use this before attempting operations to get clear feedback about permissions."),
	mcp.WithString("verb",
		mcp.Required(),
		mcp.Description("The action to check (get, list, watch, create, update, patch, delete)"),
	),
	mcp.WithString("resource",
		mcp.Required(),
		mcp.Description("The resource type to check (pods, deployments, secrets, etc.)"),
	),
	mcp.WithString("apiGroup",
		mcp.Description("API group for the resource (empty for core resources, 'apps' for deployments, etc.)"),
	),
	mcp.WithString("namespace",
		mcp.Description("Namespace to check permissions in (empty for cluster-scoped resources)"),
	),
	mcp.WithString("name",
		mcp.Description("Specific resource name to check (optional, for fine-grained checks)"),
	),
	mcp.WithString("subresource",
		mcp.Description("Subresource to check (e.g., 'logs', 'exec', 'portforward' for pods)"),
	),
	mcp.WithString("cluster",
		mcp.Description("Target cluster name (empty for local/management cluster)"),
	),
)

CanITool allows agents to check if the authenticated user has permission to perform a specific action on a Kubernetes resource.

This tool uses SelfSubjectAccessReview to verify permissions before attempting operations, providing better error messages and reducing audit log noise.

Functions

func HandleCanI

func HandleCanI(ctx context.Context, request mcp.CallToolRequest, sc *server.ServerContext) (*mcp.CallToolResult, error)

HandleCanI handles the can_i tool request.

This function performs a SelfSubjectAccessReview to check if the authenticated user has permission to perform the specified action.

Security Model

The check is performed using user impersonation, so the result reflects the actual permissions the user would have when performing the operation. This requires federation mode to be enabled.

func RegisterTools

func RegisterTools(mcpServer *server.MCPServer, sc *mcpserver.ServerContext)

RegisterTools registers the access tools with the MCP server.

Types

type AccessCheckInfo

type AccessCheckInfo struct {
	Verb        string `json:"verb"`
	Resource    string `json:"resource"`
	APIGroup    string `json:"apiGroup,omitempty"`
	Namespace   string `json:"namespace,omitempty"`
	Name        string `json:"name,omitempty"`
	Subresource string `json:"subresource,omitempty"`
}

AccessCheckInfo contains the parameters used in the access check.

type CanIResponse

type CanIResponse struct {
	// Allowed indicates whether the requested action is permitted.
	Allowed bool `json:"allowed"`

	// Denied indicates whether the action was explicitly denied.
	Denied bool `json:"denied,omitempty"`

	// Reason provides explanation of the decision.
	Reason string `json:"reason,omitempty"`

	// User is the email of the user for whom the check was performed.
	User string `json:"user"`

	// Cluster is the target cluster name.
	Cluster string `json:"cluster,omitempty"`

	// Check contains the access check parameters that were evaluated.
	Check *AccessCheckInfo `json:"check"`
}

CanIResponse represents the response from the can_i tool.