claude-security-settings

Claude Code Security Settings

When to Use This Skill

Use this skill when...	Use configure-claude-plugins instead when...
You need the permission-wildcard syntax, shell-operator protections, and project-level allowlist patterns	You want to wire a project's .claude/settings.json to the marketplace and enable plugins end-to-end
You are auditing or hardening an existing .claude/settings.json against the documented security conventions	You want runtime detection of marketplace enrollment and enabledPlugins before changing settings
Another skill needs to cite the canonical permission-wildcard reference	The user asked you to actually onboard a project to the laurigates/claude-plugins marketplace

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 *)"
    ]
  }
}

Flag-Scoped Deny Rules: Use the Space Form

When a deny rule targets a specific flag (a force-push backstop is the canonical case), write it in space form — the trailing * enforces a word boundary, so the prefix must be followed by a space or end-of-string and the rule stops at the exact flag:

{
  "permissions": {
    "deny": [
      "Bash(git push --force *)",
      "Bash(git push -f *)"
    ]
  }
}

Gotcha — colon form widens to longer flags. The :* suffix ("Bash(git push --force:*)") has been observed prefix-matching the raw command string, so it also matched git push --force-with-lease … — silently hard-blocking the safe recovery form that stacked-PR workflows depend on. Deny rules cannot be overridden except via bypassPermissions, so the widening is a hard block, not a prompt (laurigates/claude-plugins#2038, caught in laurigates/loractl#39). Current official docs state an end-of-pattern :* is equivalent to the trailing space form, but the equivalence is not version-pinned in the changelog and the widening was observed in practice — the space form's word-boundary semantics are explicit, stable, and match what the permission dialog itself writes when you approve a prefix.

When auditing or generating deny entries, flag any entry ending in a flag followed by :* (e.g. --force:*, -f:*) and rewrite it to the space form.

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 *)"
    ]
  }
}

Flag-scoped deny rules (blocking a specific flag such as --force) must use the space form, never :* — see "Flag-Scoped Deny Rules: Use the Space Form" above.

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