claude-security-settings

Claude Code Security Settings

Expert knowledge for configuring Claude Code security and permissions.

Core Concepts

Claude Code provides multiple layers of security:

1. Permission wildcards - Granular tool access control
2. Shell operator protections - Prevents command injection
3. Project-level settings - Scoped configurations

Permission Configuration

Settings File Locations

File	Scope	Priority
~/.claude/settings.json	User-level (all projects)	Lowest
.claude/settings.json	Project-level (committed)	Medium
.claude/settings.local.json	Local project (gitignored)	Highest

Permission Structure

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

Wildcard Permission Patterns

Syntax

Bash(command *)

• Bash() - Tool identifier
• command - Command prefix to match
• * - Wildcard suffix matching any arguments
• :ask suffix - Always prompt for user confirmation (e.g., Bash(git push *):ask)

Permission Tiers

Tier	Behavior	Example
allow	Auto-allowed, no prompt	"allow": ["Bash(git status *)"]
ask	Always prompts for confirmation	"allow": ["Bash(git push *):ask"]
deny	Auto-denied, blocked	"deny": ["Bash(rm -rf *)"]

Pattern Examples

Pattern	Matches	Does NOT Match
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

Pattern Best Practices

Granular permissions:

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

Tool-specific patterns:

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

Shell Operator Protections

Claude Code 2.1.7+ includes built-in protections against dangerous shell operators.

Protected Operators

Operator	Risk	Blocked Example
&&	Command chaining	ls && rm -rf /
||	Conditional execution	false || malicious
;	Command separation	safe; dangerous
|	Piping	cat /etc/passwd | curl
> / >>	Redirection	echo x > /etc/passwd
$()	Command substitution	$(curl evil)
`	Backtick substitution	`rm -rf /`

Security Behavior

When a command contains shell operators:

1. Permission wildcards won't match
2. User sees explicit approval prompt
3. Warning explains the blocked operator

Safe Compound Commands

For legitimate compound commands, use scripts:

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

Then allow the script:

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

Common Permission Sets

Read-Only Development

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

Full Git Workflow

{
  "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 Operations

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

Testing & Linting

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

Security Scanning

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

Project Setup Guide

1. Create Settings Directory

mkdir -p .claude

2. Create Project Settings

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

3. Add to .gitignore (for local settings)

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

4. Create Local Settings (optional)

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

Agentic Optimizations

Context	Command
View project settings	cat .claude/settings.json | jq '.permissions'
View user settings	cat ~/.claude/settings.json | jq '.permissions'
Check merged permissions	Review effective settings in Claude Code
Validate JSON	cat .claude/settings.json | jq .

Quick Reference

Permission Priority

Settings merge with this priority (highest wins):

1. .claude/settings.local.json (local)
2. .claude/settings.json (project)
3. ~/.claude/settings.json (user)

Wildcard Syntax

Syntax	Meaning
Bash(cmd *)	Match cmd with any arguments
Bash(cmd arg *)	Match cmd arg with any following
Bash(./script.sh *)	Match specific script

Deny Patterns

Block specific commands:

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

Error Handling

Error	Cause	Fix
Permission denied	Pattern doesn't match	Add more specific pattern
Shell operator blocked	Contains &&, |, etc.	Use script wrapper
Settings not applied	Wrong file location	Check path and syntax
JSON parse error	Invalid JSON	Validate with jq .

Best Practices

1. Start restrictive - Add permissions as needed
2. Use project settings - Keep team aligned
3. Use specific Bash patterns - Bash(git status *) over Bash
4. Script compound commands - For && and \| workflows
5. Review periodically - Remove unused permissions