varlock

Varlock セキュリティスキル

Claude Code セッション向けの、デフォルトで安全な環境変数管理です。

リポジトリ：https://github.com/dmno-dev/varlock ドキュメント：https://varlock.dev

基本原則：シークレットを決して露出させない

Claude を使用する際、シークレットは次の場所に決して表示してはいけません。

• ターミナル出力
• Claude の入出力コンテキスト
• ログファイルやトレース
• Git のコミットや差分
• エラーメッセージ

このスキルにより、すべての機密データが適切に保護されます。

---

重要：Claude のセキュリティルール

ルール 1：シークレットを決してエコーしない

# ❌ NEVER DO THIS - exposes secret to Claude's context
echo $CLERK_SECRET_KEY
cat .env | grep SECRET
printenv | grep API

# ✅ DO THIS - validates without exposing
varlock load --quiet && echo "✓ Secrets validated"

ルール 2：.env を直接読み込まない

# ❌ NEVER DO THIS - exposes all secrets
cat .env
less .env
Read tool on .env file

# ✅ DO THIS - read schema (safe) not values
cat .env.schema
varlock load  # Shows masked values

ルール 3：検証には Varlock を使用する

# ❌ NEVER DO THIS - exposes secret in error
test -n "$API_KEY" && echo "Key: $API_KEY"

# ✅ DO THIS - Varlock validates and masks
varlock load
# Output shows: API_KEY 🔐sensitive └ ▒▒▒▒▒

ルール 4：コマンドにシークレットを決して含めない

# ❌ 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 ...

---

クイックスタート

インストール

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

# Add to PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$HOME/.varlock/bin:$PATH"

# Verify
varlock --version

プロジェクトを初期化する

# Create .env.schema from existing .env
varlock init

# Or create manually
touch .env.schema

---

スキーマファイル：.env.schema

スキーマでは、各変数の型、検証方法、機密性を定義します。

基本構造

# 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
# @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 で使用できる安全なコマンド

環境の検証

# 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

シークレットを使ってコマンドを実行する

# 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

スキーマを確認する（安全）

# Schema is safe to read - contains no values
cat .env.schema

# List expected variables
grep "^[A-Z]" .env.schema

---

よくあるパターン

パターン 1：操作の前に検証する

# Always validate environment first
varlock load --quiet || {
  echo "❌ Environment validation failed"
  exit 1
}

# Then proceed with operation
npm run build

パターン 2：シークレットを安全にローテーションする

# 1. Update secret in external source (1Password, AWS, etc.)
# 2. Update .env file manually (don't use Claude for this)
# 3. Validate new value works
varlock load

# 4. If using GitHub Secrets, sync (values not shown)
./scripts/update-github-secrets.sh

パターン 3：CI/CD との連携

# GitHub Actions - secrets from GitHub Secrets
- name: Validate environment
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
    API_KEY: ${{ secrets.API_KEY }}
  run: varlock load --quiet

パターン 4：Docker との連携

# Install Varlock in container
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"]

---

シークレット関連のタスクへの対応

ユーザーから「API キーが設定されているか確認して」と依頼された場合

# ✅ Safe approach
varlock load 2>&1 | grep "API_KEY"
# Shows: ✅ API_KEY 🔐sensitive └ ▒▒▒▒▒

# ❌ Never do
echo $API_KEY

ユーザーから「認証をデバッグして」と依頼された場合

# ✅ Safe approach - check presence and format
varlock load  # Validates types and required fields

# Check if key has correct prefix (without showing value)
varlock load 2>&1 | grep -E "(CLERK|AUTH)"

# ❌ Never do
printenv | grep KEY

ユーザーから「シークレットを更新して」と依頼された場合

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."

ユーザーから「.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"

---

外部シークレットソース

1Password との連携

# In .env.schema
# @type=string @sensitive
API_KEY=exec('op read "op://vault/item/field"')

AWS Secrets Manager

# In .env.schema
# @type=string @sensitive
DB_PASSWORD=exec('aws secretsmanager get-secret-value --secret-id prod/db')

環境ごとの値

# In .env.schema
# @type=url
API_URL=env('API_URL_${NODE_ENV}', 'http://localhost:3000')

---

トラブルシューティング

「varlock: command not found」

# Check installation
ls ~/.varlock/bin/varlock

# Add to PATH
export PATH="$HOME/.varlock/bin:$PATH"

# Or use full path
~/.varlock/bin/varlock load

「Schema validation failed」

# Check which variables are missing/invalid
varlock load  # Shows detailed errors

# Common fixes:
# - Add missing required variables to .env
# - Fix type mismatches (port must be number)
# - Check string prefixes match schema

「Sensitive value exposed in logs」

# 1. Rotate the exposed secret immediately
# 2. Check .env.schema has @sensitive annotation
# 3. Ensure using varlock commands, not echo/cat

# Add missing sensitivity:
# Before: API_KEY=
# After:  # @type=string @sensitive
#         API_KEY=

---

npm スクリプト

これらを package.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"
  }
}

---

新規プロジェクト向けセキュリティチェックリスト

• Varlock CLI をインストールする
• すべての変数を定義した .env.schema を作成する
• すべてのシークレットに @sensitive 注釈を付ける
• スキーマヘッダーに @defaultSensitive=true を追加する
• .env を .gitignore に追加する
• .env.schema をバージョン管理にコミットする
• CI/CD に npm run env:validate を追加する
• シークレットのローテーション手順を文書化する
• Claude セッションで cat .env や echo $SECRET を決して使用しない

---

クイックリファレンスカード

タスク	安全なコマンド
すべての環境変数を検証する	varlock load
検証結果を表示しない	varlock load --quiet
環境変数を使って実行する	varlock run -- <cmd>
スキーマを表示する	cat .env.schema
特定の変数を確認する	varlock load | grep VAR_NAME

絶対にしないこと	理由
cat .env	すべてのシークレットが露出する
echo $SECRET	Claude のコンテキストに露出する
printenv | grep	一致したシークレットが露出する
ツールで .env を読む	シークレットが Claude のコンテキストに含まれる
コマンドにハードコードする	シェルの履歴に残る

---

他のスキルとの連携

Clerk スキル

• テストユーザーのパスワードには @sensitive を付けます
• テスト用メールアドレスには @sensitive=false を付けます（+clerk_test を含み、シークレットではありません）
• 参照先：~/.claude/skills/clerk/SKILL.md

Docker スキル

• .env ファイルをマウントし、シークレットをイメージにコピーしないでください
• エントリーポイントとして varlock run を使用してください
• 参照：~/.claude/skills/docker/SKILL.md

---

最終更新日：2025年12月22日 Claude Code 向けのセキュアな環境管理をデフォルトで提供