---

name: varlock description: "Claude Code 会话中默认安全的环境变量管理。" risk: critical source: "https://github.com/dmno-dev/varlock" version: 1.0.0

Varlock 安全技能

Claude Code 会话中默认安全的环境变量管理。

仓库: https://github.com/dmno-dev/varlock 文档: https://varlock.dev

何时使用

• 你需要在 Claude Code 会话中使用环境变量或密钥而不暴露其值。
• 任务涉及验证、加载或审计密钥，同时将其排除在日志、差异和助手上下文之外。
• 你想要围绕 Varlock 构建默认安全的工作流，而非直接检查 .env 文件。

核心原则：密钥永不暴露

使用 Claude 时，密钥绝不能出现在：

• 终端输出
• Claude 的输入/输出上下文
• 日志文件或追踪
• Git 提交或差异
• 错误消息

本技能确保所有敏感数据得到妥善保护。

---

关键：Claude 安全规则

规则 1：永不回显密钥

# 绝对不要这样做 - 会将密钥暴露给 Claude 的上下文
echo $CLERK_SECRET_KEY
cat .env | grep SECRET
printenv | grep API

# 正确做法 - 验证但不暴露
varlock load --quiet && echo "Secrets validated"

规则 2：永不直接读取 .env

# 绝对不要这样做 - 暴露所有密钥
cat .env
less .env
Read tool on .env file

# 正确做法 - 读取 schema（安全）而非值
cat .env.schema
varlock load  # 显示掩码值

规则 3：使用 Varlock 进行验证

# 绝对不要这样做 - 在错误中暴露密钥
test -n "$API_KEY" && echo "Key: $API_KEY"

# 正确做法 - Varlock 验证并掩码
varlock load
# 输出显示: API_KEY sensitive ...

规则 4：永不在命令中包含密钥

# 绝对不要这样做 - 密钥出现在命令历史中
curl -H "Authorization: Bearer sk_live_xxx" https://api.example.com

# 正确做法 - 使用环境变量
curl -H "Authorization: Bearer $API_KEY" https://api.example.com
# 或更好: varlock run -- curl ...

---

快速开始

安装

# 安装 Varlock CLI
curl -sSfL https://varlock.dev/install.sh -o /tmp/varlock-install.sh
sed -n '1,160p' /tmp/varlock-install.sh
sh /tmp/varlock-install.sh --force-no-brew

# 添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）
export PATH="$HOME/.varlock/bin:$PATH"

# 验证
varlock --version

初始化项目

# 从现有 .env 创建 .env.schema
varlock init

# 或手动创建
touch .env.schema

---

Schema 文件：.env.schema

Schema 定义每个变量的类型、验证和敏感性。

基本结构

# 全局默认值
# @defaultSensitive=true @defaultRequired=infer

# 应用配置
# @type=enum(development,staging,production) @sensitive=false
NODE_ENV=development

# @type=port @sensitive=false
PORT=3000

# 数据库 - 敏感
# @type=url @required
DATABASE_URL=

# @type=string @required @sensitive
DATABASE_PASSWORD=

# API 密钥 - 敏感
# @type=string(startsWith=sk_) @required @sensitive
STRIPE_SECRET_KEY=

# @type=string(startsWith=pk_) @sensitive=false
STRIPE_PUBLISHABLE_KEY=

安全注解

| 注解 | 效果 | 用途 | |------------|--------|---------| | @sensitive | 在所有输出中脱敏 | API 密钥、密码、令牌 | | @sensitive=false | 在日志中显示 | 公钥、非密钥配置 | | @defaultSensitive=true | 所有变量默认敏感 | 高安全性项目 |

类型注解

| 类型 | 验证内容 | 示例 | |------|-----------|---------| | string | 任意字符串 | @type=string | | string(startsWith=X) | 前缀验证 | @type=string(startsWith=sk_) | | string(contains=X) | 子串验证 | @type=string(contains=+clerk_test) | | url | 有效 URL | @type=url | | port | 1-65535 | @type=port | | boolean | true/false | @type=boolean | | enum(a,b,c) | 枚举值之一 | @type=enum(dev,prod) |

---

Claude 安全命令

验证环境

# 检查所有变量（安全 - 掩码敏感值）
varlock load

# 静默模式（成功时无输出）
varlock load --quiet

# 检查特定环境
varlock load --env=production

使用密钥运行命令

# 将验证后的环境变量注入命令
varlock run -- npm start
varlock run -- node script.js
varlock run -- pytest

# 密钥对命令可用但永不打印

检查 Schema（安全）

# Schema 可以安全读取 - 不包含值
cat .env.schema

# 列出预期变量
grep "^[A-Z]" .env.schema

---

常见模式

模式 1：操作前验证

# 始终先验证环境
varlock load --quiet || {
  echo "Environment validation failed"
  exit 1
}

# 然后继续操作
npm run build

模式 2：安全密钥轮换

# 1. 在外部源（1Password、AWS 等）中更新密钥
# 2. 更新 .env 文件
# 3. 验证新值
varlock load