varlock

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Varlock Security Skill

Varlock 安全技能

Secure-by-default environment variable management for Claude Code sessions.

Repository: https://github.com/dmno-dev/varlock Documentation: https://varlock.dev

为Claude Code会话提供默认安全的环境变量管理方案。

代码仓库：https://github.com/dmno-dev/varlock 官方文档：https://varlock.dev

Core Principle: Secrets Never Exposed

核心原则：绝不暴露敏感信息

When working with Claude, secrets must NEVER appear in:

Terminal output
Claude's input/output context
Log files or traces
Git commits or diffs
Error messages

This skill ensures all sensitive data is properly protected.

在使用Claude时，敏感信息绝对不能出现在：

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

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

CRITICAL: Security Rules for Claude

重要提示：Claude使用安全规则

Rule 1: Never Echo Secrets

规则1：绝不回显敏感信息

bash

undefined

bash

undefined

❌ NEVER DO THIS - exposes secret to Claude's context

❌ 绝对禁止这样做 - 会将敏感信息暴露给Claude的上下文

echo $CLERK_SECRET_KEY cat .env | grep SECRET printenv | grep API

✅ DO THIS - validates without exposing

✅ 正确做法 - 仅验证不暴露

varlock load --quiet && echo "✓ Secrets validated"

undefined

varlock load --quiet && echo "✓ 敏感信息验证通过"

undefined

Rule 2: Never Read .env Directly

规则2：绝不直接读取.env文件

bash

undefined

bash

undefined

❌ NEVER DO THIS - exposes all secrets

❌ 绝对禁止这样做 - 会暴露所有敏感信息

cat .env less .env Read tool on .env file

cat .env less .env 使用工具读取.env文件

✅ DO THIS - read schema (safe) not values

✅ 正确做法 - 读取配置 schema（安全无敏感值）

cat .env.schema varlock load # Shows masked values

undefined

cat .env.schema varlock load # 仅显示脱敏后的值

undefined

Rule 3: Use Varlock for Validation

规则3：使用Varlock进行验证

bash

undefined

bash

undefined

❌ NEVER DO THIS - exposes secret in error

❌ 绝对禁止这样做 - 错误信息中会暴露敏感信息

test -n "$API_KEY" && echo "Key: $API_KEY"

test -n "$API_KEY" && echo "密钥: $API_KEY"

✅ DO THIS - Varlock validates and masks

✅ 正确做法 - Varlock会验证并脱敏显示

varlock load

Output shows: API_KEY 🔐sensitive └ ▒▒▒▒▒

输出示例：API_KEY 🔐sensitive └ ▒▒▒▒▒

undefined

undefined

Rule 4: Never Include Secrets in Commands

规则4：绝不在命令中直接包含敏感信息

bash

undefined

bash

undefined

❌ NEVER DO THIS - secret in command history

❌ 绝对禁止这样做 - 敏感信息会被记录到命令历史中

curl -H "Authorization: Bearer sk_live_xxx" https://api.example.com

✅ DO THIS - use environment variable

✅ 正确做法 - 使用环境变量

curl -H "Authorization: Bearer $API_KEY" https://api.example.com

Or better: varlock run -- curl ...

更优方案：varlock run -- curl ...

---

---

Quick Start

快速开始

Installation

安装

bash

undefined

bash

undefined

Install Varlock CLI

安装Varlock CLI

curl -sSfL https://varlock.dev/install.sh | sh -s -- --force-no-brew

Add to PATH (add to ~/.zshrc or ~/.bashrc)

添加到PATH环境变量（建议添加到~/.zshrc或~/.bashrc）

export PATH="$HOME/.varlock/bin:$PATH"

Verify

验证安装

varlock --version

undefined

varlock --version

undefined

Initialize Project

初始化项目

bash

undefined

bash

undefined

Create .env.schema from existing .env

从已有的.env文件生成.env.schema

varlock init

Or create manually

或手动创建

touch .env.schema

---

touch .env.schema

---

Schema File: .env.schema

配置Schema文件：.env.schema

The schema defines types, validation, and sensitivity for each variable.

该schema文件定义了每个环境变量的类型、验证规则和敏感属性。

Basic Structure

基础结构

bash

undefined

bash

undefined

Global defaults

全局默认配置

@defaultSensitive=true @defaultRequired=infer

Application

应用配置

@type=enum(development,staging,production) @sensitive=false

NODE_ENV=development

@type=port @sensitive=false

PORT=3000

Database - SENSITIVE

数据库配置 - 敏感信息

@type=url @required

DATABASE_URL=

@type=string @required @sensitive

DATABASE_PASSWORD=

API Keys - SENSITIVE

API密钥 - 敏感信息

@type=string(startsWith=sk_) @required @sensitive

STRIPE_SECRET_KEY=

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

STRIPE_PUBLISHABLE_KEY=

undefined

STRIPE_PUBLISHABLE_KEY=

undefined

Security Annotations

安全注解

Annotation	Effect	Use For
`@sensitive`	Redacted in all output	API keys, passwords, tokens
`@sensitive=false`	Shown in logs	Public keys, non-secret config
`@defaultSensitive=true`	All vars sensitive by default	High-security projects

注解	作用	适用场景
`@sensitive`	在所有输出中自动脱敏	API密钥、密码、令牌等
`@sensitive=false`	可在日志中显示	公钥、非敏感配置项
`@defaultSensitive=true`	默认所有变量都为敏感类型	高安全要求项目

Type Annotations

类型注解

Type	Validates	Example
`string`	Any string	`@type=string`
`string(startsWith=X)`	Prefix validation	`@type=string(startsWith=sk_)`
`string(contains=X)`	Substring validation	`@type=string(contains=+clerk_test)`
`url`	Valid URL	`@type=url`
`port`	1-65535	`@type=port`
`boolean`	true/false	`@type=boolean`
`enum(a,b,c)`	One of values	`@type=enum(dev,prod)`

类型	验证规则	示例
`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)`

Safe Commands for Claude

Claude安全命令指南

Validating Environment

验证环境配置

bash

undefined

bash

undefined

Check all variables (safe - masks sensitive values)

检查所有变量（安全，敏感值会脱敏）

varlock load

Quiet mode (no output on success)

静默模式（验证成功无输出）

varlock load --quiet

Check specific environment

验证指定环境的配置

varlock load --env=production

undefined

varlock load --env=production

undefined

Running Commands with Secrets

携带敏感信息执行命令

bash

undefined

bash

undefined

Inject validated env into command

将验证通过的环境变量注入到命令中

varlock run -- npm start varlock run -- node script.js varlock run -- pytest

Secrets are available to the command but never printed

敏感信息仅对命令可见，绝不会被打印输出

undefined

undefined

Checking Schema (Safe)

查看配置Schema（安全）

bash

undefined

bash

undefined

Schema is safe to read - contains no values

Schema文件安全无敏感值，可放心查看

cat .env.schema

List expected variables

列出所有需要的变量

grep "^[A-Z]" .env.schema

---

grep "^[A-Z]" .env.schema

---

Common Patterns

常见使用模式

Pattern 1: Validate Before Operations

模式1：操作前先验证

bash

undefined

bash

undefined

Always validate environment first

始终先验证环境配置

varlock load --quiet || { echo "❌ Environment validation failed" exit 1 }

varlock load --quiet || { echo "❌ 环境配置验证失败" exit 1 }

Then proceed with operation

验证通过后再执行操作

npm run build

undefined

npm run build

undefined

Pattern 2: Safe Secret Rotation

模式2：安全的敏感信息轮换

bash

undefined

bash

undefined

1. Update secret in external source (1Password, AWS, etc.)

1. 在外部源更新敏感信息（如1Password、AWS等）

2. Update .env file manually (don't use Claude for this)

2. 手动更新.env文件（请勿通过Claude操作）

3. Validate new value works

3. 验证新值是否可用

varlock load

4. If using GitHub Secrets, sync (values not shown)

4. 若使用GitHub Secrets，同步配置（不会显示具体值）

./scripts/update-github-secrets.sh

undefined

./scripts/update-github-secrets.sh

undefined

Pattern 3: CI/CD Integration

模式3：CI/CD集成

yaml

undefined

yaml

undefined

GitHub Actions - secrets from GitHub Secrets

GitHub Actions - 从GitHub Secrets获取敏感信息

name: Validate environment env: DATABASE_URL: ${{ secrets.DATABASE_URL }} API_KEY: ${{ secrets.API_KEY }} run: varlock load --quiet

undefined

name: Validate environment env: DATABASE_URL: ${{ secrets.DATABASE_URL }} API_KEY: ${{ secrets.API_KEY }} run: varlock load --quiet

undefined

Pattern 4: Docker Integration

模式4：Docker集成

dockerfile

undefined

dockerfile

undefined

Install Varlock in container

在容器中安装Varlock

RUN curl -sSfL https://varlock.dev/install.sh | sh -s -- --force-no-brew
&& ln -s /root/.varlock/bin/varlock /usr/local/bin/varlock

Validate at container start

容器启动时验证配置

CMD ["varlock", "run", "--", "npm", "start"]

---

CMD ["varlock", "run", "--", "npm", "start"]

---

Handling Secret-Related Tasks

敏感信息相关任务处理

When User Asks to "Check if API key is set"

当用户询问“检查API密钥是否已设置”时

bash

undefined

bash

undefined

✅ Safe approach

✅ 安全方案

varlock load 2>&1 | grep "API_KEY"

Shows: ✅ API_KEY 🔐sensitive └ ▒▒▒▒▒

输出示例：✅ API_KEY 🔐sensitive └ ▒▒▒▒▒

❌ Never do

❌ 绝对禁止

echo $API_KEY

undefined

echo $API_KEY

undefined

When User Asks to "Debug authentication"

当用户询问“调试认证问题”时

bash

undefined

bash

undefined

✅ Safe approach - check presence and format

✅ 安全方案 - 检查是否存在及格式是否正确

varlock load # Validates types and required fields

varlock load # 验证类型和必填字段

Check if key has correct prefix (without showing value)

检查密钥前缀是否正确（不会显示具体值）

varlock load 2>&1 | grep -E "(CLERK|AUTH)"

❌ Never do

❌ 绝对禁止

printenv | grep KEY

undefined

printenv | grep KEY

undefined

When User Asks to "Update a secret"

当用户询问“更新敏感信息”时

Claude should respond:
"I cannot directly modify secrets for security reasons. Please:
1. Update the value in your .env file manually
2. Or update in your secrets manager (1Password, AWS, etc.)
3. Then run `varlock load` to validate

I can help you update the .env.schema if you need to add new variables."

Claude应回复：
"出于安全考虑，我无法直接修改敏感信息。请按照以下步骤操作：
1. 手动更新.env文件中的值
2. 或在你的敏感信息管理器中更新（如1Password、AWS等）
3. 然后执行`varlock load`验证配置

如果你需要添加新变量，我可以帮助你修改.env.schema文件。"

When User Asks to "Show me the .env file"

当用户询问“展示.env文件内容”时

Claude should respond:
"I won't read .env files directly as they contain secrets. Instead:
- Run `varlock load` to see masked values
- Run `cat .env.schema` to see the schema (safe)
- I can help you modify .env.schema if needed"

Claude应回复：
"我不会直接读取.env文件，因为其中包含敏感信息。你可以：
- 执行`varlock load`查看脱敏后的值
- 执行`cat .env.schema`查看配置Schema（安全无敏感值）
- 如果需要修改配置Schema，我可以提供帮助"

External Secret Sources

外部敏感信息源集成

1Password Integration

1Password 集成

bash

undefined

bash

undefined

In .env.schema

在.env.schema中配置

@type=string @sensitive

API_KEY=exec('op read "op://vault/item/field"')

undefined

API_KEY=exec('op read "op://vault/item/field"')

undefined

AWS Secrets Manager

AWS Secrets Manager 集成

bash

undefined

bash

undefined

In .env.schema

在.env.schema中配置

@type=string @sensitive

DB_PASSWORD=exec('aws secretsmanager get-secret-value --secret-id prod/db')

undefined

DB_PASSWORD=exec('aws secretsmanager get-secret-value --secret-id prod/db')

undefined

Environment-Specific Values

环境特定值配置

bash

undefined

bash

undefined

In .env.schema

在.env.schema中配置

@type=url

API_URL=env('API_URL_${NODE_ENV}', 'http://localhost:3000')

---

API_URL=env('API_URL_${NODE_ENV}', 'http://localhost:3000')

---

Troubleshooting

故障排查

"varlock: command not found"

“varlock: command not found”

bash

undefined

bash

undefined

Check installation

检查安装情况

ls ~/.varlock/bin/varlock

Add to PATH

添加到PATH

export PATH="$HOME/.varlock/bin:$PATH"

Or use full path

或使用完整路径执行

~/.varlock/bin/varlock load

undefined

~/.varlock/bin/varlock load

undefined

"Schema validation failed"

“Schema validation failed”

bash

undefined

bash

undefined

Check which variables are missing/invalid

检查哪些变量缺失或无效

varlock load # Shows detailed errors

varlock load # 会显示详细错误信息

Common fixes:

常见修复方案：

- Add missing required variables to .env

- 向.env文件添加缺失的必填变量

- Fix type mismatches (port must be number)

- 修复类型不匹配问题（如端口号必须是数字）

- Check string prefixes match schema

- 检查字符串前缀是否与schema定义一致

undefined

undefined

"Sensitive value exposed in logs"

“Sensitive value exposed in logs”

bash

undefined

bash

undefined

1. Rotate the exposed secret immediately

1. 立即轮换已暴露的敏感信息

2. Check .env.schema has @sensitive annotation

2. 检查.env.schema中是否添加了@sensitive注解

3. Ensure using varlock commands, not echo/cat

3. 确保使用Varlock命令，而非echo/cat等

Add missing sensitivity:

添加缺失的敏感注解：

Before: API_KEY=

修改前：API_KEY=

After: # @type=string @sensitive

修改后： # @type=string @sensitive

API_KEY=

---

---

npm Scripts

npm 脚本配置

Add these to your package.json:

json

{
  "scripts": {
    "env:validate": "varlock load",
    "env:check": "varlock load --quiet || echo 'Environment validation failed'",
    "prestart": "varlock load --quiet",
    "start": "varlock run -- node server.js"
  }
}

将以下配置添加到你的package.json：

json

{
  "scripts": {
    "env:validate": "varlock load",
    "env:check": "varlock load --quiet || echo '环境配置验证失败'",
    "prestart": "varlock load --quiet",
    "start": "varlock run -- node server.js"
  }
}

Security Checklist for New Projects

新项目安全检查清单

Install Varlock CLI
Create
```
.env.schema
```
with all variables defined
Mark all secrets with
```
@sensitive
```
annotation
Add
```
@defaultSensitive=true
```
to schema header
Add
```
.env
```
to
```
.gitignore
```
Commit
```
.env.schema
```
to version control
Add
```
npm run env:validate
```
to CI/CD
Document secret rotation procedure
Never use
```
cat .env
```
or
```
echo $SECRET
```
in Claude sessions

安装Varlock CLI
创建包含所有变量定义的
```
.env.schema
```
文件
为所有敏感信息添加
```
@sensitive
```
注解
在schema头部添加
```
@defaultSensitive=true
```
将
```
.env
```
添加到
```
.gitignore
```
将
```
.env.schema
```
提交到版本控制系统
在CI/CD流程中添加
```
npm run env:validate
```
步骤
记录敏感信息轮换流程
在Claude会话中绝不使用
```
cat .env
```
或
```
echo $SECRET
```
命令

Quick Reference Card

快速参考卡片

Task	Safe Command
Validate all env vars	`varlock load`
Quiet validation	`varlock load --quiet`
Run with env	`varlock run -- <cmd>`
View schema	`cat .env.schema`
Check specific var	`varlock load \| grep VAR_NAME`

Never Do	Why
`cat .env`	Exposes all secrets
`echo $SECRET`	Exposes to Claude context
`printenv \| grep`	Exposes matching secrets
Read .env with tools	Secrets in Claude's context
Hardcode in commands	In shell history

任务	安全命令
验证所有环境变量	`varlock load`
静默验证	`varlock load --quiet`
携带环境变量执行命令	`varlock run -- <cmd>`
查看配置Schema	`cat .env.schema`
检查特定变量	`varlock load \| grep VAR_NAME`

绝对禁止操作	原因
`cat .env`	暴露所有敏感信息
`echo $SECRET`	暴露给Claude上下文
`printenv \| grep`	暴露匹配到的敏感信息
使用工具读取.env文件	敏感信息会进入Claude上下文
在命令中硬编码敏感信息	会被记录到命令历史

Integration with Other Skills

与其他技能集成

Clerk Skill

Test user passwords are
```
@sensitive
```
Test emails are
```
@sensitive=false
```
(contain +clerk_test, not secret)
See:
```
~/.claude/skills/clerk/SKILL.md
```

确保用户密码标记为
```
@sensitive
```
确保邮箱标记为
```
@sensitive=false
```
（包含+clerk_test，非敏感信息）
参考：
```
~/.claude/skills/clerk/SKILL.md
```

Docker Skill

Mount
```
.env
```
file, never copy secrets to image
Use
```
varlock run
```
as entrypoint
See:
```
~/.claude/skills/docker/SKILL.md
```

Last updated: December 22, 2025 Secure-by-default environment management for Claude Code

挂载
```
.env
```
文件，绝不将敏感信息复制到镜像中
使用
```
varlock run
```
作为启动入口
参考：
```
~/.claude/skills/docker/SKILL.md
```

最后更新日期：2025年12月22日 为Claude Code提供默认安全的环境变量管理方案