The problem
An AI agent with kubectl access is one hallucinated command away from kubectl delete namespace prod, a drain, an apply to the wrong context, or a get secret -o yaml that leaks credentials into the transcript. Permission prompts help — until you run in acceptEdits or --dangerously-skip-permissions and rubber-stamp everything.
"Your AI agent should not have direct kubectl access." — and yet you want it to help.
The solution
kube-guard is a pure Claude Code plugin (hook + skill + command, zero dependencies) that sits in front of the agent's shell. Every Bash command is parsed; any kubectl/helm invocation is classified and gated:
| Class | Examples | Default verdict (strict) |
|---|
| READ | get, describe, logs, top, rollout status, helm list | ✅ allow |
| WRITE | apply, scale, patch, edit, rollout restart, helm upgrade | ⚠️ ask (confirm) |
| DESTRUCTIVE | delete, drain, taint, replace --force, helm uninstall | 🛑 deny |
| HIGH-RISK | exec, run, cp, port-forward, config view, get secret -o yaml | 🛑 deny |
Plus cross-cutting guards: protected contexts/namespaces (anything matching prod, production, *-prod, kube-system, …) escalate every mutation to deny, and the guard fails closed — if it can't verify a command (eval, pipe-to-shell, subshells, intra-word quoting like k'ubectl', unknown verbs), it asks or denies rather than guessing.
A few things the classifier is deliberately careful about:
--dry-run is a safe preview. apply/delete/scale … --dry-run=server|client mutate nothing, so they're recognised as no-ops and allowed (but --dry-run=none really applies, so it isn't).- Secret dumps are hard to sneak past.
get secret -o yaml is blocked and so are -oyaml (no space), comma lists (secrets,configmaps), fully-qualified names (secret.v1.core/x), --template/--go-template, and helm get values/manifest/all.
- RBAC privilege escalation is gated.
kubectl auth reconcile, create clusterrolebinding … --clusterrole=cluster-admin, and apply --prune are escalated, not waved through as ordinary writes.
- When it blocks, it explains. A denied command comes back with the reason and a concrete next step (
--dry-run=server, /klease, -o name, …) so the agent self-corrects instead of retrying blind.
agent → kubectl delete ns prod → 🛑 DESTRUCTIVE on protected context — denied (logged)
agent → kubectl apply -f d.yaml → ⚠️ WRITE — asks you to confirm
agent → kubectl get pods → ✅ READ — allowed
Install
/plugin marketplace add andresleecom/kube-guard
/plugin install kube-guard@kube-guard
Requires kubectl on your PATH (which you already have). Zero npm dependencies.
Why it's different
It gates execution, even when you've turned permissions off:
- A
deny/ask from kube-guard applies regardless of permission mode — even with --dangerously-skip-permissions, a protected-context delete still stops.
- It catches kubectl anywhere in a command (
cd x && kubectl delete …, env-prefixes, pipes), not just as the first word.
- It resolves your current context so guards work even when the command omits
--context.
- Every decision is written to a private, gitignored audit log (
.claude/kube-guard/audit.jsonl), with secrets redacted.
