opskit-guard

Stop your AI agent from accidentally changing your Kubernetes cluster.

When you run an AI agent alongside kubectl, helm, or terraform, there's nothing stopping it from running a command you didn't intend. A misread context, a confident wrong answer, an annotation with instructions in it — any of these can turn an investigation into an incident.

opskit-guard is a pre-tool hook that blocks every mutation verb before it reaches your cluster. Install it once. It runs silently on every agent action and stops anything that would change state.

cp pre-tool-hook.sh .claude/hooks/pre-tool.sh
chmod +x .claude/hooks/pre-tool.sh

That's the entire install.

---

What it blocks

Every command that can change your cluster state — including the ones you wouldn't think to enumerate:

kubectl apply / create / delete / patch / scale / exec / port-forward
kubectl rollout restart / undo / drain / cordon / taint
helm install / upgrade / uninstall / rollback
argocd app sync / rollback / delete
flux reconcile / suspend / delete
terraform apply / destroy / state rm / import
aws ec2 terminate-instances
az vm delete / aks scale
gcloud compute instances delete

And the bypass attempts that defeat simple blocklists:

# These are all blocked too
kubectl --context prod apply -f x.yaml    # flag before verb
k apply -f x.yaml                         # the universal alias
sh -c "kubectl apply -f x.yaml"           # shell wrapper
kustomize build . | kubectl apply -f -    # pipe chain
OPSKIT_ALLOW=1 kubectl delete pod x       # inline env override
echo a3ViZWN0bA== | base64 -d | sh        # decode and execute

The engine tokenizes each command rather than pattern-matching it. Flags between the binary and verb, aliases, wrappers, and pipe chains are all handled. Read-only work — get, describe, logs, diff, plan — passes through without friction.

---

What it allows

Everything read-only continues to work normally:

kubectl get pods -n production
kubectl describe deployment api-gateway
kubectl logs payment-service --tail=200
helm list -A
helm get values my-release
terraform plan
terraform validate
argocd app get myapp
git log --oneline -20

No configuration needed for the common case. Strict mode is available in ~/.opskit/policy.yaml if you want an explicit allowlist rather than just mutation blocking.

---

Audit log

Every decision is written to ~/.opskit/logs/hook-YYYY-MM-DD.log:

2026-07-26T19:42:11Z BLOCKED kubectl apply -f /tmp/patch.yaml
  reason: kubectl apply mutates infrastructure state
2026-07-26T19:42:15Z ALLOWED kubectl get pods -n production

The log is append-only. You can see exactly what your agent tried and whether it was stopped.

---

Works with any agent

Drop the hook file into the right directory for your tool:

Tool	Path
Claude Code	.claude/hooks/pre-tool.sh
Kiro	.kiro/hooks/pre-tool.sh
Any SKILL.md-compatible tool	check your tool's hooks documentation

Note on Cursor and Codex CLI: these tools don't have a hook layer, so opskit-guard cannot intercept bash commands in them. The MCP server in the full OpsKit kit is still read-only, but there is no OS-level enforcement. Claude Code is recommended for production use.

---

Verify it's working

# Should exit 1 (blocked)
echo '{"tool_name":"Bash","tool_input":{"command":"kubectl apply -f x.yaml"}}' \
  | python3 guard.py; echo "exit: $?"

# Should exit 0 (allowed)
echo '{"tool_name":"Bash","tool_input":{"command":"kubectl get pods"}}' \
  | python3 guard.py; echo "exit: $?"

---

Requirements

• Python 3.8+ (standard on macOS and every mainstream Linux distro)
• No other dependencies

---

What opskit-guard is not

opskit-guard blocks mutation commands. It does not give your agent the ability to investigate anything — it only stops it from changing things.

If you want an agent that can actively read your cluster, correlate events and logs, diagnose failures, and propose fixes as a reviewed GitOps PR, that's the full OpsKit K8s Reliability Pack.

---

License

MIT — use it, fork it, ship it, audit it.