k8s-secure-cli

一个安全的 CLI 工具，用于管理多个 Kubernetes 集群的 kubeconfig 凭证，防止 AI 助手直接读取敏感配置文件。

为什么需要 k8s-secure-cli？

当使用 AI 助手（如 Claude、GPT 等）时，它们经常会尝试直接读取 ~/.kube/config 文件，这可能导致凭证泄露。本工具提供了一种安全管理多个 Kubernetes 集群配置的方式：

• 防止凭证泄露 - 凭证被加密并单独存储
• 受控访问 - AI 通过此工具间接访问，不直接读取 kubeconfig
• 审批机制 - 危险命令需要明确批准
• 多集群支持 - 轻松切换不同的 k8s 环境

特性

• 🔐 AES-256-GCM 加密 - PBKDF2 密钥派生（600,000 次迭代）
• 🌶️ Pepper 机制 - 额外安全层
• 🛡️ 防御深度审批 - 多层命令审批策略
• 🛡️ 受保护命名空间 - 系统命名空间和自定义命名空间保护
• 🔏 完整性保护 - HMAC 签名防止数据库篡改
• 📁 安全临时文件 - O_EXCL 原子创建，覆写后删除
• ⚡ LRU 缓存 - 性能优化，TTL 过期
• 📊 SQLite 存储 - 加密凭证存储，WAL 模式
• 🐚 Per-Shell Context - 每个 shell 窗口独立环境

安装

# 克隆仓库
git clone <repository-url>
cd k8s-secure-cli

# 安装依赖
npm install

# 构建
npm run build

# 全局链接（可选）
npm link

快速开始

1. 设置主密码

# 推荐：使用文件（更安全）
echo "your-secure-password-here" > ~/.k8s-master-password
chmod 400 ~/.k8s-master-password
export K8S_MASTER_PASSWORD_FILE=~/.k8s-master-password

# 备选：环境变量（较不安全）
export K8S_MASTER_PASSWORD="your-secure-password-here"

密码要求：

• 最少 16 个字符
• 至少包含 3 种：小写、大写、数字、特殊字符

2. 添加集群

# 从 kubeconfig 文件添加
k8s add ./my-kubeconfig.yaml --name prod-cluster

# 从当前 kubectl context 导入
k8s add ./my-kubeconfig.yaml --name prod-cluster --from-current

# 指定环境标签
k8s add ./my-kubeconfig.yaml --name prod-cluster --env prod

3. 列出集群

k8s list
k8s list --env prod

4. 切换环境

k8s use prod-cluster

5. 执行 kubectl 命令

# 安全命令立即执行
k8s exec get pods
k8s exec get deployments -n default

# 危险命令需要审批
k8s exec delete pod/my-pod
# > ⚠️  此命令需要审批: delete pod/my-pod
# > 批准? (y/N):

命令

| 命令 | 描述 | |------|------| | k8s add <file> --name <name> | 从 kubeconfig 文件添加配置 | | k8s list 或 k8s ls | 列出所有存储的配置 | | k8s use <name> | 设置当前环境（支持 per-shell） | | k8s exec [args...] | 执行 kubectl 命令 | | k8s test [name] | 测试集群连接 | | k8s remove <name> 或 k8s rm <name> | 删除配置 | | k8s protect add <namespace> | 添加受保护的命名空间 | | k8s protect remove <namespace> | 移除受保护的命名空间 | | k8s protect list | 列出受保护的命名空间 |

Per-Shell Context

k8s use 命令支持每个 shell 窗口独立的环境：

# 在终端窗口 A
k8s use prod
# 输出: export K8S_CURRENT_CONTEXT=prod

# 在终端窗口 B
k8s use staging
# 输出: export K8S_CURRENT_CONTEXT=staging

# 每个窗口的 context 是独立的

要持久化 per-shell context，将输出的 export 语句添加到 shell 配置文件：

# 添加到 ~/.zshrc 或 ~/.bashrc
export K8S_CURRENT_CONTEXT=prod

受保护命名空间

系统命名空间（kube-system、kube-public、kube-node-lease、k3s-system）始终受保护，禁止执行危险命令。

# 添加自定义受保护命名空间
k8s protect add production --context my-cluster

# 列出受保护命名空间
k8s protect list

# 移除受保护命名空间（不能移除系统命名空间）
k8s protect remove production --context my-cluster

完整性保护

protected_namespaces 表使用 HMAC 签名保护，防止攻击者直接修改数据库绕过保护：

• 单条记录 HMAC - 检测记录修改攻击
• 全局表签名 - 检测记录删除/添加攻击
• 启动时验证 - 自动检测并警告篡改

如果检测到篡改，系统会在启动时显示警告：

⚠️  Integrity check detected issues:
  - Modified record: my-cluster/production
  - Possible deletion/addition attack on context: my-cluster

Run "k8s protect repair" to fix integrity issues.

安全模型

加密

| 组件 | 详情 | |------|------| | 算法 | AES-256-GCM | | 密钥派生 | PBKDF2 with SHA-256 | | 迭代次数 | 600,000（OWASP 2023）| | Pepper | 32 字节随机值 | | Salt | 每次加密 64 字节随机值 |

命令审批策略

防御深度策略通过 5 层检查命令：

1. 白名单 - 安全命令（get、describe、logs）自动批准
2. Shell 字符 - 阻止 \|、`、$、;、&、<、>
3. 嵌套命令 - 阻止包含其他命令的命令
4. 危险关键词 - 阻止 delete、rm、exec 等
5. 敏感资源 - 阻止 secrets、configmaps、pvcs

临时文件安全

• O_EXCL 标志 - 原子文件创建防止竞态条件
• 权限 - 文件：0o400，目录：0o700
• 清理 - 覆写零后删除
• 过期清理 - 启动时清理超过 1 小时的残留文件

文件位置

| 文件 | 位置 | 权限 | |------|------|------| | 数据库 | ~/.k8s-secure/contexts.db | 0o600 | | Pepper | ~/.k8s-secure/.pepper | 0o400 | | 完整性密钥 | ~/.k8s-secure/.integrity-key | 0o400 | | 审计密钥 | ~/.k8s-secure/.audit-key | 0o400 | | 主密码 | 用户定义 | 0o400 |

安全检查清单

生产使用前：

• [ ] 主密码 16+ 字符，包含 3+ 字符类型
• [ ] 主密码存储在文件中（而非环境变量）
• [ ] Pepper 文件已安全备份
• [ ] ~/.k8s-secure/ 目录权限为 0o700
• [ ] Shell 配置文件不包含密码环境变量

开发

# 安装依赖
npm install

# 构建
npm run build

# 开发模式
npm run dev -- --help

# 运行测试
npm test

# 代码检查
npm run lint

相关项目

本项目参考了 db-manager-cli 的模式：

• 服务容器模式
• CLI 命令结构
• 错误处理方式
• 类型定义风格

许可证

MIT

贡献

欢迎贡献！请阅读 SECURITY.md 了解安全指南。