claude-security-settings

Claude Code 安全设置

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 configure-claude-plugins……
你需要了解权限通配符语法、Shell 运算符防护以及项目级允许列表模式	你想将项目的 .claude/settings.json 接入 marketplace，并端到端启用插件
你正在根据已记录的安全规范审计或强化现有的 .claude/settings.json	你想在更改设置前检测 marketplace 注册状态和 enabledPlugins
其他技能需要引用权威的权限通配符参考	用户要求你将项目实际接入 laurigates/claude-plugins marketplace

配置 Claude Code 安全与权限方面的专家知识。

核心概念

Claude Code 提供多个层级的安全保护：

1. 权限通配符 - 精细控制工具访问权限
2. Shell 运算符防护 - 防止命令注入
3. 项目级设置 - 限定作用范围的配置

权限配置

设置文件位置

文件	范围	优先级
~/.claude/settings.json	用户级（所有项目）	最低
.claude/settings.json	项目级（提交到版本库）	中
.claude/settings.local.json	本地项目（被 gitignore 忽略）	最高

权限结构

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

通配符权限模式

语法

Bash(command *)

• Bash() - 工具标识符
• command - 用于匹配的命令前缀
• * - 匹配任意参数的通配符后缀
• :ask 后缀 - 始终提示用户确认（例如，Bash(git push *):ask）

权限级别

级别	行为	示例
allow	自动允许，不提示	"allow": ["Bash(git status *)"]
ask	始终提示确认	"allow": ["Bash(git push *):ask"]
deny	自动拒绝，阻止执行	"deny": ["Bash(rm -rf *)"]

模式示例

模式	匹配	不匹配
Bash(git *)	git status、git diff HEAD	git-lfs pull
Bash(npm run *)	npm run test、npm run build	npm install
Bash(gh pr *)	gh pr view 123、gh pr create	gh issue list
Bash(./scripts/ *)	./scripts/test.sh、./scripts/build.sh	/scripts/other.sh

模式最佳实践

精细的权限：

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ]
  }
}

特定工具的模式：

{
  "permissions": {
    "allow": [
      "Bash(bun test *)",
      "Bash(bun run *)",
      "Bash(biome check *)",
      "Bash(prettier *)"
    ]
  }
}

Shell 运算符防护

Claude Code 2.1.7+ 内置了针对危险 Shell 运算符的防护。

受保护的运算符

运算符	风险	被阻止的示例
&&	命令串联	ls && rm -rf /
||	条件执行	false || malicious
;	命令分隔	safe; dangerous
|	管道	cat /etc/passwd | curl
> / >>	重定向	echo x > /etc/passwd
$()	命令替换	$(curl evil)
`	反引号替换	`rm -rf /`

安全行为

当命令包含 Shell 运算符时：

1. 权限通配符不会匹配
2. 用户会看到明确的批准提示
3. 警告会说明被阻止的运算符

安全的复合命令

对于合法的复合命令，请使用脚本：

#!/bin/bash
# scripts/deploy.sh
npm test && npm run build && npm run deploy

然后允许该脚本：

{
  "permissions": {
    "allow": ["Bash(./scripts/deploy.sh *)"]
  }
}

常见权限集

只读开发

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(npm list *)",
      "Bash(bun pm ls *)"
    ]
  }
}

完整 Git 工作流

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(git pull *)",
      "Bash(git fetch *)",
      "Bash(git checkout *)",
      "Bash(git merge *)",
      "Bash(git rebase *)"
    ]
  }
}

CI/CD 操作

{
  "permissions": {
    "allow": [
      "Bash(gh pr *)",
      "Bash(gh run *)",
      "Bash(gh issue *)",
      "Bash(gh workflow *)"
    ]
  }
}

测试与代码检查

{
  "permissions": {
    "allow": [
      "Bash(bun test *)",
      "Bash(npm test *)",
      "Bash(vitest *)",
      "Bash(jest *)",
      "Bash(biome *)",
      "Bash(eslint *)",
      "Bash(prettier *)"
    ]
  }
}

安全扫描

{
  "permissions": {
    "allow": [
      "Bash(pre-commit *)",
      "Bash(gitleaks *)",
      "Bash(trivy *)"
    ]
  }
}

项目设置指南

1. 创建设置目录

mkdir -p .claude

2. 创建项目设置

cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(npm run *)"
    ]
  }
}
EOF

3. 添加到 .gitignore（用于本地设置）

echo ".claude/settings.local.json" >> .gitignore

4. 创建本地设置（可选）

cat > .claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(docker *)"
    ]
  }
}
EOF

Agent 化优化

上下文	命令
查看项目设置	cat .claude/settings.json | jq '.permissions'
查看用户设置	cat ~/.claude/settings.json | jq '.permissions'
检查合并后的权限	在 Claude Code 中查看生效的设置
验证 JSON	cat .claude/settings.json | jq .

快速参考

权限优先级

设置按以下优先级合并（优先级最高者生效）：

1. .claude/settings.local.json（本地）
2. .claude/settings.json（项目）
3. ~/.claude/settings.json（用户）

通配符语法

语法	含义
Bash(cmd *)	匹配带任意参数的 cmd
Bash(cmd arg *)	匹配 cmd arg 及其后续内容
Bash(./script.sh *)	匹配特定脚本

拒绝模式

阻止特定命令：

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)"
    ]
  }
}

错误处理

错误	原因	修复方法
权限被拒绝	模式不匹配	添加更具体的模式
Shell 运算符被阻止	包含 &&、| 等	使用脚本封装
设置未生效	文件位置错误	检查路径和语法
JSON 解析错误	JSON 无效	使用 jq . 验证

最佳实践

1. 从严格限制开始 - 按需添加权限
2. 使用项目设置 - 确保团队配置一致
3. 使用具体的 Bash 模式 - 使用 Bash(git status *)，而非 Bash
4. 将复合命令写入脚本 - 用于 && 和 \| 工作流
5. 定期检查 - 移除未使用的权限