gengwg/dsh-kubectl-guard

dsh-kubectl-guard

Awesome
Listed on dsh-plugin.org
npm

一个 DeepSeek Harness 策略插件，按 kubeconfig 上下文对 kubectl 进行管控。

针对非本地集群的不可逆操作会被直接拒绝。可恢复的写操作会先询问。读操作和本地集群不受影响。

它不注册自己的工具——它检查 shell 工具调用的 command 参数，因此无论 agent 运行什么都能覆盖。

安装

需要 pnpm，dsh plugin 会调用它。

从 npm 安装：

dsh plugin --profile web add dsh-kubectl-guard

从源码安装，如果你想修改它：

git clone https://github.com/gengwg/dsh-kubectl-guard
cd dsh-kubectl-guard
dsh plugin --profile web add "$PWD"

无论哪种方式，激活都是自动的：该包声明了 dsh.bundle，因此
dsh plugin add 会将其加入 profile 的 bundle 栈。重启 dsh 以加载它。

从 0.1.x 升级时（当时作为普通依赖安装）：从
~/.dsh/profiles//cordis.patch.yml 中删除手动插入的条目。Bundle 层和用户
patch 层都会生效，所以保留它会导致 guard 被加载两次。

示例

无需调用任何东西。让 agent 做它的正常工作；guard 位于
工具流水线中，在 shell 命令运行前对其进行检查。

被阻止，集群名称被替换为每会话的假名：

delete the stuck nginx pod

Error: kubectl-guard: 'delete' is irreversible and ctx#4be1f92a is not a local
cluster. Denied.

被询问，因此你需要在 UI 中批准后它才会运行：

roll out the new deployment

kubectl-guard: 'apply' writes to ctx#4be1f92a, which is not a local cluster.
[approve] [deny]

不受影响，因为读操作不受管控：

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

不受影响，因为上下文是本地：

wipe the test namespace on my kind cluster

kubectl --context kind-dev delete ns test
namespace "test" deleted

Dry run 属于读操作，因此会通过，并给 agent 一种在请求批准前向你展示变更的方式：

kubectl apply --dry-run=server -f deploy.yaml     # allowed
kubectl apply -f deploy.yaml                      # asks

无需编辑配置即可为单个会话关闭 guard：

dsh web --patch <(echo '- id: kubectl-guard
disabled: true')

行为

| 命令 | 非本地上下文 | 本地上下文 |
|---|---|---|
| get、describe、logs、top | 允许 | 允许 |
| auth can-i | 允许 | 允许 |
| auth reconcile | 询问 | 允许 |
| config use-context、其他会修改状态的 config 子命令 | 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 |

只有当上下文匹配 localContexts 时，它才是本地上下文。其他所有情况，包括无法读取的 kubeconfig，都被视为生产环境。

上下文的解析方式与 shell 的解析方式一致：显式的
--context 优先，然后是 --kubeconfig，然后是在同一命令行中内联写入的
KUBECONFIG= 赋值，最后是环境变量。最后一种情况很重要——如果没有它，KUBECONFIG=/path/to/prod kubectl delete ... 将根据你的 shell 恰好指向的内容来判定。

配置

config:
localContexts: [minikube, 'kind-*', docker-desktop]
binaries: [kubectl, k]
guardedTools: [bash, pwsh]
showContextNames: false

showContextNames 默认关闭：被阻止命令的消息会发送给模型，因此也会发送给 LLM 提供商。关闭时，模型看到的是稳定的每会话假名，如 ctx#4be1f92a，而不是你的集群名称。

故障关闭

一个可以被绕过的门禁比没有更糟。任何无法解析的内容——sh -c、命令替换、未终止的引号——都被视为变更操作：如果文本包含不可逆动词则拒绝，否则询问。未知动词会询问而不是允许。

这不是什么

这约束的是一个配合的代理，而不是对手。它读取代理请求运行的命令字符串，
因此任何在该字符串中隐藏二进制名称的做法从构造上就能绕过它——$KUBECTL delete ... 且名称只在环境中、运行时解析的 shell 别名、base64 往返。

仍然包含字面名称的间接方式会被捕获：K=kubectl; $K
delete pod foo 会被拒绝，因为任何 $ 展开与受保护二进制名称同时出现都会使命令不透明，而不透明加上不可逆动词就是拒绝。但请把该防护视为防止混乱代理的安全带，而不是防止恶意代理的沙箱。如果你需要更强的属性，请拿走凭据，而不是过滤命令。

限制

- 仅支持 kubectl。helm、argocd 和 flux 未覆盖；动词表是数据，因此添加它们只需编辑 src/verbs.js。
- 透传包装器（sudo、time、nice、...）会被看穿，但只到裸令牌包装器参数为止：timeout 30 kubectl delete ... 不会被约束，因为 30 终止了包装器链。
- current-context 使用行锚定正则表达式读取，而不是 YAML 解析器。不可读或不匹配意味着生产环境，因此失败方向是安全的。
- 假名盐是每进程的：id 在会话内稳定，跨重启不稳定。
- 防护是同步的，因此拒绝路径除了缓存的 readFileSync 之外不做 I/O。

测试

npm test

MIT。