keeper-secrets

Keeper Secrets Manager CLI（ksm）

KSM CLI 是 Keeper 面向机器的机密管理工具。它无需完整的用户登录即可从 Keeper Vault 中检索机密，而是使用 Application + Client Device 身份验证和一次性访问令牌。

官方文档

• Secrets Manager（KSM） - 概览、安装和配置
• Keeper notation - 用于字段、自定义字段和文件的 keeper:// URI 语法

何时使用 KSM 与 Commander

需求	工具
检索机密（密码、密钥、证书）	ksm
在运行时将机密注入环境变量	ksm exec
将机密模板化到配置文件中	ksm interpolate
列出／搜索与应用共享的记录	ksm secret list
创建或更新机密记录	ksm secret add / ksm secret update
将机密同步到 AWS/Azure 机密存储	ksm sync
生成安全密码	ksm secret password
管理任务（用户、团队、角色、SSO）	使用 keeper（Commander）——参见 keeper-admin skill
创建 KSM Applications 或 Client Devices	使用 keeper（Commander）——参见 keeper-admin skill
管理 PAM 资源或轮换	使用 keeper（Commander）——参见 keeper-admin skill

先决条件

1. 已安装 KSM CLI：pip install keeper-secrets-manager-cli（或使用 GitHub releases 中的二进制文件）
2. 已在 Keeper Vault 中创建 KSM Application（或通过 Commander 创建）
3. 已使用一次性访问令牌初始化 Client Device

检查安装情况：ksm version

工作流

1. 所有 KSM 相关操作都必须使用专用 TMUX 会话。
2. 首次配置 KSM 时，预先配置 KSM init 命令，要求用户输入一次性令牌，并将其注入预先配置的 tmux 会话。
3. 必须询问用户填写必填字段，不要猜测必填字段。
4. 先搜索或检查元数据，然后仅检索确切请求的字段；不要暴露任何敏感数据。
5. 优先使用机密注入或单命令环境作用域，避免将机密写入磁盘。
6. 如果语法与预期不符，立即使用 --help 并查阅 Keeper 文档。
7. 任何删除操作都必须先征求用户确认。

必需的 tmux 会话

shell 工具每次命令都会使用新的 TTY。为保留 Keeper 交互上下文、身份验证状态和 MFA 提示，请在专用 tmux 会话中运行 Keeper 交互式命令或 secrets manager 命令。

示例模式：

SOCKET_DIR="${TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/keeper-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/keeper-commander.sock"
SESSION="keeper-auth-$(date +%Y%m%d-%H%M%S)"

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "ksm shell || bash" Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -120

然后谨慎地操作该会话：

tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -l -- "whoami"
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -120

任务完成后，除非用户需要持久化的 Keeper shell，否则请结束 tmux 会话。

身份验证与配置文件设置

KSM 使用基于配置文件的身份验证。默认情况下，安装时如果启用了 keyring 支持，凭据会存储在操作系统原生的安全存储中（macOS Keychain、Windows Credential Manager、Linux Secret Service）。

# Install with keyring support (recommended)
pip install keeper-secrets-manager-cli[keyring]

# Initialize with One-Time Access Token (set KSM_CLI_TOKEN in your shell first—see Keeper profile docs; do not pass --token with a literal value)
ksm profile init

# For containers/CI (no keyring available)
pip install keeper-secrets-manager-cli
# Prerequisite: export KSM_CLI_TOKEN from a trusted source, then:
ksm profile init
# Creates keeper.ini with 0600 permissions

# Auto-create profile from environment variable (containers; see Keeper docs)
ksm secret list  # When KSM_TOKEN is set, profile may be auto-created on first use

多个配置文件

ksm profile list
# After exporting KSM_CLI_TOKEN for each setup step:
ksm profile init --profile production
ksm profile init --profile staging
ksm secret list --profile production

环境变量

变量	用途
KSM_CLI_TOKEN	用于在 CLI 上不带 --token 执行 ksm profile init 的一次性访问令牌（首选）
KSM_TOKEN	用于某些容器流程中自动初始化的一次性访问令牌（参见 Keeper 文档）
KSM_CONFIG	Base64 配置字符串（用于 K8s/容器）
KSM_CONFIG_FILE	keeper.ini 的路径
KSM_CLI_PROFILE	活动配置文件名称
KSM_HOSTNAME	Keeper 主机（US、EU、AU、JP、CA、US_GOV）

核心命令

列出机密

ksm secret list
# Output:
# UID                     Record Type          Title
# ----------------------- -------------------- -------------------------
# SNzjw8tM1HsXEzXERCJrNQ login                Stripe API Key
# 8f8I-OqPV58o2r91wVgZ_A databaseCredentials  Production MySQL Database

获取机密

# Get full record as JSON
ksm secret get -u <RECORD_UID> --json

# Get a specific field value
ksm secret get -u <RECORD_UID> -f password
ksm secret get -u <RECORD_UID> -f login

# Get with JSONPath query
ksm secret get -u <RECORD_UID> --json -q '$.fields[[email protected]=="password"].value[0]'

# Get by title
ksm secret get -t "Production MySQL Database" -f password

# Remove surrounding quotes from output (useful for scripting)
ksm secret get -u <RECORD_UID> -f password --raw

Keeper Notation

Keeper Notation 是用于引用记录中特定字段的 URI 格式。 完整语法和行为请参见 Keeper notation 文档。

格式：keeper://<RECORD_UID>/field/<FIELD_TYPE> 或 keeper://<RECORD_UID>/custom_field/<LABEL>

keeper://SNzjw8tM1HsXEzXERCJrNQ/field/login
keeper://SNzjw8tM1HsXEzXERCJrNQ/field/password
keeper://8f8I-OqPV58o2r91wVgZ_A/field/host
keeper://8f8I-OqPV58o2r91wVgZ_A/custom_field/ConnectionString

完整的 notation 语法请阅读 references/keeper-notation.md。

将机密注入环境变量（ksm exec）

这是使用机密运行应用的主要模式。任何以 keeper:// 开头的环境 变量都会在命令执行前替换为机密值。

# Single secret
export DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password"
ksm exec -- myapp

# Inline
DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password" \
API_KEY="keeper://SNzjw8tM1HsXEzXERCJrNQ/field/password" \
ksm exec -- ./start_server.sh

# Docker example
docker run \
  -e DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password" \
  -e KSM_CONFIG="<base64-config>" \
  myimage ksm exec -- /app/start.sh

将机密插入配置文件

# Replace keeper:// placeholders in a template file
ksm interpolate --in-file config.tmpl --out-file config.yaml

# Example template (config.tmpl):
# database:
#   host: keeper://8f8I-OqPV58o2r91wVgZ_A/field/host
#   password: keeper://8f8I-OqPV58o2r91wVgZ_A/field/password

创建和更新机密

# Create from editor
ksm secret add editor --record-type login --title "New API Key"

# Create from field arguments (supply sensitive field values from secure input, not sample literals)
ksm secret add field --record-type login --title "New API Key" \
  --field "login=admin"

# Update a field (use secure input for password fields)
ksm secret update -u <RECORD_UID> --field "login=newuser"

# Delete a record
ksm secret delete -u <RECORD_UID>

生成密码

ksm secret password --length 32
ksm secret password --lc 8 --uc 8 -d 8 --sc 8

同步到云存储

# Sync to AWS Secrets Manager
ksm sync --type aws_sm --credentials <AWS_CREDS_RECORD_UID> \
  --map <KEEPER_UID>=<AWS_SECRET_NAME>

# Sync to Azure Key Vault
ksm sync --type azure_kv --credentials <AZURE_CREDS_RECORD_UID> \
  --map <KEEPER_UID>=<AZURE_SECRET_NAME>

文件夹管理

ksm folder list
ksm folder get -u <FOLDER_UID>

防护措施

• 绝不要将机密值粘贴、打印或记录到聊天、代码注释或提交消息中。
• 始终优先使用 ksm exec 或 ksm interpolate，而不是将机密写入磁盘或嵌入源代码。
• 如果命令因身份验证错误而失败，请使用新的 One-Time Access Token 重新初始化配置文件。
• 以 - 开头的记录 UID 必须加上 -- 前缀： ksm secret get -- -AbCdEfGh
• 对于引用敏感记录的命令，在执行删除、更新等破坏性操作前，请先向用户确认。

常见模式

CI/CD 流水线（GitHub Actions）

env:
  KSM_CONFIG: ${{ secrets.KSM_CONFIG }}
steps:
  - run: pip install keeper-secrets-manager-cli
  - run: |
      DB_PASSWORD="keeper://<UID>/field/password" \
      ksm exec -- ./deploy.sh

Docker / Kubernetes

# Pass base64 config as env var
kubectl create secret generic ksm-config \
  --from-literal=config=<BASE64_CONFIG>

# In pod spec, mount KSM_CONFIG and use ksm exec as entrypoint

本地开发

# One-time setup
pip install keeper-secrets-manager-cli[keyring]
# Prerequisite: export KSM_CLI_TOKEN, then:
ksm profile init

# Daily use - run your app with secrets injected
DB_URL="keeper://<UID>/field/url" \
API_KEY="keeper://<UID>/field/password" \
ksm exec -- npm run dev