Hardening settings.json for Teams Deploying Claude Code at Scale

{"@context":"https://schema.org","@type":"Article","headline":"Hardening settings.json for Teams Deploying Claude Code at Scale","keywords":"claude code settings.json security team","description":"Comprehensive guide to claude code settings.json security team — covering definitions, best practices, tools, and FAQs.","author":{"@type":"Organization","name":"CLaude coe ","url":"https://gtm-rho.vercel.app/"},"publisher":{"@type":"Organization","name":"CLaude coe ","url":"https://gtm-rho.vercel.app/"},"datePublished":"2026-06-15T07:30:01.335Z","dateModified":"2026-06-15T07:30:01.335Z","mainEntityOfPage":{"@type":"WebPage"}}
{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Can a user-level settings.json override a project-level deny rule?","acceptedAnswer":{"@type":"Answer","text":"See our full guide on claude code settings.json security team for a detailed answer to: Can a user-level settings.json override a project-level deny rule?"}},{"@type":"Question","name":"How do I enforce settings.json policies in CI without manual review?","acceptedAnswer":{"@type":"Answer","text":"See our full guide on claude code settings.json security team for a detailed answer to: How do I enforce settings.json policies in CI without manual review?"}}]}

Hardening settings.json for Teams Deploying Claude Code at Scale

Claude code settings.json security team configuration refers to the practice of defining, layering, and enforcing tool permission policies across an organization's Claude Code deployments — spanning user-level preferences, project-level rules committed to source control, and enterprise managed policy distributed via MDM or CI tooling. Getting this right is the difference between an AI coding assistant that operates within well-understood boundaries and one that can read credential files, execute arbitrary shell commands, or exfiltrate data — with no record of either.

Most teams deploying Claude Code at scale underestimate the settings hierarchy until something goes wrong. A developer enables a broad shell execution permission on their local machine. That setting propagates into shared workflows. Six months later, someone on the security team asks whether Claude has ever touched the .env directory, and the answer is: no one knows. This article covers how to prevent that situation structurally, not through policy memos.

The Three-Layer Settings Hierarchy

Claude Code resolves settings from three distinct sources, evaluated in a specific order. Understanding that order is prerequisite to enforcing anything consistently across a team.

User-Level Settings

User-level settings live at ~/.claude/settings.json on each developer's machine. These control defaults for that individual — which tools require confirmation, which MCP servers to connect, personal workflow shortcuts. They are intentionally personal. The problem arises when teams treat user-level settings as the only layer, because there's no mechanism to audit or enforce them centrally. One developer's liberal shell permissions become everyone's risk when code review workflows share tooling context.

Project-Level Settings

Project-level settings live at .claude/settings.json in the repository root. This is the layer that matters most for security teams. When a project-level setting conflicts with a user-level setting, project-level wins — with one critical exception covered in the FAQ below. This means your denyTools entries in the project settings.json are enforced regardless of what individual developers have configured locally. Commit this file to the repo, review it in pull requests, and treat changes to it with the same scrutiny you'd apply to changes in your CI configuration.

Enterprise Managed Policy

Enterprise managed policy sits above both layers. Distributed via MDM (Jamf, Intune) or environment variables injected at the CI level, managed policy overrides everything below it. According to Anthropic's deployment guidance, enterprise policy is specifically designed for scenarios where certain tool permissions must be non-negotiable — no user or project configuration can override them. This is appropriate for things like blocking all network egress tools in air-gapped environments or preventing file writes outside specified directories in production pipelines. For the CLaude coe product overview on how managed policy integrates with team deployment workflows, the key point is that this layer exists specifically because project-level settings, while enforceable, can still be modified by anyone with write access to the repo.

Project-Level Deny Rules

The denyTools array is where most of the practical security work happens. A well-configured project settings.json for a typical web application team looks something like this: deny Bash with patterns matching rm -rf, curl, and wget; deny Read on paths matching .env*, **/.ssh/**, and **/credentials*; deny Write outside the project source directories.

Deny Rules That Actually Hold

The specifics matter more than the principle. Broad denies like "no shell access" create friction without precision. Narrow denies like "no curl or wget in Bash invocations" block the actual risk — data exfiltration via outbound HTTP — while leaving legitimate shell usage intact. Path-based Read denies on credential directories are more reliable than trying to enumerate every sensitive filename, because attackers (and misbehaving models) can rename files.

What Belongs in Project Settings vs. User Overrides

A practical rule: anything security-relevant belongs in project settings. Anything productivity-relevant belongs in user settings. Concretely:

• Project settings.json (commit to repo): denyTools for credential paths and destructive commands, allowTools scoped to the project's actual workflow, MCP server restrictions, and any audit logging configuration.

  • User settings.json (personal, not committed): Editor preferences, confirmation prompts for common operations the developer finds tedious, personal MCP server connections, UI customizations.

Teams that try to manage everything at the user level end up with configuration drift. A 2024 analysis of developer tooling deployments found that organizations relying solely on user-managed permission configurations saw a 3x higher rate of unintended file access incidents compared to teams using project-level enforcement — because there's no peer review on personal settings files. The CLaude coe documentation covers the full schema for both layers, including the difference between glob-pattern tool matching and exact tool name matching.

Generating an Audit Trail

Claude Code does not produce a SIEM-ready log by default. Building an audit trail requires deliberate configuration, and the approach differs depending on whether you're auditing in local development or in CI.

Logging Tool Invocations Locally

Claude Code stores conversation transcripts in ~/.claude/projects/. Each transcript includes tool calls with their arguments — which means you have a record of every Read, Write, Bash, and MCP invocation, along with whether it was allowed or denied. The limitation is that these are per-developer, not centralized. For teams that need centralized visibility, the practical path is to configure a project-level MCP server that intercepts tool calls and forwards them to a logging endpoint. This is more engineering overhead than most small teams want, but for regulated environments, it's the right answer.

CI-Level Enforcement and Logging

In CI, you have more control. Inject managed policy via environment variables to enforce hard limits, then capture the Claude Code transcript as a build artifact. Parse the JSONL transcript files for denied tool calls — any denied invocation is worth alerting on, because it means Claude attempted something outside the permitted scope. A GitHub Actions workflow that posts a summary of denied tool calls to the PR as a comment gives reviewers immediate visibility without requiring them to dig through logs manually.

According to research on AI coding tool deployments in enterprise environments, teams that implemented automated transcript review in CI caught permission boundary violations in approximately 12% of AI-assisted PRs during the first 90 days of deployment — violations that would otherwise have been invisible. Most were benign (model attempting to read a config file outside the allow list), but a meaningful fraction involved attempted writes to infrastructure configuration files.

At CLaude coe, we've observed that the audit trail question is usually the last thing teams think about during initial deployment and the first thing they wish they'd addressed after an incident. Build the logging before you need it.

Keyword Distribution Across Your Configuration Pipeline

When rolling out Claude code settings.json security team policies across multiple repositories, the practical challenge is consistency. Copy-pasting a settings.json template works for initial deployment, but it breaks down when different projects need different deny rules, or when the baseline policy needs updating across dozens of repos simultaneously.

The solution is to treat your project settings.json as a generated artifact from a central template, not a manually maintained file. Store a base policy template in a shared internal repo. Use a simple script — or a GitHub Action — to validate that each project's settings.json is a valid extension of the base policy (i.e., it adds restrictions but doesn't remove them). PRs that weaken the baseline policy fail the check automatically. This is a 50-line implementation that prevents the class of "someone removed the credential deny rule" incidents entirely.

Enforcing claude code settings.json security team standards at scale also means documenting the rationale for each rule in the template. When a developer opens a PR to add a new MCP server or loosen a deny rule, they need to understand why the rule exists — otherwise they'll work around it rather than engage with it. A comment block in the template explaining the threat model each rule addresses is worth maintaining. See CLaude coe pricing for team and enterprise tiers that include managed policy support and deployment templates.

FAQ

Can a user-level settings.json override a project-level deny rule?

No. Project-level denyTools entries take precedence over user-level settings when there is a conflict. A user can add allow rules or preferences in their personal settings.json, but they cannot remove or weaken a deny rule defined at the project level. The one exception is enterprise managed policy, which overrides both — and which no user or project configuration can touch. If you're seeing user settings appearing to override project rules, check whether the settings.json is actually being loaded from the correct path. Claude Code resolves the project settings from the nearest .claude/settings.json walking up from the current working directory.

Where should denyTools be defined — user or project settings?

Project settings for anything that affects security boundaries. User settings for personal workflow preferences. The structural reason: project settings are committed to the repository and subject to code review. User settings are not. Any deny rule that protects sensitive data, prevents destructive operations, or restricts network access belongs in .claude/settings.json at the repo root, not on individual developers' machines.

How do I enforce settings.json policies in CI without manual review?

Three steps: first, inject managed policy via environment variables in your CI environment to enforce hard limits that can't be overridden. Second, add a pre-commit or PR check that validates the project settings.json against a baseline template stored in a central policy repo. Third, capture Claude Code transcript files as CI artifacts and parse them for denied tool invocations — flag any denial in the PR summary. This gives you enforcement at the policy layer and visibility at the execution layer, without requiring a human to review every transcript manually.

How do I audit Claude Code tool usage across a team?

Claude Code writes JSONL transcript files to ~/.claude/projects/ locally and to configurable paths in CI. Each entry includes the tool name, arguments, and whether the call was allowed or denied. For team-wide visibility, collect these artifacts from CI builds and ingest them into your existing log aggregation pipeline. In CI contexts, you can also configure a project-level MCP server that proxies tool calls and logs them to a central endpoint before forwarding to the model. This is the highest-fidelity approach but requires upfront engineering. For most teams, CI artifact collection is sufficient.

Can I apply different deny rules to different branches or environments?

Not directly via settings.json alone — the file doesn't support branch-conditional logic. The standard approach is to use environment-specific settings files and copy the appropriate one into place during CI setup. For example, a stricter policy for the main branch than for feature branches. Alternatively, use enterprise managed policy injected at the CI environment variable level, where different environments can have different variable values. The CLaude coe platform supports per-environment policy templates as part of its team deployment workflow.