Claude Code 安全最佳實踐：建立安全的 AI 輔助開發工作流程

AI 輔助開發中的安全不是可選項——而是基礎。當 Claude Code 成為你開發工作流程的核心部分時，了解安全最佳實踐對於保護你的程式碼、資料和使用者至關重要。

本指南提供每位 Claude Code 開發者都應該實施的可執行安全實踐。

安全思維

為什麼 AI 開發需要額外關注

AI 輔助開發帶來獨特的考量：

更廣泛的存取權限：AI 工具通常需要更廣泛的檔案系統存取權限才能提供幫助
Token 暴露：API 金鑰和憑證可能意外出現在上下文中
權限邊界：理解 AI 可以和不可以存取什麼
稽核軌跡：追蹤做了什麼變更以及為什麼

核心原則：以對待生產系統的嚴謹態度來對待 AI 輔助開發。

1. 權限管理

最小權限原則

使用最小必要權限配置 Claude Code：

{
  "permissions": {
    "allow": [
      "Read(src/**)",
      "Write(src/**)",
      "Edit(src/**)",
      "Bash(npm run:*)",
      "Bash(npm test:*)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(**/secrets/**)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Read(**/*credential*)",
      "Write(.env*)",
      "Edit(.env*)",
      "Bash(rm -rf:*)",
      "Bash(*--force*)",
      "Bash(*DROP*)",
      "Bash(*DELETE FROM*)"
    ]
  }
}

權限層級

Claude Code 使用四層配置階層：

層級	位置	用途
企業	`/etc/claude-code/`	全組織政策
使用者	`~/.claude/`	個人偏好
專案	`.claude/settings.json`	專案特定規則
會話	執行時期	暫時覆寫

最佳實踐：在適當的最高層級定義安全規則。企業層級用於合規要求，專案層級用於特定需求。

定期權限稽核

# 檢視目前權限
cat .claude/settings.json | jq '.permissions'

# 檢查過於寬鬆的模式
grep -r "allow.*\*\*" .claude/

2. 環境變數保護

絕不暴露機密

你的 CLAUDE.md 應該明確說明：

## 機密處理

### 絕對禁止
- 在程式碼中寫死 API 金鑰、token 或密碼
- 在 commit 訊息中包含機密
- 將機密記錄到 console 或檔案
- 在錯誤訊息中包含機密

### 永遠
- 使用環境變數處理機密
- 透過安全的配置管理參照機密
- 定期輪換憑證
- 每個環境使用不同的憑證

環境檔案安全

# .env 檔案的正確權限
chmod 600 .env
chmod 600 .env.local
chmod 600 .env.production

# 驗證權限
ls -la .env*
# 應該顯示：-rw------- (僅擁有者讀寫)

範例：安全配置

// ❌ 絕對不要這樣做
const API_KEY = "sk-ant-abc123...";

// ✅ 永遠這樣做
const API_KEY = process.env.ANTHROPIC_API_KEY;
if (!API_KEY) {
  throw new Error("需要 ANTHROPIC_API_KEY 環境變數");
}

3. 檔案系統隔離

專案邊界

確保 Claude Code 保持在專案邊界內：

{
  "permissions": {
    "deny": [
      "Read(/etc/**)",
      "Read(/var/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(~/.config/**)",
      "Write(/**)"
    ]
  }
}

Gitignore 最佳實踐

# 機密 - 絕不 commit
.env
.env.local
.env.*.local
*.pem
*.key
secrets/
credentials/

# Claude Code 產出物 - 通常不 commit
.claude/memory.json
CLAUDE.local.md
.auto-cycle/

# 建置輸出
dist/
build/
node_modules/

符號連結意識

注意符號連結可能繞過目錄限制：

# 檢查專案中的符號連結
find . -type l -ls

# 確保沒有符號連結指向專案外部
find . -type l -exec realpath {} \; | grep -v "$(pwd)"

4. 安全開發工作流程

Pre-Commit 安全檢查

#!/bin/bash
# .git/hooks/pre-commit

# 檢查潛在的機密
if git diff --cached --name-only | xargs grep -l -E "(sk-ant-|ANTHROPIC_API_KEY=|password\s*=\s*['\"][^'\"]+['\"])" 2>/dev/null; then
  echo "❌ 在暫存的變更中偵測到潛在機密"
  exit 1
fi

# 檢查過於寬鬆的檔案權限
for file in $(git diff --cached --name-only); do
  if [[ -f "$file" ]]; then
    perms=$(stat -f "%OLp" "$file" 2>/dev/null || stat -c "%a" "$file" 2>/dev/null)
    if [[ "$perms" == "777" || "$perms" == "666" ]]; then
      echo "❌ 檔案 $file 權限過於寬鬆：$perms"
      exit 1
    fi
  fi
done

echo "✅ 安全檢查通過"

程式碼審查指南

審查 AI 生成的程式碼時，檢查：

## AI 程式碼審查清單

### 輸入驗證
- [ ] 所有使用者輸入都已驗證
- [ ] 驗證使用白名單方式
- [ ] 存在伺服器端驗證（不只是客戶端）

### 認證與授權
- [ ] 處理器開頭有認證檢查
- [ ] 每個操作都驗證授權
- [ ] 沒有權限提升路徑

### 資料處理
- [ ] 敏感資料未被記錄
- [ ] 錯誤訊息不洩漏內部資訊
- [ ] PII 正確處理

### 依賴
- [ ] 沒有不必要的新依賴
- [ ] 依賴維護良好
- [ ] 沒有已知漏洞（npm audit）

5. 安全程式設計模式

輸入驗證

import { z } from 'zod';

// 定義嚴格的 schema
const UserInputSchema = z.object({
  email: z.string().email().max(255),
  name: z.string().min(1).max(100).regex(/^[a-zA-Z\s]+$/),
  age: z.number().int().min(0).max(150),
});

// 驗證所有輸入
function handleUserInput(input: unknown) {
  const result = UserInputSchema.safeParse(input);
  if (!result.success) {
    throw new ValidationError(result.error.message);
  }
  return result.data; // 型別安全且已驗證
}

SQL 注入預防

// ❌ 有漏洞
const query = `SELECT * FROM users WHERE email = '${email}'`;

// ✅ 安全 - 使用參數化查詢
const user = await prisma.user.findUnique({
  where: { email }
});

// ✅ 安全 - 使用預備語句
const user = await db.query(
  'SELECT * FROM users WHERE email = $1',
  [email]
);

XSS 預防

// ❌ 有漏洞 - 直接 HTML 注入
<div dangerouslySetInnerHTML={{ __html: userContent }} />

// ✅ 安全 - React 自動轉義
<div>{userContent}</div>

// ✅ 安全 - 如果需要 HTML，先消毒
import DOMPurify from 'dompurify';
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userContent) }} />

錯誤處理

// ❌ 有漏洞 - 暴露內部資訊
catch (error) {
  return res.status(500).json({ 
    error: error.message,
    stack: error.stack 
  });
}

// ✅ 安全 - 內部記錄，回傳通用訊息
catch (error) {
  logger.error('內部錯誤', { 
    error: error.message,
    stack: error.stack,
    requestId: req.id
  });
  return res.status(500).json({ 
    error: '發生內部錯誤',
    requestId: req.id // 供支援參考
  });
}

6. MCP 安全考量

僅使用受信任的 MCP 伺服器

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "/path/to/project"],
      "trustLevel": "limited"
    }
  }
}

上下文隔離

使用多個 MCP 伺服器時，考慮上下文隔離：

## MCP 安全指南

1. **最小化 MCP 伺服器** - 只啟用你需要的
2. **限定存取範圍** - 配置每個伺服器最小路徑
3. **定期稽核** - 檢視 MCP 伺服器存取日誌
4. **及時更新** - 保持 MCP 伺服器更新

網路感知 MCP

對於發出網路請求的 MCP 伺服器：

{
  "mcpServers": {
    "api-client": {
      "command": "node",
      "args": ["./mcp-api-client.js"],
      "env": {
        "ALLOWED_HOSTS": "api.example.com,api.trusted.com"
      }
    }
  }
}

7. 稽核與監控

會話記錄

啟用會話記錄以供安全稽核：

# 記錄所有 Claude Code 會話
export CLAUDE_LOG_LEVEL=info
export CLAUDE_LOG_FILE=~/.claude/sessions.log

存取監控

追蹤檔案存取模式：

## 安全監控清單

### 每日
- [ ] 檢視敏感目錄的任何存取
- [ ] 檢查異常的權限變更
- [ ] 驗證沒有未經審查的新依賴加入

### 每週
- [ ] 稽核會話日誌的異常
- [ ] 檢視權限配置
- [ ] 執行依賴漏洞掃描

### 每月
- [ ] 完整的 CLAUDE.md 安全檢視
- [ ] 更新權限拒絕清單
- [ ] 輪換任何已暴露的憑證

自動警報

設定安全事件監控：

# 監控敏感檔案存取嘗試
tail -f ~/.claude/sessions.log | grep -E "(\.env|secrets|credentials)" &

# 權限拒絕事件警報
tail -f ~/.claude/sessions.log | grep "permission denied" | while read line; do
  echo "安全警報: $line" | mail -s "Claude Code 安全警報" admin@example.com
done

8. 事件回應

如果憑證被暴露

## 憑證暴露回應

1. **立即**
   - 撤銷已暴露的憑證
   - 生成新憑證
   - 更新所有使用它的系統

2. **1 小時內**
   - 稽核日誌查看未授權使用
   - 檢查資料外洩
   - 通知安全團隊

3. **24 小時內**
   - 事後檢討
   - 更新程序以防止再次發生
   - 記錄學到的經驗

如果產生惡意程式碼

## 惡意程式碼回應

1. **不要執行** - 立即停止
2. **記錄** - 截圖並儲存程式碼
3. **回滾** - 還原任何已做的變更
4. **報告** - 通知你的安全團隊
5. **檢視** - 稽核最近的會話尋找模式

9. 團隊安全實踐

安全培訓主題

## Claude Code 使用者必修培訓

1. **權限模型**（30 分鐘）
   - 權限如何運作
   - 如何安全配置
   - 常見錯誤避免

2. **機密管理**（30 分鐘）
   - 永不寫死機密
   - 環境變數最佳實踐
   - 輪換程序

3. **AI 程式碼審查**（45 分鐘）
   - 要看什麼
   - 常見 AI 生成的漏洞
   - 審查清單使用

4. **事件回應**（30 分鐘）
   - 何時上報
   - 回應程序
   - 文件要求

安全冠軍

指定團隊成員為安全冠軍：

## 安全冠軍職責

- 每月檢視權限配置
- 進行安全培訓課程
- 安全問題第一回應者
- 維護安全文件
- 了解 Claude Code 安全功能更新

10. 持續改進

安全指標

隨時間追蹤這些指標：

指標	目標	測量
權限違規	0	每日日誌檢視
機密暴露	0	Pre-commit hooks
依賴漏洞	0 嚴重	每週 npm audit
安全事件	0	事件追蹤

定期檢視

## 每月安全檢視議程

1. [ ] 檢視權限配置
2. [ ] 稽核會話日誌
3. [ ] 更新拒絕清單新模式
4. [ ] 檢查 Claude Code 更新
5. [ ] 檢視並更新此清單
6. [ ] 與團隊分享學習

開始行動

今天（15 分鐘）

✅ 配置 .claude/settings.json 拒絕規則
✅ 驗證 .env 檔案權限正確（600）
✅ 將機密加入 .gitignore

本週（1 小時）

✅ 設定 pre-commit hooks
✅ 建立團隊安全指南
✅ 檢視 MCP 伺服器配置

本月（2 小時）

✅ 進行團隊安全培訓
✅ 建立監控和警報
✅ 記錄事件回應程序

重點摘要

最小權限 - 只授予必要的權限
縱深防禦 - 多層安全控制
永不信任，永遠驗證 - 驗證輸入，審查輸出
稽核一切 - 維護日誌並定期檢視
保持更新 - 保持 Claude Code 和依賴的更新

安全是持續的過程，不是一次性設定。將這些實踐融入你的日常工作流程，你就能在 AI 輔助下開發更安全的軟體。

安全實踐應根據你組織的特定要求和合規需求進行調整。

相關文章：Claude Code 安全優先開發、生產準備清單