Permissions and Security

Claude Code features a multi-layered permission system that controls every action the agent takes on your machine. Mastering the configuration of permission modes, allow/deny rules, and sandboxing protects you against unauthorized executions and prompt injections. This guide details how to secure your Claude Code environment step by step.

Claude Code permissions and security refers to the set of mechanisms that regulate the actions an AI agent can execute on your workstation. Claude Code offers several permission mechanisms, a granular rule system in settings.json, and native sandboxing via Seatbelt (macOS) and bubblewrap (Linux). many security incidents related to AI agents stem from misconfigured permissions.

How do Claude Code's permission modes work?

Claude Code offers 6 permission modes via the --permission-mode flag that determine the level of autonomy granted to the agent. Each mode corresponds to a specific use case, from the most restrictive to the most permissive.

default mode is the default mode. The agent asks for your confirmation before every sensitive operation: file writing, shell command execution, network call. This mode is suitable for initial sessions and getting familiar with the tool.

acceptEdits mode automatically approves file edits, and it also auto-approves common in-scope filesystem commands such as mkdir, touch, mv, cp, rm, and sed. Other shell commands still require your validation. This mode speeds up routine code work.

plan mode is an analysis-only mode: Claude Code shows an action plan and asks for confirmation before executing. This mode is suited to code review and architecture decisions.

auto mode uses an LLM classifier to automatically decide which actions are safe. It is a research preview that requires Claude Code v2.1.83+. On the Anthropic API it works with Opus 4.6+ or Sonnet 4.6 and is available by default. On Amazon Bedrock, Google Vertex AI, and Microsoft Foundry it is off by default and requires Opus 4.7/4.8 plus the CLAUDE_CODE_ENABLE_AUTO_MODE=1 environment variable.

dontAsk mode auto-denies any tool not pre-approved via your allow rules or /permissions (rules that would normally prompt via ask are denied rather than prompted). Read-only operations still run.

bypassPermissions mode (--dangerously-skip-permissions) removes all confirmations. Every action executes immediately. Reserve this mode for isolated environments (Docker containers, CI/CD) where no sensitive data is exposed.

In session, Shift+Tab or Alt+M cycles through available permission modes without restarting Claude Code.

To switch between modes, use the --permission-mode flag at launch or Shift+Tab / Alt+M in session:

# Default mode
claude

# acceptEdits mode
claude --permission-mode acceptEdits

# Plan mode (analysis before action)
claude --permission-mode plan

# Auto mode (LLM classifier, research preview, Anthropic API)
claude --permission-mode auto

# Bypass mode (CI/CD only)
claude --dangerously-skip-permissions

You can also set the default mode in settings.json with "defaultMode": "plan".

To dive deeper into each mode with hands-on exercises, check out the permissions and security tutorial that guides you step by step. If you are just getting started, the quickstart guide lets you configure your permissions in under 5 minutes.

Key takeaway: default mode is suitable for the vast majority of daily use cases; only switch to bypassPermissions in a disposable environment. Use Shift+Tab or Alt+M to cycle through modes in session.

How to configure allow/deny rules in settings.json?

The settings.json file is the heart of Claude Code's security configuration. It contains granular rules that allow or block specific tools, with or without pattern restrictions.

Open your configuration file in your editor (or run /config in session):

$EDITOR ~/.claude/settings.json

The basic structure contains three main keys: allow, deny, and ask. Each rule targets a specific tool and can include a pattern to filter arguments.

{
 "permissions": {
 "allow": [
 "Read",
 "Write",
 "Bash(git *)",
 "Bash(npm test *)",
 "Bash(npm run *)"
 ],
 "deny": [
 "Bash(rm -rf *)",
 "Bash(curl *)",
 "Bash(wget *)"
 ],
 "ask": [
 "Bash(git push *)"
 ]
 }
}

deny rules take priority over allow rules. The ask list forces a confirmation even if the tool would normally be auto-approved. If a command matches both an allow and a deny rule, it will be blocked. In practice, this hierarchy lets you create "allow everything except" policies.

Each Bash command needs its own rule: write Bash(npm test ) and Bash(npm run ) as separate entries rather than combining them. The characters |, &&, and ; are not pattern separators; Claude Code treats them as compound-command separators, and each subcommand must match a rule independently.

Specifically, you can define per-project rules by placing a .claude/settings.json file at the repository root. Project rules merge with global rules, and project deny rules are added to global deny rules.

{
 "permissions": {
 "allow": [
 "Bash(docker compose *)",
 "Bash(make *)"
 ],
 "deny": [
 "Bash(docker push *)"
 ]
 }
}

To check your current configuration, consult the permissions cheatsheet which summarizes all rule syntaxes. The permissions and security FAQ answers common questions about rule conflicts.

Key takeaway: always place destructive commands (rm, drop, push --force) in the deny list, even if you are working in Normal mode.

Why is sandboxing essential for Claude Code?

Sandboxing isolates the processes launched by Claude Code from the rest of your system. Without a sandbox, a malicious command injected via a prompt could access your personal files, SSH keys, or API tokens.

Claude Code uses Seatbelt on macOS and bubblewrap on Linux. These technologies limit the system calls available to child processes. In practice, the sandbox blocks access to directories outside the project, unauthorized network sockets, and system peripherals.

On macOS, Seatbelt applies a sandbox profile that restricts file system access. Only the project directories and necessary dependencies are accessible. Sandboxing is opt-in: enable it with the /sandbox panel in session, or set "sandbox": { "enabled": true } in settings.json to turn it on across all your projects. On macOS there is nothing extra to install, since Seatbelt is built in.

On Linux, bubblewrap creates an isolated user namespace. The sandboxed process sees a minimal file system with only explicitly authorized mounts, and its startup overhead is minimal. On Linux and WSL2 the sandbox relies on two packages you must install first: bubblewrap (filesystem isolation) and socat (network relay).

To diagnose a sandbox issue, the troubleshooting guide helps you identify common errors. You can also consult the complete Claude Code guide to understand the overall security architecture.

By isolating child processes and restricting their system calls, sandboxing significantly reduces the attack surface that a prompt injection could exploit.

Key takeaway: sandboxing is opt-in via "sandbox": { "enabled": true } in settings.json (toggle it in session with /sandbox). Enable it on any machine that holds sensitive data.

How to protect against prompt injections in Claude Code?

A prompt injection occurs when malicious content in a file or API response manipulates the agent's behavior. Claude Code integrates several layers of defense against this attack vector.

The first defense is the permission system itself. Even if an injected prompt asks the agent to execute rm -rf /, Normal mode will require your confirmation. Configure explicit deny rules for destructive commands.

The second layer is automatic detection. Claude Code analyzes tool results and flags suspicious content. When the agent detects an injection attempt, it displays a warning and suspends execution.

Here is how to strengthen your protection in practice:

1. Enable Normal mode for any session involving unverified files
2. Add deny rules for network commands (curl, wget, nc)
3. Limit accessible directories via the sandbox
4. Check the .claude/settings.json files of cloned repositories before using them
5. Inspect the CLAUDE.md file content of each project

# Check a cloned project's CLAUDE.md before launching Claude Code
cat CLAUDE.md
# Check the project settings
cat .claude/settings.json

Injection attempts frequently target shell commands. Systematically block outbound network commands in your deny rules to reduce this risk.

The CLAUDE.md file can itself be an injection vector. Before working on an external repository, read its content and verify that it does not contain hidden instructions. To understand how the memory system works, consult the CLAUDE.md guide.

The security checklist gives you a complete list of checks to perform before each session on an unknown repository.

Key takeaway: permissions + sandbox + your vigilance on unverified files form an effective defense triangle against injections.

What essential settings should you configure in settings.json for security?

The settings.json file accepts several security parameters beyond simple allow/deny rules. Here are the settings every developer should know.

Configure allow/deny rules to precisely control which tools are authorized:

{
 "permissions": {
 "allow": ["Read", "Bash(git *)"],
 "deny": ["Bash(rm -rf *)"]
 }
}

Sandboxing is configurable in settings.json via the sandbox key:

{
 "permissions": {
 "allow": ["Read", "Bash(git *)"],
 "deny": ["Bash(rm -rf *)"]
 },
 "sandbox": {
 "enabled": true,
 "filesystem": {
 "allowRead": ["/var/myapp", "/tmp/builds"]
 }
 }
}

The sandbox.enabled key enables or disables sandboxing (Seatbelt on macOS, bubblewrap on Linux). The sandbox.filesystem keys control file access: allowRead and allowWrite grant access to directories beyond the working directory, while denyRead and denyWrite explicitly block paths.

The settings.json file also supports hooks that intercept agent events:

{
 "hooks": {
 "PreToolUse": [
 {
  "matcher": "Bash",
  "hooks": [
  {"type": "command", "command": "echo 'Bash called'", "timeout": 5000}
  ]
 }
 ],
 "PostToolUse": [],
 "UserPromptSubmit": [],
 "SessionStart": [],
 "Stop": [],
 "Notification": []
 }
}

Hooks support the events PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, and Notification. Each hook can use a matcher (regex) and an if field for fine-grained filtering. Hook types are: command, http, mcp_tool, prompt, and agent (five types). Exit codes determine behavior: 0 = success/no objection (the normal permission flow still applies), 2 = block (stderr is returned to Claude), any other code = non-blocking error (logged, and the action proceeds).

The configuration hierarchy follows several levels (from highest to lowest priority):

1. Managed/Policy: organization policy set by the administrator. Highest priority, can never be overridden by any other level
2. Command-line arguments: flags passed at launch (--permission-mode, --allowedTools, etc.)
3. Local project: .claude/settings.local.json, ignored by git, specific to your machine
4. Shared project: .claude/settings.json at the repository root, versioned with the code
5. Global/User: ~/.claude/settings.json, applies to all projects, lowest priority

Deny rules accumulate across levels: a global deny rule can never be overridden by a project allow rule. This behavior ensures that your personal safeguards remain active regardless of the project.

To discover advanced configuration tips, consult the permissions and security tips page. If you work in a team, the context management guide explains how to share a consistent configuration.

Key takeaway: combine strict deny rules with automatic sandboxing for maximum security on sensitive projects.

How to audit and monitor Claude Code actions?

Monitoring the agent's actions is just as essential as configuring permissions. Claude Code stores session transcripts under ~/.claude/projects/, which you can inspect to review the tools and commands the agent ran during a session.

Locate the most recent session files:

ls -lt ~/.claude/projects/

Browsing these transcripts lets you trace which tools were used and which commands were run, so you can spot any suspicious activity. Making this review a regular habit is enough to catch anomalies early.

Agentic coding introduces specific risks because the agent makes autonomous decisions. Regularly examine command patterns to verify that the agent has not developed unexpected behaviors.

For a first hands-on experience with the tool, the installation and first launch guide covers the complete setup. You can then follow the your first conversations guide to learn how to interact with the agent safely.

SFEIR Institute offers the one-day Claude Code training that includes hands-on labs on permission configuration and sandboxing. To go further, the 2-day AI-Augmented Developer training covers secure integration of AI agents into your development workflows, with exercises on allow/deny rules and injection detection.

Key takeaway: audit your logs at least once a week and immediately block any unrecognized command pattern.

Can Claude Code be used safely in a CI/CD pipeline?

Integrating Claude Code into a CI/CD pipeline requires enhanced security configuration. The agent runs without human supervision, making deny rules and sandboxing critical.

Launch Claude Code in headless mode with restricted permissions:

claude --permission-mode dontAsk --allowedTools "Read,Edit,Bash(npm test *),Bash(npm run build *)" \
 -p "Fix the failing tests"

Use --permission-mode dontAsk with an explicit --allowedTools list so that only the listed tools run. Avoid --dangerously-skip-permissions here: bypass mode skips the permission layer entirely, so the --allowedTools list would no longer restrict what the agent can execute.

In CI/CD mode, here are the best practices recommended by SFEIR Institute:

1. Enable bypass mode only in an ephemeral container
2. Restrict authorized tools to the strict minimum via --allowedTools
3. Disable network access in the sandbox
4. Limit the timeout to 5 minutes (300,000 ms) to avoid blocking
5. Archive the logs from each execution for audit

The container must be destroyed after each execution. No secrets should be mounted in plaintext. Use environment variables injected by your secrets manager (Vault, AWS Secrets Manager).

In practice, scope each pipeline run to a focused task and bound it with a timeout so it stays predictable and auditable.

The one-day AI-Augmented Developer - Advanced training specifically covers CI/CD integration of AI agents, with labs on securing automated pipelines and secrets management.

Key takeaway: in CI/CD, treat Claude Code like any untrusted process (ephemeral container, minimal permissions, archived logs).

What are the most common security pitfalls to avoid?

Certain mistakes regularly occur among developers configuring Claude Code for the first time. Here are the 5 most common pitfalls and how to avoid them.

Pitfall 1: leaving Bypass mode enabled locally. This mode disables all protections. Public repositories are known to contain malicious CLAUDE.md files that exploit this mode. Systematically switch back to Normal mode after your CI/CD sessions.

Pitfall 2: forgetting to deny network commands. By default, curl, wget, and nc are allowed in Normal mode (with confirmation). In Auto-accept mode, they execute without prompting. Add these commands to your global deny list.

Pitfall 3: sharing a settings.json with overly permissive allow rules. A Bash() in the project allow rules authorizes all shell commands. Prefer specific patterns like Bash(npm ) or Bash(git *).

Pitfall 4: ignoring security updates. Claude Code receives regular security patches, so keep it up to date. Avoid npm update -g, which respects the original semver range and may not upgrade. Update with:

npm install -g @anthropic-ai/claude-code@latest

You can also run claude update to update an existing installation.

Pitfall 5: not checking the CLAUDE.md files of submodules. Git submodules can contain their own configuration files. Inspect each submodule before starting a session.

For an exhaustive list of checks, the security checklist covers all critical points. You will also find solutions to common problems in the troubleshooting guide.

Key takeaway: the majority of security incidents come from overly permissive configurations left in place out of habit. Audit your settings every month.