dsh-kubectl-guard
A DeepSeek Harness policy plugin that gates kubectl by kubeconfig context.
Irreversible verbs against a non-local cluster are denied outright. Recoverable writes ask first. Reads and local clusters are untouched.
It registers no tools of its own — it inspects the command argument of shell tool calls, so it covers whatever the agent runs.
Install
Requires pnpm, which dsh plugin shells out to.
From npm:
dsh plugin --profile web add dsh-kubectl-guard
From source, if you want to hack on it:
git clone https://github.com/gengwg/dsh-kubectl-guard
cd dsh-kubectl-guard
dsh plugin --profile web add "$PWD"
Either way, activation is automatic: the package declares dsh.bundle, so
dsh plugin add joins it to the profile's bundle stack. Restart dsh to load it.
Upgrading from 0.1.x, which installed as a plain dependency: delete the manual
insert entry from ~/.dsh/profiles/<profile>/cordis.patch.yml. Bundle and user
patch layers both apply, so leaving it in loads the guard twice.
Examples
Nothing to invoke. Ask the agent to do its normal work; the guard sits in the
tool pipeline and inspects the shell command before it runs.
Blocked, with the cluster name replaced by a per-session pseudonym:
> delete the stuck nginx pod
Error: kubectl-guard: 'delete' is irreversible and ctx#4be1f92a is not a local
cluster. Denied.
Asked, so you approve it in the UI before it runs:
> roll out the new deployment
kubectl-guard: 'apply' writes to ctx#4be1f92a, which is not a local cluster.
[approve] [deny]
Untouched, because reads are not gated:
> what pods are failing in kube-system?
kubectl get pods -n kube-system --field-selector=status.phase!=Running
NAME READY STATUS RESTARTS
api-7d9f8c 0/1 CrashLoopBackOff 14
Untouched, because the context is local:
> wipe the test namespace on my kind cluster
kubectl --context kind-dev delete ns test
namespace "test" deleted
Dry runs are reads, so they pass and give the agent a way to show you a change
before asking for it:
kubectl apply --dry-run=server -f deploy.yaml # allowed
kubectl apply -f deploy.yaml # asks
Turn the guard off for one session without editing config:
dsh web --patch <(echo '- id: kubectl-guard
disabled: true')
Behavior
| Command | Non-local context | Local context |
|---|
get, describe, logs, top | allow | allow |
auth can-i | allow | allow |
auth reconcile | ask | allow |
config use-context, other mutating config subcommands | ask | ask |
apply, patch, scale, exec | ask | allow |
delete, drain, evict | deny | allow |
scale --replicas=0 | deny | allow |
apply --prune | deny | allow |
replace --force | deny | allow |
apply --dry-run=server | allow | allow |
A context is local only if it matches localContexts. Everything else, including a kubeconfig that cannot be read, is treated as production.
The context is resolved the way the shell would resolve it: an explicit
--context wins, then --kubeconfig, then a KUBECONFIG= assignment written
inline on the same command line, then the ambient environment. That last case
matters -- without it, KUBECONFIG=/path/to/prod kubectl delete ... would be
judged against whatever your shell happened to point at.
Config
config:
localContexts: [minikube, 'kind-*', docker-desktop]
binaries: [kubectl, k]
guardedTools: [bash, pwsh]
showContextNames: false
showContextNames is off by default: blocked-command messages go to the model, and therefore to the LLM provider. With it off the model sees a stable per-session pseudonym like ctx#4be1f92a instead of your cluster's name.
Failing closed
A gate that can be talked around is worse than none. Anything unparseable — sh -c, command substitution, an unterminated quote — is treated as a mutation: denied if the text contains an irreversible verb, asked otherwise. An unknown verb asks rather than allows.
What this is not
This gates a cooperative agent, not an adversary. It reads the command string
the agent asked to run, so anything that hides the binary name from that string
defeats it by construction -- $KUBECTL delete ... with the name only in the
environment, a shell alias resolved at runtime, a base64 round-trip.
Indirection that still contains the literal name is caught: K=kubectl; $K delete pod foo is denied, because any $ expansion alongside a mention of a
guarded binary makes the command opaque, and opaque plus an irreversible verb
is a denial. But treat the guard as a seatbelt against a confused agent, not a
sandbox against a hostile one. If you need the stronger property, take the
credential away rather than filtering the command.
Limitations
- Only
kubectl. helm, argocd and flux are not covered; the verb table is data, so adding them is an edit to src/verbs.js.
- Pass-through wrappers (
sudo, time, nice, ...) are seen through, but only until a bare-token wrapper argument: timeout 30 kubectl delete ... is not gated, because 30 ends the wrapper chain.
current-context is read with a line-anchored regex, not a YAML parser. Unreadable or unmatched means production, so the failure direction is safe.- The pseudonym salt is per-process: ids are stable within a session, not across restarts.
- Guards are synchronous, so the deny path does no I/O beyond a cached
readFileSync.
Test
npm test
MIT.
