sica-fondt/knowledge/cyber-skills/skills/implementing-pod-security-admission-controller/references/api-reference.md

API Reference: Kubernetes Pod Security Admission Controller

Libraries Used

Library	Purpose
kubernetes	Official Kubernetes Python client for cluster API access
json	Parse and format admission review payloads
yaml	Read and write Pod Security Standard label configurations

Installation

pip install kubernetes pyyaml

Authentication

from kubernetes import client, config

# In-cluster (running inside a pod)
config.load_incluster_config()

# Local kubeconfig
config.load_kube_config(context="my-cluster")

v1 = client.CoreV1Api()

Pod Security Standards Levels

Level	Description
privileged	Unrestricted — no restrictions applied
baseline	Minimally restrictive — prevents known privilege escalation
restricted	Heavily restricted — follows hardening best practices

Namespace Label API

Pod Security Admission is configured via namespace labels:

Label	Purpose
pod-security.kubernetes.io/enforce	Reject pods that violate the policy
pod-security.kubernetes.io/enforce-version	Pin policy to specific k8s version
pod-security.kubernetes.io/audit	Log violations in audit log
pod-security.kubernetes.io/audit-version	Pin audit policy version
pod-security.kubernetes.io/warn	Show warnings to kubectl users
pod-security.kubernetes.io/warn-version	Pin warning policy version

Core Operations

List Namespaces with PSA Labels

namespaces = v1.list_namespace()
for ns in namespaces.items:
    labels = ns.metadata.labels or {}
    enforce = labels.get("pod-security.kubernetes.io/enforce", "none")
    audit = labels.get("pod-security.kubernetes.io/audit", "none")
    warn = labels.get("pod-security.kubernetes.io/warn", "none")
    print(f"{ns.metadata.name}: enforce={enforce} audit={audit} warn={warn}")

Apply PSA Labels to a Namespace

body = {
    "metadata": {
        "labels": {
            "pod-security.kubernetes.io/enforce": "restricted",
            "pod-security.kubernetes.io/enforce-version": "latest",
            "pod-security.kubernetes.io/audit": "restricted",
            "pod-security.kubernetes.io/warn": "restricted",
        }
    }
}
v1.patch_namespace(name="production", body=body)

Audit All Namespaces for Missing PSA Labels

def audit_psa_labels():
    findings = []
    namespaces = v1.list_namespace()
    for ns in namespaces.items:
        name = ns.metadata.name
        labels = ns.metadata.labels or {}
        if name in ("kube-system", "kube-public", "kube-node-lease"):
            continue
        enforce = labels.get("pod-security.kubernetes.io/enforce")
        if not enforce:
            findings.append({"namespace": name, "issue": "no enforce label"})
        elif enforce == "privileged":
            findings.append({"namespace": name, "issue": "enforce=privileged"})
    return findings

Check Pod Violations Against a Level

def check_pod_security(namespace, level="restricted"):
    pods = v1.list_namespaced_pod(namespace=namespace)
    violations = []
    for pod in pods.items:
        for container in pod.spec.containers:
            sc = container.security_context
            if not sc:
                violations.append({
                    "pod": pod.metadata.name,
                    "container": container.name,
                    "issue": "no securityContext defined",
                })
                continue
            if sc.privileged:
                violations.append({
                    "pod": pod.metadata.name,
                    "container": container.name,
                    "issue": "privileged=true",
                })
            if sc.run_as_non_root is not True:
                violations.append({
                    "pod": pod.metadata.name,
                    "container": container.name,
                    "issue": "runAsNonRoot not set",
                })
            caps = sc.capabilities
            if level == "restricted" and (not caps or not caps.drop or "ALL" not in caps.drop):
                violations.append({
                    "pod": pod.metadata.name,
                    "container": container.name,
                    "issue": "capabilities.drop does not include ALL",
                })
    return violations

kubectl Equivalents

# Label a namespace with restricted enforcement
kubectl label namespace production \
  pod-security.kubernetes.io/enforce=restricted \
  pod-security.kubernetes.io/warn=restricted \
  --overwrite

# Dry-run to test impact before enforcing
kubectl label --dry-run=server --overwrite namespace production \
  pod-security.kubernetes.io/enforce=restricted

# Check which namespaces have PSA labels
kubectl get namespaces -L pod-security.kubernetes.io/enforce

Output Format

{
  "namespace": "production",
  "enforce_level": "restricted",
  "audit_level": "restricted",
  "warn_level": "restricted",
  "pod_violations": [
    {
      "pod": "legacy-app-7f8b9c",
      "container": "app",
      "issue": "privileged=true"
    }
  ],
  "compliant": false
}